3. Puntos de conexión de IAPI y Swagger

1. Una vez que recibas las credenciales, te recomendamos probar la API usando nuestro Swagger, disponible en la siguiente URL, para familiarizarte con la API

https://app.swaggerhub.com/apis/PriceLabs/price-labs_connector/1.0.0

2. La URL base para todas las llamadas a la API está disponible en el Swagger mencionado anteriormente.

4. Seguridad
   

1. Solicitudes del PMS a PriceLabs:

Se requieren dos encabezados de seguridad. El X-INTEGRATION-TOKEN es inicialmente proporcionado por PriceLabs y puede regenerarse por medio de un endpoint por el PMS. El X-INTEGRATION-NAME es proporcionado por PriceLabs y permanece constante.

2. Solicitudes de PriceLabs al PMS

Los siguientes componentes se combinarán en dos firmas: un set de encabezados, una cadena de versión y el cuerpo en formato JSON. Estos se firmarán usando tu token de integración.

Valores de Ejemplo:

version = “v1”

headers["X-SOURCE"] = “request_source”

headers["X-PL-TIMESTAMP"] = “request_timestamp”

headers["X-PL-REQUESTID"] = “request_id”

body = "{\"test\":\"body\"}"

Estos valores de ejemplo se combinarían de la siguiente manera en pseudocódigo

api_token = "26eea40c-f297-4b68-aeb8-bb626fe4b5e5"

header_components = "v1:request_source:request_timestamp:request_id"

signed_headers = "v1." + sha256_sign( header_components, api_token )

body_components = signed_headers + "{\"test\":\"body\"}"

signed_body = sha256_sign( body_components, api_token )

Y se proporcionarán como los siguientes encabezados:

headers["X-PL-SIGNED-HEADERS"] = signed_headers

headers["X-PL-SIGNED-BODY"] = signed_body

Después de calcular la firma de lo que recibes, puedes compararla con los encabezados de firma proporcionados en la solicitud.

Para verificar tu implementación, se proporcionan las firmas de los ejemplos:

headers["X-PL-SIGNED-HEADERS"]="v1.567425e5a91b576652d591cabea78e9e1fe017d1c67e2d812ae2859c355965ff"

headers["X-PL-SIGNED-BODY"]="5011b348ff6691bb9cbe93f85ffb836ef0e3fec45a4ce924f5940cb1aa4071b8"

La versión se puede identificar en el encabezado dividiéndolo en el primer ‘.’, donde la cadena antes de este punto es la versión, como v1 en el encabezado firmado mencionado anteriormente.

5. Configuración de la URL del PMS

El PMS deberá configurar las siguientes 3 URLs para poder recibir la información de precios. Por favor, toma nota de las que son obligatorias

1. Sincronización de URL(obligatorio)

1. Este endpoint debe ser creado y controlado por el PMS

2. El PMS debe proporcionar este endpoint a PriceLabs usando el endpoint / integration.

3. PriceLabs llamará a este endpoint y subirá los listados junto con los precios y configuraciones asociadas, como se menciona en las Características de Precios de este documento.

4. Si falla la activación de la sincronización de la URL, lo intentamos 10 veces en ese día calendario.

2. Activación de la URL del Calendario (obligatorio)

1. Este endpoint debe ser creado y controlado por el PMS.

2. El PMS debe proporcionar este endpoint a PriceLabs usando el endpoint /integration.

3. Este endpoint recibirá los ids de los listados que necesitan una actualización completa de su información.

4. Una vez que este endpoint sea activado por PriceLabs, el PMS debe enviar un calendario completo que incluya los últimos precios y disponibilidad usando el endpoint /calendar.

3. URL de Hook

1. Este endpoint es opcional para el PMS, pero debe ser creado y controlado por el PMS si quieres implementarlo.

2. El PMS debe proporcionar este endpoint a PriceLabs usando el endpoint /integration.

