Introdução

A API PNA Accrual do LATAM Pass permite que as empresas parceiras gerenciem o acúmulo de pontos não aéreos para os membros do LATAM Pass, de acordo com o contrato comercial vigente.

Quando uma parceria faz uma solicitação de acúmulo, o processamento é feito de forma assíncrona.

Para saber o status do processo, existem duas opções:

Notificação do acúmulo, é recebida uma resposta automática por meio de um webhook que entrega as informações ao endpoint configurado quando a acumulação é concluída, evitando que a empresa parceira tenha que consultar a API constantemente.
Consultar acúmulo.

Recomenda-se usar apenas a notificação por webhook. Se decidir implementar ambos os mecanismos, a consulta só deve ser usada se a notificação não for recebida após 24 horas.

Para receber as notificações, a parceria deve salvar o correlationId, fornecido na resposta inicial da solicitação, para relacionar a notificação com a solicitação original.

O webhook de acumulação não comunica códigos de erro HTTP 4xx ou 5xx, pois seu objetivo é informar apenas o status final da transação, que pode ser PROCESSED ou CANCELLED. Caso o serviço da parceria responda com códigos 4xx ou 5xx durante a tentativa de entrega da notificação, esta será considerada não entregue e o sistema ativará novas tentativas automáticas por um período máximo de 7 dias.

Cronograma base

Acesse o cronograma Gantt básico, um diagrama que apresenta de forma estruturada as atividades, prazos e dependências de cada tipo de parceria com o programa, através dos links indicados.:

Dados necessários para configurar a integração

Para realizar uma integração correta entre o sistema da aliança e o LATAM Pass, é necessário fornecer os seguintes dados:

URL do servidor da parceiro: endpoint onde o LATAM Pass enviará os resultados da acumulação por meio de webhook. Exemplo: https://api.mi-alianza.com/accrual-webhook
Usuário para autenticação básica: nome de usuário usado exclusivamente para autenticação HTTP Basic. Exemplo: aliançaUser
Senha para autenticação básica: senha associada ao usuário para autenticação HTTP Basic.
Cabeçalhos adicionais (se necessários): qualquer cabeçalho HTTP que a API da aliança exigir.

Qualquer modificação ou eliminação de configurações já realizadas deve ser gerenciada por meio de uma solicitação ao Central de Suporte, por ambiente (teste ou produção), conforme detalhado no fluxo a seguir:

Conteúdo da notificação

nonAirAccrual:
- String ffn: código do cliente LATAM Pass que identifica a conta que recebeu o acúmulo;
- String latamAccruald: código de identificação da transação de acúmulo referenciado no arquivo de faturamento;
- String status: Estado da solicitação de acúmulo:
  - CANCELLED: solicitação rejeitada. O acúmulo solicitado não foi contabilizado na conta do cliente para composição de seu saldo. Este é o único estado a ser considerado para estorno da transação do lado do parceiro;
  - PROCESSED: acúmulo concedido. O acúmulo solicitado foi contabilizado na conta do cliente para composição de seu saldo e fará parte do próximo arquivo de faturamento.
trace:
- UUID correlationId: código de identificação do correlativo indicado pelo parceiro ou, se não indicado, gerado pelo LATAM Pas para efeitos de rastreabilidade;
- UUID threadId: código LATAM Pass que identifica a cadeia de transações por todo o processo de acúmulo;
- DateTime receivedDateTime: data e hora em que a solicitação de acúmulo foi recebida;
- DateTime returnedDateTime: data e hora em que a solicitação de acúmulo foi respondida.
error:
- Integer code: código do erro;
- String message: descrição da mensagem de erro;
- String instructions: descrição das instruções a serem seguidas pelo parceiro ao se deparar com o erro;
- DateTimeissuedDateTime: data e hora em que o erro foi gerado;
- details:
  - String key: chave que detalha o erro;
  - String value: valor que detalha o erro.

Motivos para uma solicitação ser rejeitada

Motivo	Código	Mensagem	Instruções ao parceiro
A data da atividade junto ao parceiro, no momento do solicitação de acúmulo, encontrava-se no futuro. (`partnerOriginalDateTime`)	101	ActivityDateGreater ThanCurrentDate	Validate your request because some date is greater than current date
Código de identificação do parceiro não cadastrado. (`partnerId`)	108	PartnerDoesNotExist	Partner doesn't exist. Please contact our LATAM team to set up the necessary configurations
Código de identificação do produto não cadastrado ou não vinculado ao parceiro ou expirado no momento da solicitação de acúmulo. (`productId`)	110	IACOD	Accrual code is expired or invalid
Programa inválido para o país de residência do cliente. (`ffn`)	111	CCIE - Invalid country of residence	Invalid program. Please contact our LATAM team to set up the necessary configurations
Cliente não encontrado com os dados informados (`ffn`,`document`), mas endereço de e-mail vinculado à outra conta já existente (`email`).	112	DuplicateMemberProfiles ExistsAsPerAlgorithm	Member: Contact LATAM to update your data
Código de identificação do cliente (`ffn`) é inválido para o seu país de residência (`residenceCountryCode`).	113	Incorrect CPF format validated by the Core System	Fix the CPF number
Cliente com estado de conta inválido para acúmulo. (`ffn`)	114	Invalid member status	Member: Contact LATAM to update your data
Não foi possível processar a solicitação de acúmulo para o cliente. (`ffn`,`document`)	204	Member already exists	Member: Contact LATAM to update your data
Código de identificação do cliente (`ffn`) é inválido para o seu país de residência (`residenceCountryCode`).	205	Incorrect CPF format validated by the Core System	Fix the CPF number
Não foi possível processar a solicitação de acúmulo para o cliente. (`ffn`,`document`)	206	Member already exists	Member: Contact LATAM to update your data

Exemplos de notificação

Acúmulo concedido

curl --request POST \
  --url https://url-servidor-parceiro/ \
  --header 'Content-Type: application/json' \
  --data '{
	"nonAirAccrual": {
		"ffn": "12345678912",
		"latamAccrualId": "BCS12345_6",
		"status": "PROCESSED"
	},
	"trace": {
		"correlationId": "f050f11e-b05b-499d-ae13-154efc091ef4",
		"threadId": "39fd0a13-b76a-445c-875c-01595eb6f577",
		"receivedDateTime": "2024-11-01 12:14:54.510+0000",
		"returnedDateTime": "2024-11-01 12:14:54.553+0000"
	}
}'

Solicitação rejeitada

curl --request POST \
  --url https://url-servidor-parceiro/ \
  --header 'Content-Type: application/json' \
  --data '{
	"nonAirAccrual": {
		"ffn": "11111111111",
		"status": "CANCELLED"
	},
	"trace": {
		"correlationId": "f050f11e-b05b-499d-ae13-154efc091ef4",
		"threadId": "39fd0a13-b76a-445c-875c-01595eb6f577",
		"receivedDateTime": "2024-11-01 12:14:54.510+0000",
		"returnedDateTime": "2024-11-01 12:14:54.553+0000"
	},
	"error": {
		"code": 108,
		"message": "PartnerDoesNotExist",
		"instructions": "Partner doesn't exist.
Please contact our LATAM team to set up the necessary configurations.",
		"issuedDateTime": "2024-11-01 12:14:54.510+0000",
		"details": null
	}
}'

Notificação do acúmulo