1 La API key

Leal te la entrega al activar el comercio, una por ambiente. Envíala en cada llamada, salvo en las anulaciones.

Authorization: Bearer <API key>

La de QA no sirve en producción. En Puntos agrega X-API-Version: 1.

2 Sigue este orden

El uid que devuelve Usuarios es el member_ref que pide Puntos. El comercio es el de tu API key. GET /v1/loyalty/public/whoami lo confirma.

1 Cómo enviarla

Authorization: Bearer <API key>

Para probar una operación, ábrela en Referencia y pega la API key en Authentication. En Postman usa la variable apiKey.

2 Qué identifica

La API key identifica a tu comercio. El cliente final se crea o se busca en Usuarios.

Las anulaciones no usan esta API key. Se firman con AWS Signature Version 4. El header Authorization empieza por AWS4-HMAC-SHA256.

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 comercio de tu API key. Para quitar la asociación: PUT /v3/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 tu usuario en Leal. commerce_id es el de tu API key. Guarda el id de la sucursal donde opera la caja.

1 Comercio y saldo

Devuelve el commerce_id de tu API key.

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.
• Si la venta trae líneas, envía items. product_code es el SKU. Sin items, el cálculo usa gross_amount.

3 Premios del comercio

El reward_id de la redención es el id_reward de esta lista. id_commerce es el de tu API key.

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

Estas dos llamadas se firman con AWS Signature Version 4. El header Authorization empieza por AWS4-HMAC-SHA256. No llevan la API key.

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

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": "<uid_cms>"
}

Devuelve las descargas vigentes con su url y su status.

En Referencia puedes descargar la colección. En Postman: Import → Link. baseUrl arranca en QA; para producción usa https://api.leal.co.