Início Rápido

1. Pré-requisitos Essenciais

Antes de fazer sua primeira chamada à API Redeem, certifique-se de que todos os identificadores e credenciais necessários estão disponíveis.

1.1 Obter identificadores de negócio

Você precisará dos seguintes identificadores para operar a API Redeem. Eles são fornecidos durante o processo de onboarding:

2. Configuração de autenticação

A API Redeem utiliza dois fluxos de autenticação distintos dependendo da operação:

2.1 Obter autenticação

2.1.1 Fluxo A — Auth0 PKCE (vinculado ao membro)

Este fluxo vincula a conta de um membro específico e é obrigatório para Criar um resgate.

Passo 1 — Iniciar vinculação de conta (Authorize)

POST https://sandbox.api.latam.com/api/xp-api-login-management/v1/account-linking/authorize

Corpo da requisição:

{
  "client_id": "YOUR_CLIENT_ID_B2C_FROM_AUTH0",
  "redirect_uri": "YOUR_REDIRECT_URI",
  "external_user_id": "PARTNER_INTERNAL_USER_ID",
  "country": "cl",
  "lang": "es"
}

Resposta:

{
  "url": "https://auth.st.latamairlines.com/authorize?...",
  "state": "1489c760-e5e2-45cf-82ce-b518a8e38738",
  "codeVerifier": "OS7yYdFuH1b8e-Va99Vhbtg9TlLUAATwUMbNRsusRYo"
}

Passo 2 — Autenticação do membro (Navegador)

Abra a url retornada no Passo 1 em um navegador. Após o membro fazer login, a LATAM redireciona para o seu redirect_uri com o código de autorização:

<YOUR_REDIRECT_URI>?code=urb-YpG50oh6zYFJQL8UdF0oV6E1dZHTR1lXq7yvQew_i&state=1489c760-e5e2-45cf-82ce-b518a8e38738

Passo 3 — Trocar o código pelo token de acesso

POST https://sandbox.api.latam.com/api/xp-api-login-management/v1/oauth/token

Corpo da requisição:

{
  "grant_type": "authorization_code",
  "client_id": "YOUR_CLIENT_ID_B2C_FROM_AUTH0",
  "code": "CODE_FROM_CALLBACK",
  "redirect_uri": "YOUR_REDIRECT_URI",
  "code_verifier": "CODE_VERIFIER_FROM_STEP_1"
}

Resposta:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "v1.Mc8...",
  "token_type": "Bearer",
  "expires_in": 86400
}

Use o access_token no cabeçalho Authorization: Bearer para todas as requisições do Fluxo A. A renovação via refresh_token também está disponível; entre em contato com o LATAM Pass Support se precisar de mais detalhes.

2.1.2 Fluxo B — Credenciais de cliente do Portal API (nível do parceiro)

Este fluxo autentica no nível do parceiro e é utilizado para as operações de Consultar resgate e Cancelar resgate. Como pré-requisito, ao criar seu aplicativo no Developer Portal, selecione a API Redeem PNA.

Após a criação do aplicativo, obtenha um token de acesso usando o endpoint e as informações abaixo.

POST https://api.latampass.com/sandbox/oauth/access-token

Cabeçalhos da requisição:

Authorization: Basic <base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded
client_id: YOUR_CLIENT_ID

Corpo da requisição:

grant_type=client_credentials

Resposta:

{
  "access_token": "a0459255-597c-48ad-83a6-6e0da50a324d",
  "token_type": "Bearer",
  "expires_in": 3600
}

2.1.3 Resumo de autenticação

3. Configurar cabeçalhos da requisição

Use o conjunto de cabeçalhos adequado com base na operação que você está executando.

Fluxo A — Auth0 PKCE (Criar resgate):

Fluxo B — Credenciais de cliente do Portal API (Consultar resgate, Cancelar resgate):

4. Construir sua requisição

Criar resgate — POST /redeem

Campos obrigatórios:

Campos opcionais:

Exemplo com cURL:

