Início Rápido

1. Pré-requisitos Essenciais

Antes de começar a integração com as APIs do LATAM Pass, você deve completar os seguintes requisitos comerciais e técnicos.

1.1 Obter Identificadores de Negócio

Os principais identificadores que você precisa são:

• PartnerID: um identificador único para sua empresa (ex: 09989092000121 ou OHUTA). O mesmo ID é usado para os ambientes Sandbox e Produção.
• ProductID: um identificador específico usado para rastrear transações de acúmulo.

Como posso obter o partnerID e o productID? Seu ponto focal comercial deve enviá-los para você. Você pode contatá-lo para obter esses identificadores caso ainda não os tenha recebido.

O que devo fazer se não os recebi? Por favor, contate nossa equipe de suporte caso não consiga entrar em contato com seu ponto focal.

1.2 Configuração de Autenticação (Auth)

Nossas APIs utilizam o padrão OAuth 2.0. Para interagir com qualquer endpoint, você deve incluir um access_token válido nos cabeçalhos de suas requisições.

Siga estas etapas para configurar seu acesso:

Etapa 1- Registre seu App: Navegue até a seção Dev Tools > Register App para criar o perfil da sua aplicação.

Etapa 2- Selecione a API: Selecione qual API deseja usar, sempre marcando a opção OAuth.

Após registrar a aplicação selecionando as APIs desejadas no Dev Tools, você poderá acessar a lista de seus apps registrados.

Clicando nos botões "Details" e "Authorization", você poderá acessar seu authorization code.

Com esse authorization code, você pode usar nossa API de access-token para gerar seu token e utilizá-lo nas outras APIs.

Sem o access token, você não conseguirá utilizá-las.

Etapa 3- Recupere suas Credenciais: Após a aprovação do app, acesse Dev Tools > My Apps, selecione seu app recém-criado e clique em "See details" para acessar:

2. Obter Autenticação

Construa sua Requisição POST para obter o parâmetro access-token.

2.1 Prepare sua Requisição de Autenticação

Use este curl para obter o método POST e preencha os parâmetros faltantes. Lembre-se: este é um exemplo de como deve ficar. Por favor, substitua os campos client_id e authorization pelos valores obtidos na seção anterior.

curl https://api.latampass.com/sandbox/oauth/access-token \
  --request POST \
  --header 'x-latam-test: LatamPass' \
  --header 'client_id: <<seu_client_id>>' \
  --header 'authorization: Basic <<seu_codigo_de_autorizacao>>' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials'

2.2 Configure os Cabeçalhos da Requisição

Após obter o client_id e o código de autorização conforme descrito na seção de Pré-requisitos Essenciais, configure os seguintes cabeçalhos na sua requisição:

Campos Obrigatórios Importantes

Após enviar a requisição com os cabeçalhos e o corpo sugeridos corretamente, você receberá o status 201 e esta resposta:

{
  "access_token": "<SEU_ACCESS_TOKEN>",
  "token_type": "access_token",
  "expires_in": 1000000
}

3. Construir seu POST

Construa sua Requisição POST com os parâmetros do parceiro e suas credenciais

3.1 Use nossas APIs

Se quiser usar a API Accrual PNA v2, use este comando curl e substitua os atributos incompletos pelas suas credenciais de parceiro, códigos de autenticação e outros parâmetros do corpo, que você já deve ter caso tenha lido as seções anteriores.

Neste exemplo, usaremos a requisição de accrual para enviar uma solicitação de acúmulo.

curl https://api.latampass.com/sandbox/v2/customer/loyalty/partner/accrual \
  --request POST \
  --header 'x-Latam-Test: LatamPass' \
  --header 'client_id: <insira seu client id aqui>' \
  --header 'access_token: <insira seu access token aqui>' \
  --header 'Content-Type: application/json' \
  --data '{
    "nonAirAccrual": {
      "quantity": 1000,
      "description": "PURCHASE TV 4K 60\" BLACK",
      "partner": {
        "partnerId": "<insira seu partner ID AQUI obtido com a equipe comercial da Latam>",
        "productId": "<use seu próprio código de produto AQUI, alfanumérico obrigatório>",
        "partnerAccrualId": "<use seu identificador único AQUI, alfanumérico, obrigatório>",
        "partnerTransactionId": "<use seu identificador único AQUI, alfanumérico, obrigatório>",
        "partnerOriginalDateTime": "yyyy-mm-ddThh:mm:ss-<fuso-horario>:00"
      },
      "member": {
        "ffn": "7000000013",
        "firstName": "Carlos Jose",
        "lastName": "Silva Santos",
        "birthDate": "1900-12-30",
        "gender": "FEMALE",
        "email": "carlos.santos@email.com",
        "residenceCountryCode": "AW",
        "phone": {
          "countryCode": 55,
          "areaCode": 11,
          "phoneNumber": 999998888
        },
        "document": {
          "documentId": "12345678900",
          "documentType": "CPF",
          "issueCountryCode": "BR"
        }
      }
    }
  }'