3. Si la URL está configurada, PriceLabs puede llamar a este endpoint para enviar notificaciones al PMS con información específica relevante para un listado.

4. Este endpoint también puede ser usado para notificar al PMS en caso de errores o datos faltantes para un listado.

6. Características de Precios

Como parte de nuestra solución de precios dinámicos, podemos ofreceer las siguientes características de precios a través de nuestra API. Se recomienda ofecer las que están marcadas como obligatorias* ya que estos son los requisitos mínimos para nuestra integración. Tener soporte para las otras características crea una integración más robusta que permite a los clientes aprovechar al máximo las funciones de PriceLabs.

1. Precios*

2. Estadía Mínima*

3. Restricciones de Check in and Check Out

4. Precios según la Duración de Estadía (LOS)

5. Multi Unidades - Una propiedad/listado que tiene múltiples unidades dentro

6. Descuentos Semanales y Mensuales

7. Cargo por Persona Adicional y Activación de Persona Adicional (después de cuántos huéspedes se deben aplicar tarifas por persona adicional)

7. Llamadas API

1. Integración

1. Endpoint/integration
2. Obligatorio: Si
3. Requisito previo: El PMS debe recibir credenciales de la API de PriceLabs. Esta es una llamada a la API independiente.
4. Descripción:
• Este endpoint se usará para actualizar y mantener la integración del PMS. Principalmente, este endpoint se usa para actualizar la siguiente información crítica
• Actualizar sync_url, calendar_trigger_url and hook_url
• Actuaizar el token de API
• Controlar qué “características” de precios se exponen a los usuarios, como estadía mínima, restricciones de check-in/check-out, descuentos semanales/mensuales, tarifa por persona adicional, etc.

2. Listados

1. Endpoint: / Listados
2. Obligatorio: Si
3. ORequisito Previo:
1. El cliente crea/actualiza listados y sus características en el PMS.
2. El cliente debe estar registrado en PriceLabs y debe habilitar al PMS para enviar las características de los listados y los precios a PriceLabs.

4. Descripción:

• Para recibir recomendaciones de precios, se debe realizar esta llamada a la API para un listado recién creado o para enviar actualizaciones a un listado existente. Es fundamental que se realice esta llamada para cualquier listado nuevo listado que quieras agregar en PriceLabs; de lo contrario, PriceLabs no podrá proporcionar recomendaciones de precios para el listado recién creado dentro de tu PMS.
• Al realizar esta llamada, es obligatorio proporcionar el correo electrónico registrado del cliente en el parámetro user_token de la solicitud. Este es el mismo correo electrónico con el que el cliente está registrado en PriceLabs.
• 
  
• 
• 
  
• Importante: El id del listado que se envía a PriceLabs debe ser único en el PMS. Con exclusividad nos referimos a que un id de listado XYZ no puede pertenecer a dos o más usuarios en tu PMS y es exclusivo de un usuario en particular. Por ejemplo, si el id del listado “L2001” se está usando para dos propiedades diferentes de usuarios distintos, tales casos crearían ambigüedad.

1. Endpoint / Calendario
2. Obligatorio: Si
3. Requisitos Previo: Listado
4. Descripcion:
• Este endpoint se usará para actualizar el calendario de un listado con precios diarios y disponibilidad. Sin esta llamada, PriceLabs no podrá derivar precios dinámicos para el listado especifico.
•  La solicitud de calendario para un listado recién agregado debe contener un mínimo de 730 días de precios y disponibilidad. Una vez que se haya enviado un calendario completo a PriceLabs, se pueden usar las llamadas para enviar actualizaciones al calendario completo o a un rango específico de fechas.
• Recomendamos usar esta API para enviar cualquier actualización que ocurra en los precios y disponibilidad de un listado durante un período de calendario específico, para mantener PriceLabs actualizado, y así el PMS puede eventualmente enviar solo actualizaciones en el calendario (solo delta, no el calendario completo).
• Como mínimo, se debe actualizar el precio y la disponibilidad para cada fecha. Sin embargo, las otras configuraciones no es necesario actualizarlas; para recibir un diferencial en lugar de la configuración completa con cada sincronización, debes mantenerlas todas actualizadas.

