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": "7mbur3nq4hsqtnn1s5qu0dub54",
  "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": "283qnh9mpsdlsfl8buismud68e",
  "AuthParameters": {
    "USERNAME": "<usuario>",
    "PASSWORD": "<contraseña>"
  }
}

La respuesta trae AuthenticationResult.AccessToken. Ese valor es el Bearer de Usuarios, Puntos y CDP. Cuando vence, se pide otro con los mismos datos. El formulario de abajo usa el host y el ClientId de este ambiente.

2 Qué trae el token

No hace falta decodificarlo para llamar al API: se envía completo en Authorization. Estos claims son los que las demás secciones reutilizan.

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. Hoy la única ruta del catálogo es interna (GET /internal/reward-catalog). No hay GET /v1/loyalty/public/reward-catalog y la referencia no la publica.

4 Redimir, con el OTP en tus manos

El endpoint de redención no revisa el código. Tú lo envías, lo validas y solo entonces redimes.

{
  "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": "000000"
}

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. El contrato no declara credencial: van al plano del ledger.

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

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.