Introducción

La API PNA Accrual de LATAM Pass permite que las empresas aliadas gestionen la acumulación de puntos no aéreos para los socios LATAM Pass, según el acuerdo comercial vigente.

Cuando una alianza realiza una solicitud de acumulación, el procesamiento se efectúa de forma asíncrona.

Para conocer el estado del proceso, existen dos opciones:

1. Notificación de acumulación: se recibe una respuesta automática mediante un webhook que entrega la información al endpoint configurado cuando la acumulación se completa, evitando que la empresa aliada tenga que consultar la API constantemente.
2. Consulta de acumulación: se realiza una consulta directa a la API para verificar el estado(documentación relacionada)

Se recomienda usar solo la notificación por webhook. Si se decide implementar ambos mecanismos, la consulta solo debe usarse si no se recibe la notificación después de 24 horas.

Para recibir las notificaciones, la alianza debe guardar el correlationId, entregado en la respuesta inicial de la solicitud, para relacionar la notificación con la solicitud original.

El webhook de acumulación no comunica códigos de error HTTP 4xx o 5xx, ya que su objetivo es informar únicamente el estatus final de la transacción, el cual puede ser PROCESSED o CANCELLED. En caso de que el servicio de la alianza responda con códigos 4xx o 5xx durante el intento de entrega de la notificación, ésta se considerará no entregada y el sistema activará reintentos automáticos por un período máximo de 7 días.

Carta Gantt base

Accede a la carta Gantt base, un diagrama que presenta de manera estructurada las actividades, plazos y dependencias de cada tipo de alianza con el programa, mediante los enlaces indicados.

1. Nuevas alianzas;
2. Alianzas vigentes que migran a la API PNA LATAM Pass.

Datos requeridos para configurar la integración

Para realizar una integración correcta entre el sistema de la alianza y LATAM Pass, se deben proporcionar los siguientes datos:

1. URL del servidor de la alianza: endpoint donde LATAM Pass enviará los resultados de la acumulación mediante webhook. Ejemplo: https://api.mi-alianza.com/accrual-webhook
2. Usuario para autenticación básica: nombre de usuario utilizado exclusivamente para la autenticación HTTP Basic. Ejemplo: alianzaUser
3. Contraseña para autenticación básica: clave asociada al usuario para autenticación HTTP Basic.
4. Encabezados adicionales (si fueran necesarios): cualquier header HTTP que la API de la alianza requiera.

Cualquier modificación o eliminación de configuraciones ya realizadas debe gestionarse mediante una solicitud al Centro de Soporte, por entorno (pruebas o producción), como se detalla en el siguiente flujo:

Para más información, consulte el FAQ del portal LATAM Pass.

Contenido de la notificación

• nonAirAccrual:
  • String ffn: código de socio LATAM Pass que identifica la cuenta que recibió la acumulación;
  • String latamAccruald: código de identificación de la transacción de acumulación referenciada en el archivo de facturación;
  • String status: estado de la solicitud acumulada:
    • CANCELLED: solicitud rechazada. La acumulación solicitada no fue registrada en la cuenta del socio para formar su saldo. Este es el único estado que se debe considerar por parte de la alianza para reversar la transacción de su lado;
    • PROCESSED: acumulación concedida. La acumulación solicitada se registró en la cuenta del socio para formar su saldo y será parte del próximo archivo de facturación.
• trace:
  • UUID correlationId: código de identificación del correlativo indicado por la alianza o, en caso de no indicarlo, generado por LATAM Pas para fines de trazabilidad;
  • UUID threadId: código de acceso LATAM que identifica la cadena de transacciones durante todo el proceso de acumulación;
  • DateTime receivedDateTime: fecha y hora en que se recibió la solicitud de acumulación;
  • DateTime returnedDateTime: fecha y hora a la que se respondió a la solicitud de acumulación.
• error:
  • Integer code: código de error;
  • String message: descripción del mensaje de error;
  • String instructions: descripción de las instrucciones que debe seguir la alianza cuando de error;
  • DateTime issuedDateTime: fecha y hora en que se generó el error;
  • details:
    • String key: llave que detalla el error;
    • String value: valor que detalla el error.

Motivos para rechazar una solicitud

Ejemplos de notificaciones

Acumulación concedida

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"
	}
}'

Solicitud rechazada

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
	}
}'