API de banco de pontos
Permita que clientes usem ganhos de fidelidade para reservar viagens
Você escolhe se o seu modelo de site sem marca vai se conectar ao seu programa de fidelidade, para que clientes possam juntar ou resgatar pontos (ou ambos). O programa de fidelidade define quais compras dos seus clientes vão receber em troca a moeda de fidelidade (pontos, dinheiro ou outra), incluindo as compras no seu modelo de site. Você também pode permitir que as pessoas resgatem ganhos acumulados no seu modelo de site para reservar viagens.
Os clientes vão ter duas opções para resgatar os ganhos de fidelidade: direto no modelo de site ou com agentes da Expedia por telefone. Com a API de banco de pontos, os seus clientes podem:
- Resgatar os ganhos de fidelidade
- Reverter compras de viagens (também chamado de cancelamento ou anulação)
- Receber um reembolso integral ou parcial do total dos ganhos de fidelidade para planos de viagem cancelados
- Consultar o saldo da conta de fidelidade
Consulte mais informações na página sobre dados e respostas comuns.
Podemos exibir o saldo de fidelidade do cliente no cabeçalho do modelo de site. No entanto, como as chamadas de API ocorrem no carregamento da página, os pontos mostrados não vão ser atualizados até que a página seja atualizada. Por isso, podem não refletir outros usos de fidelidade.
A API de banco de pontos tem pontos de extremidade que abrangem resgate, reversão e reembolso dos ganhos de fidelidade. Ela também pode chamar um ponto de extremidade de saldo da conta. Para garantir precisão, a API precisa ser consultada no momento da transação. Cada um dos pontos de extremidade é detalhado nas guias abaixo, mas todos (inclusive o de saldo da conta) compartilham os mesmos campos de cabeçalho.
Variáveis de cabeçalho
| Campo | Descrição | Exemplo do valor | Tipo e comprimento do campo | Obrigatório? |
|---|---|---|---|---|
partnerId | Identificador exclusivo da empresa, disponibilizado pela Expedia. | SUA MARCA | Sequência, máximo de 20 caracteres | Sim |
Authorization | Token de acesso recebido pela Expedia do seu servidor de autorização, a ser validado pela sua equipe. | JSON Web Token (JWT) padrão | Sequência, comprimento padrão de JWT | Não |
Authorization2 | JSON Web Token (JWT) enviado pela Expedia. Assinatura e declarações a serem validadas por você. | JWT padrão | Sequência, comprimento padrão de JWT | Não |
Confira a página de exemplo de solicitação e resposta para saber mais sobre o conteúdo.
Resgate
Esse processo de confirmação em etapa única permite que clientes resgatem as suas recompensas de fidelidade por meio do banco de pontos usando POST /redeem.
Solicitação
| Campo | Descrição | Exemplo do valor | Tipo e comprimento do campo | Obrigatório? |
|---|---|---|---|---|
requestId | Identificador exclusivo da solicitação de transação. | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Sequência, máximo de 40 caracteres | Sim |
membershipId | Identificador exclusivo de cliente, recebido via SSO. | a6fgju7he1bf | Sequência, máximo de 40 caracteres | Sim |
loyaltyAccountNumber | Número da conta do programa de fidelidade do cliente (também chamado de programAccountNumber). Deve ser preenchido apenas se um identificador diferente de membershipId for necessário para operações de fidelidade.- 234986576 | Sequência, máximo de 40 caracteres | Não | |
programId | Identificador do programa de fidelidade ao qual o cliente é afiliado ou o nome do nível associado ao programa de fidelidade. | Silver Gold Platinum | Sequência, máximo de 20 caracteres | Não |
sourceConfirmationId | Identificador de confirmação da Expedia (também chamado de orderId). É enviado em solicitações de resgate, reembolso e anulação e deve ser enviado de volta como parte do conteúdo de resposta e como parte do arquivo de reconciliação de pontos diário. | 9223371998507503799 | Sequência, máximo de 50 caracteres | Sim |
totalproductCost | Custo total da reserva (até duas casas decimais). Igual ao equivalente em dinheiro do valor pago em pontos + valor pago em dinheiro ou cartão. | 230,09 | Sequência, máximo de 10 caracteres | Sim |
PaymentDetails | Moeda de fidelidade e dados de pagamento em dinheiro ou cartão. Consulte a tabela PaymentDetails para campos aninhados. | Sim |
Resposta
| Campo | Descrição | Exemplo do valor |
|---|---|---|
status | Status da transação (valores: Approved ou Declined) | Declined |
requestId | Identificador exclusivo da solicitação de transação (do conteúdo da solicitação). | a5783c58-c5ce-4ff9-b83c-58c5cedff9 |
transactionDateTime | Data e hora da transação, conforme registrado no sistema do parceiro. | 2023-04-20T12:01:23.203057Z |
sourceConfirmationId | Identificador do pedido da Expedia (também chamado de orderId). É enviado em solicitações de resgate, reembolso e anulação e deve ser incluído no conteúdo de resposta e no arquivo de reconciliação de pontos diário. | 9223371998507503799 |
redemptionDetails | Confirmação do prêmio de fidelidade resgatado. Consulte a tabela RedemptionDetails para itens aninhados. | |
DeclineReason | Motivo pelo qual a transação foi recusada. Consulte a tabela de dados comuns DeclineReason para itens aninhados. | |
reasonMessage | Uma mensagem personalizada para acompanhar uma resposta de recusa para melhor registro. Consulte a tabela de dados comuns DeclineReason para itens aninhados. |
PaymentDetails
| Campo | Descrição | Obrigatório? |
|---|---|---|
redemptionDetails | Informações do resgate de fidelidade. Consulte a tabela RedemptionDetails para itens aninhados. | Sim |
amountPaidInCash | Valor pago pelo cliente ao fazer a reserva em dinheiro ou no cartão. Consulte a tabela de dados comuns Amount para itens aninhados. | Sim |
RedemptionDetails
| Campo | Descrição | Exemplo do valor | Tipo e comprimento do campo | Obrigatório? |
|---|---|---|---|---|
amountPaidInLoyaltyCurrency | Número total de pontos, milhas (ou qualquer outra moeda de fidelidade) pagos pela reserva. Consulte a tabela de dados comuns Amount para campos aninhados. | Sim | ||
redemptionConfirmationId | Identificador da operação de resgate. É enviado na solicitação de reembolso ou anulação da Expedia e deve ser preenchido no relatório reconciliação de pontos diário como "ID de confirmação do parceiro" para a transação de resgate. | expedia-a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Sequência, máximo de 50 caracteres | Sim |
loyaltyRedemptionCode | Código de resgate exigido por algumas implementações, em geral, preenchido na solicitação. É uma senha de uso único ou código de resgate predefinido para um produto, se necessário. | SKU | Sequência, máximo de 20 caracteres | Não |
Reversões
Para processar reversões (ou seja, reversão de transações de fidelidade, também chamadas de cancelamentos ou anulações) no banco de pontos, você vai usar o ponto de extremidade POST /rollback.
Essa API é acionada quando uma operação de resgate é bem-sucedida, mas precisa ser revertida pela Expedia por algum motivo, como falha de fornecimento (por exemplo, enquanto o cliente está tentando reservar, o hotel fica lotado). Como essa é uma reversão de resgate, vai ser necessária uma reconciliação antes que os ganhos de fidelidade estejam disponíveis de novo.
Observação: as transações de resgate e de reversão não devem aparecer no relatório de reconciliação de pontos diário.
Solicitação
| Campo | Descrição | Exemplo do valor | Tipo e comprimento do campo | Obrigatório? |
|---|---|---|---|---|
requestId | Identificador exclusivo da solicitação de transação. | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Sequência, máximo de 40 caracteres | Sim |
membershipId | Identificador exclusivo de cliente do seu programa de fidelidade .- a6fgju7he1bf | Sequência, máximo de 40 caracteres | Sim | |
sourceConfirmationId | Identificador do pedido da Expedia (também chamado de orderId). É enviado em solicitações de resgate, reembolso e anulação e deve ser incluído no conteúdo de resposta e no arquivo de reconciliação de pontos diário. | 9223371998507503799 | Sequência, máximo de 50 caracteres | Sim |
CancellationDetails | Informações sobre a transação de reversão. Consulte a tabela CancellationDetails para itens aninhados. |
Resposta
| Campo | Descrição | Exemplo do valor | Tipo e comprimento do campo | Obrigatório? |
|---|---|---|---|---|
status | Status da transação de reversão indicando se o cancelamento foi bem-sucedido (valores: Approved ou Declined) | Approved | Sequência | Sim |
requestId | Identificador exclusivo da solicitação de transação (do conteúdo da solicitação) .- a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Sequência, máximo de 40 caracteres | Sim | |
transactionDateTime | Data e hora da transação, conforme registrado no seu sistema .- 2023-04-20T12:01:23.203057Z | Sequência, máximo de 40 caracteres | Sim | |
sourceConfirmationId | Identificador do pedido da Expedia (também chamado de orderId). É enviado em solicitações de resgate, reembolso e anulação e deve ser incluído no conteúdo de resposta e no arquivo de reconciliação de pontos diário. | 9223371998507503799 | Sequência, máximo de 50 caracteres | Sim |
CancellationDetails | Informações sobre a transação de reversão (obrigatórias se o valor status for Approved). Consulte a tabela CancellationDetails para itens aninhados. | |||
Balance | Quantidade de pontos, milhas ou qualquer outra moeda de fidelidade disponível na conta do cliente. Consulte os dados comuns na tabela Amount para itens aninhados .- | |||
DeclineReason | Motivo pelo qual a transação foi recusada. Consulte a tabela de dados comuns DeclineReason para itens aninhados .- | |||
reasonMessage | Uma mensagem personalizada para acompanhar uma resposta de recusa. Consulte a tabela de dados comuns DeclineReason para itens aninhados. |
CancellationDetails
| Campo | Descrição | Exemplo do valor | Tipo e comprimento do campo | Obrigatório? |
|---|---|---|---|---|
redemptionConfirmationId | Identificador de confirmação para resgate, enviado na resposta de resgate. Se revertido, não deve ser preenchido no relatório de pontos diário. | a5783c58-c5ce-4ff9-b83c-58c5cedff991 | Sequência, máximo de 50 caracteres | Sim |
cancellationConfirmationId | Identificador de confirmação para operação de reversão (obrigatório se o valor status for Approved). Não deve ser preenchido no relatório de pontos diário. | a5783c58-c5ce-4ff9-b83c-58c5cedff993 | Sequência, máximo de 50 caracteres | Não |
Reembolsos
Essa API é usada para processar reembolsos de fidelidade no seu banco de pontos com POST /refund. É acionada quando clientes precisam cancelar os seus planos após já terem usado os ganhos de fidelidade para reservar. Como se trata de um reembolso de ganhos de fidelidade, é necessária uma reconciliação antes que a moeda reembolsada esteja disponível na conta do cliente.
Solicitação
| Campo | Descrição | Exemplo do valor | Tipo e comprimento do campo | Obrigatório? |
|---|---|---|---|---|
requestId | Identificador exclusivo da solicitação de reembolso .- a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Sequência, máximo de 40 caracteres | Sim | |
membershipId | Identificador exclusivo de cliente. | a6fgju7he1bf | Sequência, máximo de 40 caracteres | Sim |
sourceConfirmationId | Identificador do pedido da Expedia (também chamado de orderId). É enviado em solicitações de resgate, reembolso e anulação e deve ser incluído no conteúdo de resposta e no arquivo de reconciliação de pontos diário. | 9223371998507503799 | Sequência, máximo de 50 caracteres | Sim |
RefundDetails | Informações sobre a transação de reembolso. Consulte a tabela RefundDetails para itens aninhados. |
Resposta
| Campo | Descrição | Exemplo do valor | Tipo e comprimento do campo | Obrigatório? |
|---|---|---|---|---|
status | Status do reembolso (valores: Approved ou Declined) | Approved | Sequência | Sim |
requestId | Identificador exclusivo da solicitação de reembolso (do conteúdo da solicitação). | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Sequência, máximo de 40 caracteres | Sim |
transactionDateTime | Data e hora da transação, conforme registrado no seu sistema .- 2023-04-20T12:01:23.203057Z | Sequência, máximo de 40 caracteres | Sim | |
sourceConfirmationId | Identificador do pedido da Expedia (também chamado de orderId). É enviado em solicitações de resgate, reembolso e anulação e deve ser incluído no conteúdo de resposta e no arquivo de reconciliação de pontos diário. | 9223371998507503799 | Sequência, máximo de 50 caracteres | Sim |
RefundDetails | Informações sobre a transação de reembolso. Consulte a tabela RefundDetails para itens aninhados. | |||
Balance | Quantidade de pontos, milhas ou qualquer outra moeda de fidelidade disponível na conta do cliente. Consulte os dados comuns na tabela Amount para itens aninhados .- | |||
DeclineReason | Motivo pelo qual a transação foi recusada. Consulte a tabela de dados comuns DeclineReason para itens aninhados .- | |||
reasonMessage | Uma mensagem personalizada para acompanhar uma resposta de recusa. Consulte a tabela de dados comuns DeclineReason. |
RefundDetails
| Campo | Descrição | Exemplo do valor | Tipo e comprimento do campo | Obrigatório? |
|---|---|---|---|---|
loyaltyRefundAmount | Número total de pontos, milhas ou qualquer outra moeda de fidelidade reembolsada. Consulte a tabela de dados comuns Amount para campos aninhados. | |||
redemptionConfirmationId | Identificador da operação de resgate. Enviado na resposta de resgate. | a5783c58-c5ce-4ff9-b83c-58c5cedff918 | Sequência, máximo de 50 caracteres | Sim |
refundConfirmationId | Identificador da operação de reembolso. É enviado na solicitação de reembolso ou anulação da Expedia e deve ser preenchido no arquivo de reconciliação de pontos diário como "ID de confirmação do parceiro" para a transação de reembolso. | a324554f03-c5ce-4ff9-b83c-58c5cedff988 | Sequência, máximo de 50 caracteres | Não |
Saldo da conta
Para buscar o saldo da conta de fidelidade do cliente, use o ponto de extremidade POST /balance.
Solicitação
| Campo | Descrição | Exemplo do valor | Tipo e comprimento do campo | Obrigatório? |
|---|---|---|---|---|
requestId | Identificador exclusivo da solicitação de transação. | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Sequência, máximo de 40 caracteres | Sim |
membershipId | Identificador exclusivo de cliente do seu programa de fidelidade .- a6fgju7he1bf | Sequência, máximo de 40 caracteres | Sim | |
loyaltyAccountNumber | Número da conta do programa de fidelidade do cliente (também chamado de programAccountNumber). Deve ser preenchido apenas se um identificador diferente de membershipId for necessário para operações de fidelidade.- 234986576 | Sequência, máximo de 40 caracteres | Não | |
programId | Identificador do programa de fidelidade ao qual o cliente é afiliado ou o nome do nível associado ao programa de fidelidade. | Platinum | Sequência, máximo de 20 caracteres | Não |
Resposta (bem-sucedida)
| Campo | Descrição | Exemplo do valor | Tipo e comprimento do campo | Obrigatório? |
|---|---|---|---|---|
requestId | Identificador exclusivo da solicitação de transação. | a5783c58-c5ce-4ff9-b83c-58c5cedff988 | Sequência, máximo de 40 caracteres | Sim |
Balance | Quantidade de pontos, milhas ou qualquer outra moeda de fidelidade disponível na conta do cliente. Consulte os dados comuns na tabela Amount para itens aninhados .- |