Notificação de resgate

A LATAM Pass Redeem API processa resgates e cancelamentos de forma assíncrona. Após enviar uma requisição, os parceiros recebem o status final da transação via notificação por webhook.

Existem duas opções para verificar o status final:

Notificação de resgate (webhook) — recomendada. A API envia automaticamente um POST para o seu endpoint configurado quando o processamento é concluído.
Consultar status do resgate — polling via endpoint GET.

Importante

Recomendamos fortemente o uso de notificação por webhook. Se você decidir implementar ambos, o polling deve ser utilizado somente se uma notificação não for recebida após 24 horas.

Existem dois tipos de notificações por webhook:

Notificação de resgate: enviada quando uma transação de Criar resgate atinge um status final (PROCESSED, ERROR ou CANCELLED).
Notificação de recrédito: enviada quando uma transação de Cancelar resgate atinge um status final (REFUNDED, CANCELLED ou ERROR).

Para vincular a notificação à requisição original, armazene o correlationId retornado na resposta 201 inicial.

Se o endpoint do parceiro responder com códigos 4xx ou 5xx durante a entrega da notificação, o sistema ativa tentativas automáticas por até 7 dias.

Dados necessários para configurar a integração

A configuração do webhook de resgate usa a mesma estrutura que o Accrual. O diferenciador principal é o campo source, que deve ser definido como "REDEEM".

Para configurar seu webhook de resgate, forneça ao LATAM Pass Support as seguintes informações:

Dado	Obrigatório	Descrição
URL do servidor do parceiro	Sim	Endpoint HTTPS onde o LATAM Pass enviará as notificações via webhook. Deve ser uma URL HTTPS publicamente acessível (sem IPs privados, sem localhost). Exemplo: `https://api.mycompany.com/redeem-webhook`
`source`	Sim	Deve ser `"REDEEM"` — distingue da configuração de webhook de Accrual
Método de autenticação	Pelo menos um	Basic auth (usuário + senha), token OAuth ou cabeçalhos adicionais
Usuário (Basic Auth)	Condicional	Usuário para autenticação básica no seu endpoint
Senha (Basic Auth)	Condicional	Senha para autenticação básica no seu endpoint
Cabeçalhos adicionais	Opcional	Quaisquer cabeçalhos HTTP exigidos pelo seu endpoint (pares chave-valor)
Configuração de token OAuth	Condicional	Se estiver usando OAuth: URL do endpoint de token, cabeçalhos/corpo da requisição para obter o token, nomes dos campos para enviar e recuperar o token

Qualquer modificação ou exclusão de configurações deve ser gerenciada via solicitação ao LATAM Pass Support, por ambiente (sandbox ou produção).

Conteúdo da notificação

Ambos os tipos de notificação (Resgate e Recrédito) compartilham a mesma estrutura de payload. Campos com valores null são omitidos.

Campo	Tipo	Descrição
`correlationId`	UUID	ID de correlação que vincula esta notificação à requisição original
`status`	String	Status final da transação (veja Valores de status abaixo)
`description`	String	Descrição do produto ou serviço da requisição de resgate original
`ffn`	String	Número do membro LATAM Pass (parcialmente mascarado)
`miles`	Integer	Para notificações de resgate: milhas debitadas. Para notificações de recrédito: milhas reacreditadas
`partnerTransactionId`	String	ID da transação do lado do parceiro
`redemptionId`	String	ID atribuído pelo sistema de pontos. Presente quando o status é `PROCESSED` ou `REFUNDED`
`errorException`	String (JSON)	Detalhe do erro quando o status é `ERROR` ou `CANCELLED`. Serializado como uma string JSON

Valores de status — Notificação de resgate (Criar resgate):

Status	Significado
`PROCESSED`	Milhas debitadas com sucesso. Elegível para cancelamento
`ERROR`	Processamento falhou. Veja `errorException` para detalhes. Entre em contato com o LATAM Pass Support se for recuperável
`CANCELLED`	Requisição cancelada. Milhas não foram debitadas

Valores de status — Notificação de recrédito (Cancelar resgate):

Status	Significado
`REFUNDED`	Milhas reacreditadas com sucesso na conta do membro
`CANCELLED`	Recrédito não pôde ser concluído (não recuperável)
`ERROR`	Recrédito falhou. Veja `errorException` para detalhes

Exemplos de notificação

Notificação de resgate — PROCESSED (milhas debitadas com sucesso)

curl --request POST \
  --url https://partner-server-url/ \
  --header 'Content-Type: application/json' \
  --data '{
    "correlationId": "ec909ee0-d890-44f4-b3f9-01797d591bc2",
    "status": "PROCESSED",
    "description": "Demo API redeem",
    "ffn": "10*******11",
    "miles": 15,
    "partnerTransactionId": "TXN-TEST-1769171650",
    "redemptionId": "4541318701061"
  }'

Notificação de resgate — CANCELLED (requisição rejeitada)

curl --request POST \
  --url https://partner-server-url/ \
  --header 'Content-Type: application/json' \
  --data '{
    "correlationId": "ec909ee0-d890-44f4-b3f9-01797d591bc2",
    "status": "CANCELLED",
    "description": "Demo API redeem",
    "ffn": "10*******11",
    "miles": 15,
    "partnerTransactionId": "TXN-TEST-1769171650",
    "errorException": "{\"status\":\"ERROR\",\"message\":\"The account balance is insufficient\",\"code\":10,\"instructions\":\"Check the available balance or add funds to continue.\"}"
  }'

Notificação de recrédito — REFUNDED (milhas reacreditadas com sucesso)

curl --request POST \
  --url https://partner-server-url/ \
  --header 'Content-Type: application/json' \
  --data '{
    "correlationId": "ec909ee0-d890-44f4-b3f9-01797d591bc2",
    "status": "REFUNDED",
    "description": "Demo API redeem",
    "ffn": "10*******11",
    "miles": 15,
    "partnerTransactionId": "TXN-TEST-1769171650",
    "redemptionId": "4541318701061"
  }'