Adición de un webhook de evento de reserva
En este artículo
Al agregar un webhook de evento de reserva se envían los detalles de la reserva en formato JSON a una URL cada vez que se crea, modifica, cancela o restablece una reserva.
Detalles clave
- Conocimientos técnicos requeridos: Configurar y administrar webhooks requiere experiencia técnica. Consulta a un desarrollador web si es necesario.
- Activación: Activa el webhook del evento de reserva en Configuración -> Cuenta Sirvoy -> Webhook de evento de reserva.
- Límite del webhook: Solo puede haber un webhook activo por cuenta de Sirvoy.
- Activadores de callback: Un webhook de evento de reserva envía un callback a una URL específica cada vez que se crea, modifica, cancela o restablece una reserva.
Requerimientos técnicos:
- Código de respuesta: El servidor receptor debe responder con un código de estado «200 OK». De lo contrario, la llamada se reintentará diez veces con un back-off exponencial de hasta 10 veces antes de descartarse.
- HTTPS y TLS: Solo admitimos HTTPS utilizando TLS versión 1.2 o superior para garantizar la privacidad y confidencialidad de los datos. Asegúrate de que tu certificado HTTPS sea válido; de lo contrario no se enviarán datos.
- Health check: Tu servidor debe responder a las solicitudes HTTP GET con «200 OK» para realizar los health checks. No se enviarán datos mediante HTTP GET, pero esto garantiza que tu endpoint está activo.
Gestión de notificaciones de reservas y fallos de webhook
Enviamos una notificación por cada cambio en la reserva. Los eventos pueden estar en desorden en la entrega. Utiliza la marca de tiempo «generatedAt» para crear una línea de tiempo precisa de los eventos. Cada notificación contendrá la representación JSON completa de la reserva en ese momento.
Si tu endpoint comienza a fallar y no devuelve códigos de estado exitosos a nuestras llamadas, te lo notificaremos por correo electrónico. Si continúa fallando durante una semana, el webhook se eliminará después de una notificación final.
IP Whitelisting
Para garantizar callbacks de webhook exitosas, permite los siguientes rangos de IP en tu firewall:
- 34.243.166.60
- 52.18.11.99
- 63.34.80.48
- 54.194.0.85
- 2a05:d018:e34:5300::/56
Los servidores que hacen las callbacks son dual-stack, con conectividad tanto IPv4 como IPv6. Si agregas direcciones IPv4 e IPv6 a tu nombre de dominio, la callback se realizará al primer servidor que responda.
Ejemplos de formato JSON
Ejemplo de estructura JSON para nuevas reservas:
{
"version": "2.0",
"generatedAt": "2024-05-31T12:11:53.639+00:00",
"event": "new",
"propertyId": 1,
"bookingId": 26006,
"channelBookingId": null,
"bookingDate": "2024-05-31T12:09:16+00:00",
"arrivalDate": "2024-06-01",
"departureDate": "2024-06-04",
"cancelled": false,
"eta": "10:00",
"totalAdults": 4,
"guest": {
"firstName": "John",
"lastName": "Doe",
"businessName": "Acme",
"address": "Fancy street",
"postcode": "11-111",
"city": "York",
"state": "NY",
"country": "US",
"phone": "+16033336666",
"email": "guest@email.com",
"passportNo": "XX11122223333",
"language": "en",
"message": "Additional comment added by guest"
},
"guestReference": "2103001",
"internalComment": null,
"couponCode": null,
"bookingSource": "Front desk",
"bookingIsCheckedIn": false,
"bookingIsCheckedOut": false,
"bookingIsConfirmed": true,
"customFields": [
{
"name": "Custom text field name",
"value": "text added by guest"
},
{
"name": "Custom checkbox unchecked",
"value": false
},
{
"name": "Custom checkbox checked",
"value": true
}
],
"rooms": [
{
"RoomTypeName": "Basic room",
"RoomTypeDescription": "Basic room",
"RoomName": "101",
"RoomId": 2,
"arrivalDate": "2024-06-01",
"departureDate": "2024-06-04",
"adults": 2,
"quantity": 3,
"price": 100,
"roomTotal": 300,
"guestName": null,
"comment": null,
"ledgerAccount": null
},
{
"RoomTypeName": "Fancy room",
"RoomTypeDescription": "Fancy room",
"RoomName": "182",
"RoomId": 83,
"arrivalDate": "2024-06-01",
"departureDate": "2024-06-04",
"adults": 2,
"quantity": 3,
"price": 100,
"roomTotal": 300,
"guestName": null,
"comment": null,
"ledgerAccount": null
}
],
"additionalItems": [
{
"description": "Breakfast",
"specificDate": null,
"quantity": 12,
"price": 20,
"itemTotal": 240,
"ledgerAccount": null
}
],
"bookedCategory": null,
"currency": "EUR",
"totalPrice": 840,
"totalSurcharges": 84,
"totalPriceIncludingSurcharges": 924,
"payments": [],
"invoices": []
}
Ejemplo de estructura JSON para crear un recibo de caja y aplicar un pago a una factura:
{
"version": "2.0",
"generatedAt": "2024-05-31T12:15:23.895+00:00",
"event": "modified",
"propertyId": 1,
"bookingId": 26006,
"channelBookingId": null,
"bookingDate": "2024-05-31T12:09:16+00:00",
"arrivalDate": "2024-06-01",
"departureDate": "2024-06-04",
"cancelled": false,
"eta": "10:00",
"totalAdults": 4,
"guest": {
"firstName": "John",
"lastName": "Doe",
"businessName": "Acme",
"address": "Fancy street",
"postcode": "11-111",
"city": "York",
"state": "NY",
"country": "US",
"phone": "+16033336666",
"email": "guest@email.com",
"passportNo": "XX11122223333",
"language": "en",
"message": "Additional comment added by guest"
},
"guestReference": "2103001",
"internalComment": null,
"couponCode": null,
"bookingSource": "Front desk",
"bookingIsCheckedIn": false,
"bookingIsCheckedOut": false,
"bookingIsConfirmed": true,
"customFields": [
{
"name": "Custom text field name",
"value": "text added by guest"
},
{
"name": "Custom checkbox unchecked",
"value": false
},
{
"name": "Custom checkbox checked",
"value": true
}
],
"rooms": [
{
"RoomTypeName": "Basic room",
"RoomTypeDescription": "Basic room",
"RoomName": "101",
"RoomId": 2,
"arrivalDate": "2024-06-01",
"departureDate": "2024-06-04",
"adults": 2,
"quantity": 3,
"price": 100,
"roomTotal": 300,
"guestName": null,
"comment": null,
"ledgerAccount": null
},
{
"RoomTypeName": "Fancy room",
"RoomTypeDescription": "Fancy room",
"RoomName": "182",
"RoomId": 83,
"arrivalDate": "2024-06-01",
"departureDate": "2024-06-04",
"adults": 2,
"quantity": 3,
"price": 100,
"roomTotal": 300,
"guestName": null,
"comment": null,
"ledgerAccount": null
}
],
"additionalItems": [
{
"description": "Breakfast",
"specificDate": null,
"quantity": 12,
"price": 20,
"itemTotal": 240,
"ledgerAccount": null
}
],
"bookedCategory": null,
"currency": "EUR",
"totalPrice": 840,
"totalSurcharges": 84,
"totalPriceIncludingSurcharges": 924,
"payments": [],
"invoices": [
{
"invoiceNumber": "41002",
"invoiceDate": "2024-06-01",
"dueDate": "2024-06-01",
"receiver": "Acme",
"address": [
"John Doe",
"Fancy street",
"York, NY 11-111",
"United States"
],
"roundingAmount": 0,
"invoiceTotal": 924,
"originInvoice": null,
"invoiceRows": [
{
"quantity": 3,
"price": 100,
"rowTotal": 300,
"ledgerAccount": "100",
"rowText": "Basic room",
"vatRate": 0,
"vatAmount": 0,
"bookingId": 26006
},
{
"quantity": 3,
"price": 100,
"rowTotal": 300,
"ledgerAccount": "100",
"rowText": "Fancy room",
"vatRate": 0,
"vatAmount": 0,
"bookingId": 26006
},
{
"quantity": 12,
"price": 20,
"rowTotal": 240,
"ledgerAccount": "200",
"rowText": "Breakfast",
"vatRate": 0,
"vatAmount": 0,
"bookingId": 26006
},
{
"quantity": 1,
"price": 84,
"rowTotal": 84,
"ledgerAccount": "300",
"rowText": "surcharge",
"vatRate": 0,
"vatAmount": 0,
"bookingId": 26006
}
],
"payments": [
{
"paymentId": 28,
"createdAt": "2024-05-31T12:15:09+00:00",
"valueDate": "2024-06-01",
"amount": 924,
"ledgerAccount": "3606",
"paymentReference": null,
"comment": null
}
]
}
]
}
Para cualquier pregunta o ayuda adicional, comunícate con nuestro equipo de soporte.