1 Empieza por el token

Todas las llamadas llevan el mismo header. El token de QA no sirve en producción.

Authorization: Bearer <AccessToken>

2 Sigue este orden

El uid que devuelve Usuarios es el member_ref que pide Puntos. El commerce_id sale del token, en el claim custom:idCommerce.

1 Pedir el AccessToken

Un POST a la raíz del host. QA usa https://oauthqa.leal.co/. Producción usa https://oauth.leal.co/. El header X-Amz-Target fija la operación InitiateAuth.

QA

POST https://oauthqa.leal.co/
Content-Type: application/x-amz-json-1.1
X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth

{
  "AuthFlow": "USER_PASSWORD_AUTH",
  "ClientId": "<ClientId>",
  "AuthParameters": {
    "USERNAME": "<usuario>",
    "PASSWORD": "<contraseña>"
  }
}

Producción

POST https://oauth.leal.co/
Content-Type: application/x-amz-json-1.1
X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth

{
  "AuthFlow": "USER_PASSWORD_AUTH",
  "ClientId": "<ClientId>",
  "AuthParameters": {
    "USERNAME": "<usuario>",
    "PASSWORD": "<contraseña>"
  }
}

Usa AuthenticationResult.AccessToken en Authorization: Bearer.

2 Qué trae el token

Se envía completo en Authorization. Estos claims se reutilizan en las demás llamadas.

El token identifica al usuario del comercio, no al cliente final. El cliente se crea o se busca en Usuarios.

1 Catálogos, si el formulario no trae los códigos

2 Crear a la persona

{
  "cedula": "1234567890",
  "tipoDocumento": 1,
  "nombre": "Ana",
  "apellido": "Pérez",
  "celular": "3001234567",
  "email": "ana@ejemplo.com",
  "codPais": "CO",
  "codCiudad": "1",
  "plataformaOrigen": "API",
  "idComercio": 3
}

Guarda el uid de la respuesta. En Puntos ese valor se envía como member_ref.

3 Buscarla si ya existe

{
  "criterio": "cedula",
  "valor": "1234567890"
}

Para ver la ficha de un uid que ya tienes:

El correo o el celular de esa ficha son los que usa el OTP de redención.

4 Asociarla al comercio

Hazlo cuando la persona ya existe y todavía no está en tu programa.

{
  "uid": "<uid>",
  "idComercio": 3
}

idComercio es el mismo custom:idCommerce del token. Para quitar la asociación: PUT /v1/users/legacy/favorite/remove con el mismo cuerpo.

5 Sucursales

La redención pide branch_id. Esta lista devuelve los ids de tu comercio.

uid_cms es custom:uidCms. commerce_id es custom:idCommerce. Guarda el id de la sucursal donde opera la caja.

1 Confirmar el comercio y el saldo

Responde el commerce_id de tu token. Úsalo para comprobar que el usuario es el de este comercio.

Devuelve el saldo activo y el pendiente.

Historial. También sirve para recuperar el operation_key si hay que anular y ya no lo tienes.

2 Acumular por el monto de la compra

{
  "member_ref": "<uid>",
  "operation_key": "fac-1001",
  "external_ref": "fac-1001",
  "source": "pos",
  "user_origin": "pos",
  "gross_amount": 50000,
  "branch_id": "1200"
}

• operation_key lo generas tú. Es la llave para no duplicar y para anular después.
• external_ref es el número de la factura.
• Un 200 con points: 0 es válido: la regla no entregó puntos.

3 Premios del comercio

La redención pide un reward_id. Ese id te lo entrega Leal para el premio del comercio.

4 Redimir, con el OTP en tus manos

Genera el OTP, valídalo y llama a la redención.

{
  "usecaseId": 1,
  "commerceId": 3,
  "email": "ana@ejemplo.com",
  "cellphone": "3001234567",
  "countryCode": "CO",
  "uid": "<uid>"
}

usecaseId es el de redención que te entregó Leal. La respuesta trae otpId.

{
  "otpId": 12345,
  "otpCode": "<código>"
}

Sigue solo si isValid es true.

{
  "member_ref": "<uid>",
  "reward_id": "<reward_id>",
  "operation_key": "red-2001",
  "external_ref": "fac-1001",
  "source": "pos",
  "branch_id": "1200"
}

5 Anular

Usa un operation_key nuevo para la anulación y señala la operación original con origin_operation_key. También vale origin_entry_id o external_ref.

{
  "commerce_id": 3,
  "member_ref": "<uid>",
  "operation_key": "anu-fac-1001",
  "origin_operation_key": "fac-1001",
  "source": "pos"
}

Para anular una redención, el mismo cuerpo más motive:

{
  "commerce_id": 3,
  "member_ref": "<uid>",
  "operation_key": "anu-red-2001",
  "origin_operation_key": "red-2001",
  "motive": "devolucion",
  "source": "pos"
}

6 Factura y líneas

Estas dos llamadas registran la factura y sus líneas, con el mismo AccessToken. codigoItem es el SKU.

Acumula y, si responde code 100, escribe la cabecera y las líneas. Guarda id_transaccion.

Escribe la cabecera si no existe y reemplaza las líneas. codigoItem es el SKU. Pide ese id_transaccion. El detalle de los cuerpos está en la referencia.

1 Tu primera audiencia manual

Una audiencia manual es una lista de uids que tú envías. Este ejemplo aplica solo a ese tipo de audiencia.

{
  "audience_name": "Clientes VIP",
  "audience_type": "manual",
  "uids": ["uid-1", "uid-2"],
  "dry_run": true
}

• dry_run: true no crea nada: responde 200 con enabled_count y excluded_count, para que revises cuántos clientes entran.
• Envía dry_run: false (o quítalo) para crear la audiencia. Responde 201 con su segmentation_id.

2 Exportar a CSV

La exportación es asíncrona: primero se encola y después consultas la lista de descargas vigentes. Los tipos públicos son USERS_OF_LIST (clientes de audiencias) y CLIENT (clientes del comercio).

{
  "idExportType": "USERS_OF_LIST",
  "commerceId": 3,
  "uidCms": "<custom:uidCms>"
}

Devuelve las descargas vigentes con su url, status y fecha de retención.

La colección trae las variables baseUrl, token y commerceId vacías. Solo baseUrl viene con el host de este ambiente. En Postman: Import → Link.