curl https://api.latampass.com/sandbox/v1/customer/eloyalty/partner/redeem \
  --request POST \
  --header 'x-latam-test: LatamPass' \
  --header 'Authorization: Bearer <YOUR_JWT_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "description": "Demo API redeem",
    "miles": 15,
    "redemptionCode": "13X9CRYM",
    "partnerId": "LPS",
    "partnerTransactionId": "TXN-TEST-1769171650"
  }'

5. Cancelar resgate — POST /redeem/cancel

Campos obrigatórios:

Exemplo com cURL:

curl https://api.latampass.com/sandbox/v1/customer/eloyalty/partner/redeem/cancel \
  --request POST \
  --header 'x-latam-test: LatamPass' \
  --header 'Access_token: <YOUR_UUID_ACCESS_TOKEN>' \
  --header 'client_id: <YOUR_CLIENT_ID>' \
  --header 'Content-Type: application/json' \
  --data '{
    "correlationId": "ec909ee0-d890-44f4-b3f9-01797d591bc2",
    "description": "Customer requested cancellation",
    "miles": 15
  }'

6. Consultar status do resgate — GET /redeem

Parâmetro de consulta:

Exemplo com cURL:

curl 'https://api.latampass.com/sandbox/v1/customer/eloyalty/partner/redeem?correlationId=ec909ee0-d890-44f4-b3f9-01797d591bc2' \
  --request GET \
  --header 'x-latam-test: LatamPass' \
  --header 'Access_token: <YOUR_UUID_ACCESS_TOKEN>' \
  --header 'client_id: <YOUR_CLIENT_ID>' \
  --header 'Content-Type: application/json'

7. Tratar a resposta

7.1 Verificar o status final da transação

A Redeem API processa transações de forma assíncrona. O resultado final é entregue por um de dois mecanismos:

Webhook (recomendado) — configure um endpoint HTTPS do seu lado. A API envia uma requisição POST para o seu endpoint com o correlationId e o status final quando o processamento é concluído.

Polling (alternativa) — use o endpoint GET com o correlationId para consultar o status atual da transação a qualquer momento. Use polling apenas se uma notificação via webhook não for recebida após 24 horas.

Problemas e soluções

8. Checklist de integração

Use este checklist para confirmar que sua integração está completa e correta antes de solicitar acesso à produção.

• ✅ Ambos os fluxos de autenticação configurados (Fluxo A e Fluxo B)
• ✅ App do Portal configurada com b2b_client_id
• ✅ Resposta 201 interpretada como aceite, não como conclusão
• ✅ Respostas 4xx registradas com correlationId; respostas 500 repetidas com os mesmos dados
• ✅ Criar resgate validado de ponta a ponta (POST → correlationId → Webhook PROCESSED / ERROR / CANCELLED)
• ✅ Consultar resgate validado (GET por correlationId → status correto retornado)
• ✅ Fluxo de cancelamento validado (criar → PROCESSED → cancelar → Webhook REFUNDED / CANCELLED / ERROR)
• ✅ Tratamento de erros implementado para erros de validação, casos de não encontrado, status inválido e valor excedendo o total original
• ✅ correlationId armazenado de forma persistente e usado nas operações de GET e cancelamento
• ✅ Endpoint de webhook configurado e recebendo notificações ativamente

9. Guia de acesso à produção

Antes de solicitar acesso à produção, os seguintes pré-requisitos devem ser cumpridos:

• Todos os testes de integração concluídos em Sandbox (criar, consultar status, cancelar)
• Nenhum problema técnico em aberto entre seus sistemas e o LATAM Pass
• Integração em Sandbox aprovada pelo LATAM Pass Support via ticket

Passos para ir para produção:

1. Concluir a integração no Sandbox — execute todos os cenários de teste: Criar resgate, Consultar status do resgate e Cancelar resgate.
2. Solicitar aprovação para produção — abra um ticket na Central de Ajuda. O LATAM Pass Support verificará se os serviços estão configurados corretamente e poderá solicitar evidências das transações concluídas em sandbox.

Ambientes: Sandbox vs. Produção

Endpoints de produção