Inicio Rápido

1. Prerrequisitos Esenciales

Antes de comenzar la integración con las APIs de LATAM Pass, debes completar los siguientes requisitos comerciales y técnicos.

1.1 Obtener Identificadores de Negocio

Los identificadores clave que necesitas son:

• PartnerID: un identificador único para tu empresa (ej: 09989092000121 o OHUTA). El mismo ID se usa para los entornos Sandbox y Producción.
• ProductID: un identificador específico usado para rastrear transacciones de acumulación.

¿Cómo puedo obtener el partnerID y el productID? Tu punto focal comercial debe enviártelos. Puedes contactarlo para obtener estos identificadores si aún no los has recibido.

¿Qué debo hacer si no los recibí? Por favor, contacta a nuestro equipo de soporte en caso de que no hayas podido comunicarte con tu punto focal.

1.2 Configuración de Autenticación (Auth)

Nuestras APIs utilizan el estándar OAuth 2.0. Para interactuar con cualquier endpoint, debes incluir un access_token válido en los encabezados de tus solicitudes.

Sigue estos pasos para configurar tu acceso:

Paso 1- Registra tu App: Navega a la sección Dev Tools > Register App para crear el perfil de tu aplicación.

Paso 2- Selecciona la API: Selecciona qué API deseas usar, marcando siempre la opción OAuth.

Una vez que hayas registrado la aplicación seleccionando las APIs deseadas en Dev Tools, podrás acceder a la lista de tus apps registradas.

Al hacer clic en los botones "Details" y "Authorization", podrás acceder a tu authorization code.

Con ese authorization code, puedes usar nuestra API de access-token para generar tu token y usarlo en las otras APIs.

Sin el access token, no podrás utilizarlas.

Paso 3- Recupera tus Credenciales: Una vez aprobada la app, ve a Dev Tools > My Apps, selecciona tu app recién creada y haz clic en "See details" para acceder a:

2. Obtener Autenticación

Construye tu Solicitud POST para obtener el parámetro access-token.

2.1 Prepara tu Solicitud de Autenticación

Usa este curl para obtener el método POST y completa los parámetros faltantes. Recuerda: este es un ejemplo de cómo debe verse. Por favor, reemplaza los campos client_id y authorization con los valores que obtuviste en la sección anterior.

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

2.2 Configura los Encabezados de la Solicitud

Una vez que obtengas el client_id y el código de autorización como se describe en la sección de Prerrequisitos Esenciales, configura los siguientes encabezados en tu solicitud:

Campos Obligatorios Importantes

Una vez que envíes la solicitud con los encabezados y el cuerpo sugeridos correctamente, recibirás el estado 201 y esta respuesta:

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

3. Construir tu POST

Construye tu Solicitud POST con los parámetros del partner y tus credenciales

3.1 Usa nuestras APIs

Si quieres usar la API Accrual PNA v2, usa este comando curl y reemplaza los atributos incompletos con tus credenciales de partner, códigos de autenticación y otros parámetros del cuerpo, que ya deberías tener si leíste las secciones anteriores.

En este ejemplo, usaremos la solicitud de accrual para enviar una solicitud de acumulación.

curl https://api.latampass.com/sandbox/v2/customer/loyalty/partner/accrual \
  --request POST \
  --header 'x-Latam-Test: LatamPass' \
  --header 'client_id: <ingresa tu client id aquí>' \
  --header 'access_token: <ingresa tu access token aquí>' \
  --header 'Content-Type: application/json' \
  --data '{
    "nonAirAccrual": {
      "quantity": 1000,
      "description": "PURCHASE TV 4K 60\" BLACK",
      "partner": {
        "partnerId": "<ingresa tu partner ID AQUÍ obtenido con el equipo comercial de Latam>",
        "productId": "<usa tu propio código de producto AQUÍ, alfanumérico obligatorio>",
        "partnerAccrualId": "<usa tu identificador único AQUÍ, alfanumérico, obligatorio>",
        "partnerTransactionId": "<usa tu identificador único AQUÍ, alfanumérico, obligatorio>",
        "partnerOriginalDateTime": "yyyy-mm-ddThh:mm:ss-<zona-horaria>: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"
        }
      }
    }
  }'

Más información sobre los campos de esta solicitud de API de ejemplo:

4. Manejar la Respuesta del Accrual

Maneja el estado de aceptación y los posibles errores del ejemplo del paso 3

4.1 Estados y Significados

Si recibes una respuesta 200 OK, significa que tu solicitud fue aceptada exitosamente para procesamiento.