4. Obtener Precios
1. Endpoint/Obtener Precios
2. Obligatorio: No, pero se recomienda implementar.
3. Prerequisito: Esta API se puede llamar una vez que PriceLabs active la URL de sincronización
4. Descripción:
• Después de que los listados estén configurados junto con los precios y la disponibilidad usando los endpoints listados y /calenadrio, PriceLabs activará la URL de sincronización proporcionada por el PMS tan pronto los nuevos precios estén listos.
• Una vez que el PMS recibe la activación de la URL de sincronización, puede consumir los precios en el cuerpo de la activación de la URL de sincronización o llamar a /get_prices para obtener los últimos precios dinámicos para tus listados.
• Por lo general, esta llamada debe realizarse una vez al día, cuando se activa la URL de sincronización. En algunos casos, podría hacerse más de una vez al día, si el cliente quiere publicar los últimos precios dinámicos para que estén disponibles más pronto.
• Es importante señalar que el PMS no debe configurar un trabajo CRON para llamar a este endpoint, sino que debe llamarlo solo después de que se active la URL de sincronización.
• Esta llamada es opcional, ya que los precios también se envían dentro del mensaje publicado en la URL de sincronización. El PMS puede consumir los precios de la URL de sincronización si no desea llamar a get_prices
• Como procedimiento estándar, en caso de que falle la activación de la URL de sincronización, intentamos nuevamente 10 veces en un día calendario.

5. Reservas

1. Endpoint / Reservaciones
2. Obligatorio: Sí. Esta API habilita las herramientas de Portfolio Analytics para los clientes.
3. Requisito previo: El listado para el cual se publican las reservas debe estar configurado correctamente en PriceLabs
4. Descripción:
• Este endpoint se usa para agregar una nueva reserva o actualizar una reserva existente para un listado.
• Se recomienda llamar a este endpoint siempre que haya nuevas reservas, actualizaciones o cancelaciones de reservas existentes, ya que esta información se usa dentro del producto de Portfolio Analytics que los clientes usan para ver diversas tendencias y comparar el desempeño de sus listados con el mercado.
• Un punto importante para mencionar es que el campo del costo_total en la solicitud de reservas debe incluir la suma de todos los costos asociados, incluidos los cargos y los impuestos.
• Para cálculos precisos de ocupación, es importante también brindar los bloqueos de calendario (bloqueos de propietario, bloqueos de mantenimiento, etc.) como reservas con un costo de $0 y un estado de BLOQUEADO

6. Estado

1. Endpoint: /Estado
2. Obligatorio: No
   
3. Prerequisitos: Los listados deben estar configurados en PriceLabs
4. Descripción:
• Este endpoint se usa para obtener información de PriceLabs sobre el estado actual de los datos asociados.
• Se puede obtener información sobre reservas, listados y calendarios de los listados.
• Esto no tendrá un impacto directo en los datos o la experiencia del usuario, pero se pueden usar por tu PMS para validar información, durante la creación de la integración o proporcionar soporte a los usuarios de la integración establecida

8. Ejemplo de Flujo de Integración

Con fines de demostración, usaremos un nombre ad-hoc ‘Fancy Rentals’ como un PMS que quiere integrarse con PriceLabs. Una vez que Fancy Rentals reciba el token de integración y el nombre de PriceLabs, podrá realizar llamadas a la API como se explicó en la sección anterior.

