API del banco de puntos
Permite a los clientes usar sus puntos de fidelidad para reservar viajes
Tú decides si tu sitio web de la plataforma de viajes de marca blanca se conectará a tu programa de fidelización, ya sea para acumular o canjear puntos de fidelidad (o ambas cosas). Tu programa de fidelización define qué compras dan derecho a ganar moneda de fidelización (sea cual sea la forma que adopte en tu programa —puntos, dólares o cualquier otra cosa—), incluidas las que se realizan en tu sitio web basado en una plantilla. También puedes permitirles canjear sus recompensas acumuladas en el sitio de la plantilla para reservar viajes.
Los clientes tendrán dos opciones para canjear sus puntos de fidelidad: directamente a través de tu página web modelo o por teléfono con un agente de Expedia. Con la API de Points Bank, el cliente podrá:
- Canjear la moneda de fidelidad obtenida
- Retirar compras de viajes (también denominado cancelar o anular)
- Recibir un reembolso total o parcial a su saldo total de fidelidad por cualquier plan de viaje cancelado
- Ver el saldo de su cuenta de fidelidad
>> Echa un vistazo a la página «Datos y respuestas comunes» para obtener más información
Podemos mostrar el saldo de fidelidad de un cliente en el encabezado de la plantilla de tu sitio web. Sin embargo, como las llamadas a la API se producen al cargar la página, los puntos que se muestren no se actualizarán hasta que lo haga la página, por lo que puede que no reflejen algún uso de las recompensas.
La API del banco de puntos tiene puntos de conexión que cubren el canje, la devolución y el reembolso de recompensas de fidelidad. También puede llamar a un punto de conexión de saldo de la cuenta. Para mayor precisión, esta API debe consultarse en el momento de la transacción. Cada uno de los puntos de conexión se detalla en las pestañas siguientes, pero todos ellos (incluido el punto de conexión de saldo de la cuenta) comparten los mismos campos de encabezado.
Variables de encabezado
| Campo | Descripción | Valor de muestra | Tipo de campo y longitud | ¿Obligatorio? |
|---|---|---|---|---|
partnerId | Identificador único de tu empresa, proporcionado por Expedia | TU MARCA | Cadena, máx. 20 caracteres | Sí |
Authorization | Token de acceso recibido por Expedia desde tu servidor de autorización que debe validar tu equipo | Token web JSON estándar (JWT) | Cadena, longitud JWT estándar | — |
Authorization2 | Token web JSON (JWT) enviado por Expedia; tu empresa debe validar la firma y las reclamaciones | JWT estándar | Cadena, longitud JWT estándar | — |
Canje
Este proceso de canje de one-step permite a los clientes canjear sus recompensas de fidelidad a través del banco de puntos, utilizando POST /redeem.
Solicitud
| Campo | Descripción | Valor de muestra | Tipo de campo y longitud | ¿Obligatorio? |
|---|---|---|---|---|
requestId | Identificador único de la solicitud de transacción | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Cadena, máx. 40 caracteres | Sí |
membershipId | Tu identificador único de cliente, recibido a través del SSO | a6fgju7he1bf | Cadena, máx. 40 caracteres | Sí |
loyaltyAccountNumber | El número de cuenta de fidelidad del cliente (también conocido como « programAccountNumber »); | 234986576 | Cadena, máx. 40 caracteres | — |
programId | Identificador del programa de fidelidad al que está afiliado el cliente o el nombre del nivel asociado al programa de fidelidad | Silver Gold Platinum | Cadena, máx. 20 caracteres | — |
sourceConfirmationId | Identificador de confirmación por parte de Expedia (también denominado orderId); se envía en las solicitudes de canje, reembolso y anulación y debe devolverse como parte de la carga de respuesta y como parte del archivo diario de reconciliación de puntos | 9223371998507503799 | Cadena, máx. 50 caracteres | Sí |
itineraryId | ItineraryId para hacer la reserva | 7610133766295 | Cadena, máx. 20 caracteres | — |
totalproductCost | Coste total de la reserva (hasta dos decimales); igual al equivalente en efectivo del importe pagado con puntos + el importe pagado en efectivo o con tarjeta | 230,09 | Cadena, máx. 10 caracteres | Sí |
PaymentDetails | Puntos de fidelidad y datos de pago en efectivo o con tarjeta; echa un vistazo a la sección « PaymentDetails » más abajo para ver los detalles del artículo. | Sí | ||
pointsPurchaseDetails | Solo es necesario en los casos en los que se compran puntos. Echa un vistazo a la sección « PointsPurchaseDetails » que aparece más abajo para ver los detalles del objeto. | — |
Respuesta
| Campo | Descripción | Valor de muestra |
|---|---|---|
status | Estado de la transacción (valores: Aprobado o Rechazado) | Rechazado |
requestId | Identificador único de la solicitud de transacción (de la carga de solicitud) | a5783c58-c5ce-4ff9-b83c-58c5cedff9 |
transactionDateTime | Fecha y hora de la transacción, tal y como se registran en el sistema del colaborador | 2023-04-20T12:01:23.203057Z |
sourceConfirmationId | Identificador del pedido por parte de Expedia (también denominado orderId); se envía en las solicitudes de canje, reembolso y anulación y debe incluirse en la carga de respuesta y en el archivo diario de reconciliación de puntos | 9223371998507503799 |
redemptionDetails | Confirmación del premio de fidelidad canjeado; consulta la sección « RedemptionDetails » más abajo para ver los detalles del objeto |   |
DeclineReason | Motivo por el que se rechazó la transacción; consulta la tabla de datos comunes DeclineReason para ver los detalles del objeto |
>> Más información sobre DeclineReason
PaymentDetails
| Campo | Descripción | ¿Obligatorio? |
|---|---|---|
redemptionDetails | Detalles sobre el canje de puntos de fidelidad; echa un vistazo a la sección « RedemptionDetails » más abajo para ver los detalles del artículo. | Sí |
amountPaidInCash | Importe que el cliente ha pagado por la reserva, ya sea en efectivo o con tarjeta; consulta la tabla de datos comunes « Amount » para ver los detalles del objeto. | Sí |
>> Más información sobre Amount
RedemptionDetails
| Campo | Descripción | Valor de muestra | Tipo de campo y longitud | ¿Obligatorio? |
|---|---|---|---|---|
amountPaidInLoyaltyCurrency | Número total de puntos, millas (o cualquier otra moneda de fidelidad) pagados por la reserva; consulta la tabla de datos comunes Amount para ver los campos anidados | Sí | ||
redemptionConfirmationId | Identificador de la operación de canje; se enviará en la solicitud de reembolso o anulación de Expedia, y debe rellenarse en el informe diario de reconciliación de puntos como "ID de confirmación del colaborador" para la transacción de canje | expedia-a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Cadena, máx. 50 caracteres | Sí |
loyaltyRedemptionCode | Código de canje requerido por algunas implementaciones, normalmente rellenado en la solicitud; es una contraseña de un solo uso o un código de canje predefinido para un producto, si se requiere | SKU | Cadena, máx. 20 caracteres | — |
promotionId | PromotionId (si hay algún ID de promoción asociado a la solicitud de canje) | Cadena, máx. 50 caracteres | — |
>> Más información sobre Amount
PointsPurchaseDetails
| Campo | Descripción | ¿Obligatorio? |
|---|---|---|
pointsPurchaseValue | Total de puntos que hay que comprar para reservar según la tarifa de la tabla; consulta la tabla de datos comunes Amount para ver los detalles del objeto | Sí |
amountPaidForPointsPurchase | Importe total pagado en efectivo para comprar los puntos necesarios. Este valor también es « basePriceForPointsPurchase + taxesAndFeesForPointsPurchase »; consulta la tabla de datos comunes « Amount » para ver los elementos anidados. | Sí |
basePriceForPointsPurchase | Precio base de los puntos que se van a comprar. Por ejemplo, si quieres comprar 2000 puntos y el precio por punto es de $0.02, el precio base sería $40;. Echa un vistazo a la tabla de datos comunes Amount para ver los artículos anidados. | — |
taxesAndFeesForPointsPurchase | Impuestos y tasas aplicables al precio base de la compra de puntos, si procede; consulta la tabla de datos comunes Amount para los elementos anidados. | — |
>> Más información sobre Amount
Retiradas
Para procesar retiradas (es decir, anulaciones de transacciones de fidelidad, también denominadas cancelaciones o anulaciones) en el banco de puntos, utilizarás el punto de conexión POST /rollback.
Esta API se activa cuando se realiza una operación de canje correctamente, pero Expedia debe revertirla, por ejemplo, debido a un fallo en la oferta (por ejemplo, mientras el cliente está intentando reservar, el hotel se agota). Como se trata de la anulación de un canje, se deberá realizar una reconciliación para que las recompensas de fidelidad vuelvan a estar disponibles.
Nota: Ni las transacciones de canje ni las de retirada deben aparecer en el informe diario de reconciliación de puntos.
Solicitud
| Campo | Descripción | Valor de muestra | Tipo de campo y longitud | ¿Obligatorio? |
|---|---|---|---|---|
requestId | Identificador único de la solicitud de transacción | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Cadena, máx. 40 caracteres | Sí |
membershipId | Identificador único del cliente de tu programa de fidelización | a6fgju7he1bf | Cadena, máx. 40 caracteres | Sí |
sourceConfirmationId | Identificador del pedido por parte de Expedia (también denominado orderId); se envía en las solicitudes de canje, reembolso y anulación y debe incluirse en la carga de respuesta y en el archivo diario de reconciliación de puntos | 9223371998507503799 | Cadena, máx. 50 caracteres | Sí |
CancellationDetails | Detalles sobre la transacción de retirada; consulta la tabla CancellationDetails para ver los elementos anidados |
Respuesta
| Campo | Descripción | Valor de muestra | Tipo de campo y longitud | ¿Obligatorio? |
|---|---|---|---|---|
status | Estado de la transacción de retirada que indica si la cancelación se ha realizado correctamente (valores: Aprobado o Rechazado) | Aprobado | Cadena | Sí |
requestId | Identificador único de la solicitud de transacción (de la carga de solicitud) | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Cadena, máx. 40 caracteres | Sí |
transactionDateTime | Fecha y hora de la transacción, tal y como se registran en tu sistema | 2023-04-20T12:01:23.203057Z | Cadena, máx. 40 caracteres | Sí |
sourceConfirmationId | Identificador del pedido por parte de Expedia (también denominado orderId); se envía en las solicitudes de canje, reembolso y anulación y debe incluirse en la carga de respuesta y en el archivo diario de reconciliación de puntos | 9223371998507503799 | Cadena, máx. 50 caracteres | Sí |
CancellationDetails | Detalles sobre la transacción de retirada (obligatorio si el valor status es Aprobado; consulta la tabla CancellationDetails para ver los elementos anidados | |||
Balance | Número de puntos, millas o cualquier otra unidad de fidelización disponible en la cuenta del cliente; consulta la tabla de datos comunes Amount para ver los elementos anidados | |||
DeclineReason | Motivo por el que se rechazó la transacción; consulta la tabla de datos comunes « DeclineReason » para ver los elementos anidados | |||
reasonMessage | Un mensaje personalizado para acompañar una respuesta de rechazo; consulta la tabla de datos comunes DeclineReason para los elementos anidados |
>> Más información sobre Amount
>> Más información sobre DeclineReason
CancellationDetails
| Campo | Descripción | Valor de muestra | Tipo de campo y longitud | ¿Obligatorio? |
|---|---|---|---|---|
redemptionConfirmationId | Identificador de confirmación del canje; se envía en la respuesta de canje; si se retira, no debe aparecer en el informe diario de puntos | a5783c58-c5ce-4ff9-b83c-58c5cedff991 | Cadena, máx. 50 caracteres | Sí |
cancellationConfirmationId | Identificador de confirmación para la operación de retirada (obligatorio si el valor status es Aprobado); no debe rellenarse en el informe diario de puntos | a5783c58-c5ce-4ff9-b83c-58c5cedff993 | Cadena, máx. 50 caracteres | — |
Reembolsos
Esta API se utiliza para procesar los reembolsos de fidelidad a tu banco de puntos con POST /refund. Se activa cuando el cliente necesita cancelar sus planes después de haber utilizado sus recompensas de fidelidad en una reserva. Como se trata de un reembolso de recompensas de fidelidad, se deberá realizar una reconciliación para que la moneda reembolsada esté disponible en la cuenta del cliente.
Solicitud
| Campo | Descripción | Valor de muestra | Tipo de campo y longitud | ¿Obligatorio? |
|---|---|---|---|---|
requestId | Identificador único de la solicitud de reembolso | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Cadena, máx. 40 caracteres | Sí |
membershipId | Identificador único del cliente | a6fgju7he1bf | Cadena, máx. 40 caracteres | Sí |
sourceConfirmationId | Identificador del pedido por parte de Expedia (también denominado orderId); se envía en las solicitudes de canje, reembolso y anulación y debe incluirse en la carga de respuesta y en el archivo diario de reconciliación de puntos | 9223371998507503799 | Cadena, máx. 50 caracteres | Sí |
RefundDetails | Detalles de la transacción de reembolso; consulta la tabla RefundDetails para ver los elementos anidados |
Respuesta
| Campo | Descripción | Valor de muestra | Tipo de campo y longitud | ¿Obligatorio? |
|---|---|---|---|---|
status | Estado del reembolso (valores: Aprobado o Rechazado) | Aprobado | Cadena | Sí |
requestId | Identificador único de la solicitud de reembolso (de la carga de reembolso) | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Cadena, máx. 40 caracteres | Sí |
transactionDateTime | Fecha y hora de la transacción, tal y como se registran en tu sistema | 2023-04-20T12:01:23.203057Z | Cadena, máx. 40 caracteres | Sí |
sourceConfirmationId | Identificador del pedido por parte de Expedia (también denominado orderId); se envía en las solicitudes de canje, reembolso y anulación y debe incluirse en la carga de respuesta y en el archivo diario de reconciliación de puntos | 9223371998507503799 | Cadena, máx. 50 caracteres | Sí |
RefundDetails | Detalles de la solicitud de reembolso; consulta la tabla RefundDetails para ver los elementos anidados | |||
Balance | Número de puntos, millas o cualquier otra unidad de fidelización disponible en la cuenta del cliente; consulta la tabla de datos comunes «Importe» para los elementos anidados | |||
DeclineReason | Motivo por el que se rechazó la transacción; consulta la tabla de datos comunes DeclineReason para ver los elementos anidados | |||
reasonMessage | Un mensaje personalizado que acompañe a una respuesta de rechazo; consulta la tabla de datos comunes DeclineReason |
>> Más información sobre Amount
>> Más información sobre DeclineReason
RefundDetails
| Campo | Descripción | Valor de muestra | Tipo de campo y longitud | ¿Obligatorio? |
|---|---|---|---|---|
loyaltyRefundAmount | Número total de puntos, millas o cualquier otra moneda de fidelidad reembolsada; consulta la tabla de datos comunes Amount para ver los elementos anidados | |||
redemptionConfirmationId | Identificador de la operación de canje; enviado en la respuesta de canje | a5783c58-c5ce-4ff9-b83c-58c5cedff918 | Cadena, máx. 50 caracteres | Sí |
refundConfirmationId | Identificador de la operación de reembolso; se enviará en la solicitud de reembolso o anulación de Expedia, y debe rellenarse en el archivo diario de reconciliación de puntos como "ID de confirmación del colaborador" para la transacción de reembolso | a324554f03-c5ce-4ff9-b83c-58c5cedff988 | Cadena, máx. 50 caracteres | — |
>> Más información sobre Amount
Saldo de la cuenta
Para obtener el saldo de la cuenta de fidelidad del cliente, utilizarás el punto de conexión POST /balance.
Solicitud
| Campo | Descripción | Valor de muestra | Tipo de campo y longitud | ¿Obligatorio? |
|---|---|---|---|---|
requestId | Identificador único de la solicitud de transacción | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Cadena, máx. 40 caracteres | Sí |
membershipId | Identificador único del cliente de tu programa de fidelización | a6fgju7he1bf | Cadena, máx. 40 caracteres | Sí |
loyaltyAccountNumber | El número de la cuenta de fidelidad del cliente (también denominado programAccountNumber); solo debería rellenarse si se requiere un identificador que no sea membershipId para operaciones de fidelidad | 234986576 | Cadena, máx. 40 caracteres | — |
programId | Identificador del programa de fidelidad al que está afiliado el cliente o el nombre del nivel asociado al programa de fidelidad | Platinum | Cadena, máx. 20 caracteres | — |
Respuesta (correcta)
| Campo | Descripción | Valor de muestra | Tipo de campo y longitud | ¿Obligatorio? |
|---|---|---|---|---|
requestId | Identificador único de la solicitud de transacción | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Cadena, máx. 40 caracteres | Sí |
Balance | Número de puntos, millas o cualquier otra unidad de fidelización disponible en la cuenta del cliente; consulta la tabla de datos comunes Amount para ver los elementos anidados |
>> Más información sobre Amount