• Analiza el cuerpo de AccrualResponseV2 y almacena el correlationId. Esta es tu clave principal para rastrear la transacción.
• Si recibes un error 4xx o 5xx, registra el cuerpo de la respuesta para depuración.
• No reintentes errores 4xx sin corregir la solicitud.

4.2 Verificar el Estado Final de la Transacción

Si tu transacción se generó correctamente (recibiste una respuesta 200 OK), puedes verificar el estado de la transacción con 2 métodos: webhook automático y manualmente.

Opción 1: Recibir Notificaciones (Webhook) – Recomendado

Acción: Configura un endpoint (URL) en tu sistema que pueda recibir notificaciones POST. Cuando el estado de la transacción cambie, la API de Accrual te enviará una notificación con el correlationId y el estado final.

Proceso: Tu sistema debe estar escuchando en esa URL para recibir la notificación y actualizar el estado de la transacción en tus registros.

Más información sobre webhook aquí

Opción 2: Consultar el Endpoint (Polling)

• Acción: Realiza llamadas GET periódicas al endpoint de consulta usando el correlationId recibido en el paso 4.

URL:

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

Condición de Parada: Detén el polling cuando el campo status en la respuesta sea PROCESSED o CANCELLED

4.3 Problemas y Soluciones

5. Lista de Verificación de Integración

Verifica aquí si completaste todos los pasos necesarios

5.1 Lista de Verificación de Integración de la API de Accrual

✅ Autenticación: ¿Estoy incluyendo el token de autenticación (access_token) en el encabezado Authorization de todas mis solicitudes?

✅ Identificación del Miembro: ¿Estoy enviando el FFN o un objeto de documento completo (documentId, documentType, issueCountryCode) para identificar al miembro en cada solicitud de accrual?

✅ Identificadores del Partner: ¿Estoy generando y enviando los tres identificadores únicos obligatorios en el objeto partner?

productId

partnerAccrualId

partnerTransactionId

✅ Idempotencia: Para evitar duplicados, ¿estoy usando el partnerAccrualId de forma consistente para la misma transacción? Si reenvío una transacción debido a un fallo de red, ¿uso el mismo partnerAccrualId?

✅ Manejo de Respuestas:

• ¿Mi lógica interpreta correctamente una respuesta 200 OK / 204 No Content como una aceptación exitosa de la solicitud?
• ¿Mi lógica puede manejar una respuesta 4xx (ej., 400 Bad Request) y registrar el correlationId y el mensaje de error para depuración?

✅ Registro del correlationId: ¿Estoy almacenando el correlationId retornado en la respuesta de éxito?

6. Guía de Acceso a Producción

Asegúrate de haber completado todos los elementos para verificar tu preparación para producción

Antes de solicitar acceso a producción, asegúrate de que:

• ✅ Todas las pruebas internas completadas exitosamente en Sandbox
• ✅ Sin problemas técnicos entre el partner y LATAM Pass
• ✅ Integración aprobada por el equipo de LATAM Pass
• ✅ Requisitos de seguridad validados

6.1 Pasos de Preparación para Producción

1. Completar la Integración en Sandbox

Completa exitosamente todos los escenarios de prueba en el entorno Sandbox

2. Solicitar Aprobación de Producción

Para que la integración sea aprobada, LATAM Pass debe:

• Asegurarse de que los servicios y reglas estén correctamente configurados en tu APP de prueba
• Solicitar evidencia de transacciones realizadas en el entorno de prueba

3. Recibir Credenciales de Producción

Una vez aprobado, recibirás:

• client_id de Producción
• client_secret de Producción
• Instrucciones de acceso a producción

6.2 Entornos: Sandbox vs. Producción

6.3 Cómo Solicitar Acceso

1. Requisitos de Acceso

• Acceso a través de la funcionalidad Dev Tools > Register App
• Esperar aprobación del equipo (no automática como en Sandbox)
• Recibir correo electrónico de confirmación del equipo

2. Proceso de Producción Asistido

• Abre un ticket en el Centro de Soporte solicitando producción asistida
• El equipo de soporte definirá cómo se debe generar la evidencia
• La evidencia será compartida con el equipo

3. Requisitos de Seguridad

• La APP de Producción permanecerá en estado "Pendiente" hasta ser aprobada
• El equipo se pondrá en contacto para alineación y correcciones
• La APP de Producción será desactivada automáticamente por razones de seguridad

6.4 Endpoints de Producción

6.5 Problemas Comunes en Producción y Soluciones