1. Primero, Fancy Rentals debe llamar al endpoint/integración para actualizar las URL del PMS (sección 5) y para obtener el token de integración. Si las URL del PMS no están configuradas, el resto de las llamadas a la API que siguen pueden no funcionar como se espera. Fancy Rentals debe almacenar el token de integración en su sistema para realizar llamadas a la API de PriceLabs. Si necesitan un nuevo token, puedes llamar nuevamente a este endpoint para obtener uno nuevo.

2. Siempre que un usuario cree un listado nuevo en Fancy Rentals y agregue sus precios y disponibilidad, Fancy Rentals debe llamar al endpoint/listados para los nuevos listados, seguido de una llamada al endpoint/ calendario para enviar un mínimo de 12 meses y hasta 2 años de precios y disponibilidad.

3. Siempre que un usuario actualice los precios y la disponibilidad de sus listados en Fancy Rentals, debe llamar al endpoint/calendar para actualizar la misma información en PriceLabs.

4. Siempre que PriceLabs llame a la URL para la activación del calendario con los IDs de los listados, Fancy Rentals debe llamar al endpoint/calendario con una actualización completa de los precios y la disponibilidad para los listados enviados por PriceLabs.

5. Cuando el usuario establece personalizaciones de precios y activa la sincronización del listado en ‘ON’ o inicia una sincronización manual en PriceLabs, PriceLabs llamará a la URL de sincronización proporcionada por Fancy Rentals con los IDs de los listados junto con sus precios dinámicos y otras configuraciones. Fancy Rentals puede llamar al endpoint/obtener precios para obtener la misma información, si es necesario.

6. Cuando Fancy Rentals reciba reservas del usuario o de otros canales, deben llamar al endpoint/reservaciones para enviar los detalles de la reserva a PriceLabs. Dado que las nuevas reservas o cancelaciones también cambian la disponibilidad, se recomienda que el PMS también llame posteriormente al endpoint/calendario para actualizar la disponibilidad y los precios más recientes.

9. Certificación

Una vez que el PMS haya completado el desarrollo, les solicitamos que notifiquen a PriceLabs sobre ello para que se pueda realizar la certificación. Asistiremos al equipo del PMS en cada paso de este proceso de certificación. Por favor, ten en cuenta que tu PMS será generalmente visible para todos los clientes en el menú desplegable del PMS solo después de que se complete la certificación.

1. A continuación, encontrarás el link a nuestro checklist de certificación, que el PMS debe utilizar para verificar tu integración.

https://docs.google.com/spreadsheets/d/18mMq8Qwv_LIalrxgiud_qHeRk4SPjeHtcC8wEYHcxOo/edit#gid=0

2. También solicitamos al equipo del PMS que comparta información sobre la integración, junto con la información de marketing. Los detalles se pueden encontrar en el mismo checklist de certificación.

3. El checklist también incluye las pruebas de verificación que necesitamos realizar para asegurarnos de que el flujo de la API se haya implementado correctamente.

1. Estas pueden ser ejecutadas por PriceLabs usando una cuenta de prueba en el PMS y un usuario de prueba en PriceLabs O
   

2. Si no se puede crear o compartir una cuenta de prueba en el PMS, entonces el equipo del PMS y el equipo de PriceLabs pueden realizar estas pruebas durante una llamada previamente programada.

10. Lanzamiento

Una vez que la certificación esté completa, el PMS está listo para iniciar la integración con PriceLabs.

1. El PMS debe configurar sus URLs de producción en PriceLabs: URL de sincronización, URL de activación del calendario y URL de gancho, y obtener el último token de integración.

2. El PMS y PriceLabs, en conjunto, deben identificar a los clientes prospectivos para iniciar la integración. Idealmente, se debe seleccionar un set de estos clientes para verificar que la integración funcione de manera completamente funcional y correcta. PriceLabs habilitará la integración para los clientes seleccionados.

3. Una vez se confirme que la integración funciona sin problemas y sin inconvenientes para los clientes seleccionados, se habilitará para todos los clientes en PriceLabs, de acuerdo con lo pactado con el PMS