Mais informações sobre os campos desta requisição de API de exemplo:

4. Lidar com a Resposta do Accrual

Lide com o status de aceitação e os possíveis erros do exemplo da etapa 3

4.1 Status e Significados

Se você receber uma resposta 200 OK, significa que sua requisição foi aceita com sucesso para processamento.

• Analise o corpo de AccrualResponseV2 e armazene o correlationId. Esta é sua chave principal para rastrear a transação.
• Se você receber um erro 4xx ou 5xx, registre o corpo da resposta para depuração.
• Não tente novamente erros 4xx sem corrigir a requisição.

4.2 Verificar o Status Final da Transação

Se sua transação foi gerada corretamente (recebeu uma resposta 200 OK), você pode verificar o status da transação de 2 formas: webhook automático e manualmente.

Opção 1: Receber Notificações (Webhook) – Recomendado

Ação: Configure um endpoint (URL) no seu sistema que possa receber notificações POST. Quando o status da transação mudar, a API de Accrual enviará uma notificação com o correlationId e o status final.

Processo: Seu sistema deve estar escutando nessa URL para receber a notificação e atualizar o status da transação em seus registros.

Mais informações sobre webhook aqui

Opção 2: Consultar o Endpoint (Polling)

• Ação: Faça chamadas GET periódicas ao endpoint de consulta usando o correlationId recebido na etapa 4.

URL:

curl 'https://api.latampass.com/sandbox/v2/customer/loyalty/partner/accrual?partnerIdentifier=<seu partner ID>&correlationId=<seu correlation ID gerado>' \
  --header 'x-Latam-Test: LatamPass' \
  --header 'client_id: <Seu client id>' \
  --header 'Access_token: <seu access token>'

Condição de Parada: Pare o polling quando o campo status na resposta for PROCESSED ou CANCELLED

4.3 Problemas e Soluções

5. Checklist de Integração

Verifique aqui se você completou todas as etapas necessárias

5.1 Checklist de Integração da API de Accrual

✅ Autenticação: Estou incluindo o token de autenticação (access_token) no cabeçalho Authorization de todas as minhas requisições?

✅ Identificação do Membro: Estou enviando o FFN ou um objeto de documento completo (documentId, documentType, issueCountryCode) para identificar o membro em cada requisição de accrual?

✅ Identificadores do Parceiro: Estou gerando e enviando os três identificadores únicos obrigatórios no objeto partner?

productId

partnerAccrualId

partnerTransactionId

✅ Idempotência: Para evitar duplicatas, estou usando o partnerAccrualId de forma consistente para a mesma transação? Se reenviar uma transação devido a uma falha de rede, uso o mesmo partnerAccrualId?

✅ Tratamento de Respostas:

• Minha lógica interpreta corretamente uma resposta 200 OK / 204 No Content como uma aceitação bem-sucedida da requisição?
• Minha lógica consegue tratar uma resposta 4xx (ex., 400 Bad Request) e registrar o correlationId e a mensagem de erro para depuração?

✅ Registro do correlationId: Estou armazenando o correlationId retornado na resposta de sucesso?

6. Guia de Acesso à Produção

Certifique-se de ter concluído todos os itens para verificar sua prontidão para produção

Antes de solicitar acesso à produção, certifique-se de que:

• ✅ Todos os testes internos concluídos com sucesso no Sandbox
• ✅ Sem problemas técnicos entre o parceiro e o LATAM Pass
• ✅ Integração aprovada pela equipe do LATAM Pass
• ✅ Requisitos de segurança validados

6.1 Etapas de Prontidão para Produção

1. Concluir a Integração no Sandbox

Conclua com sucesso todos os cenários de teste no ambiente Sandbox

2. Solicitar Aprovação de Produção

Para que a integração seja aprovada, o LATAM Pass deve:

• Garantir que os serviços e regras estejam corretamente configurados no seu APP de teste
• Solicitar evidências de transações realizadas no ambiente de teste

3. Receber Credenciais de Produção

Após aprovação, você receberá:

• client_id de Produção
• client_secret de Produção
• Instruções de acesso à produção

6.2 Ambientes: Sandbox vs. Produção

6.3 Como Solicitar Acesso

1. Requisitos de Acesso

• Acesso via funcionalidade Dev Tools > Register App
• Aguardar aprovação da equipe (não automática como no Sandbox)
• Receber e-mail de confirmação da equipe

2. Processo de Produção Assistido

• Abra um ticket no Centro de Suporte solicitando produção assistida
• A equipe de suporte definirá como as evidências devem ser geradas
• As evidências serão compartilhadas com a equipe

3. Requisitos de Segurança

• O APP de Produção permanecerá no status "Pendente" até ser aprovado
• A equipe entrará em contato para alinhamentos e correções
• O APP de Produção será automaticamente desativado por razões de segurança

6.4 Endpoints de Produção

6.5 Problemas Comuns em Produção e Soluções