Documentación · API

API de Lealtad

Conecta tu programa de lealtad directo con tu propio sistema — POS, CRM, lo que ya uses. Consulta saldos, abona puntos, canjea premios y da de alta clientes, todo desde tu código.

Autenticación

Cada solicitud necesita tu llave de API en el header Authorization. Genera tu llave desde tu panel, en la sección "API" de tu negocio.

Authorization: Bearer lz_TU_LLAVE_AQUI

Tu llave da acceso completo a los datos de tu negocio únicamente — nunca a los de otros negocios. Puedes tener varias llaves activas (por ejemplo, una por sucursal o por sistema) y revocarlas individualmente sin afectar las demás.

Antes de empezar

Base URL: https://kredentik.com/api/
Formato: todo el cuerpo de las solicitudes POST es JSON (Content-Type: application/json), y todas las respuestas también son JSON.
Límite de frecuencia: 60 solicitudes por minuto por llave.
Identificar una tarjeta: casi todos los endpoints aceptan code (el código impreso en la tarjeta física) o phone (para tarjetas digitales por teléfono) — solo mandas uno de los dos.
Errores: siempre regresan {"success": false, "error": {"code": "...", "message": "..."}} con el código HTTP correspondiente (400, 401, 403, 404, 409, 429).

Endpoints

GET/lealtad_api_tarjeta.php

Consulta el saldo y los datos de una tarjeta.

Parámetro	Tipo	Descripción
code	query	Código impreso en la tarjeta física.
phone	query	Teléfono del cliente (tarjeta digital). Usa uno u otro.

curl "https://kredentik.com/api/lealtad_api_tarjeta.php?code=AB12CD34" \
  -H "Authorization: Bearer lz_TU_LLAVE"

{
  "success": true,
  "data": {
    "code": "AB12CD34",
    "phone": null,
    "customer_name": "Juan Pérez",
    "balance_points": 45,
    "created_at": "2026-08-01 10:00:00",
    "activated_at": "2026-08-03 18:22:10"
  }
}

POST/lealtad_api_abonar.php

Registra una compra y abona los puntos/sellos correspondientes. Aplica las mismas validaciones anti-fraude que la pantalla del cajero: el folio no se puede repetir el mismo día, y hay un límite de frecuencia por tarjeta.

Campo	Obligatorio	Descripción
code	Uno de los dos	Código de la tarjeta.
phone	Uno de los dos	Teléfono del cliente.
folio	Sí	Número de ticket/comanda de la venta.
amount	Solo si el negocio es "por puntos"	Monto de la compra.

curl -X POST "https://kredentik.com/api/lealtad_api_abonar.php" \
  -H "Authorization: Bearer lz_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{"code": "AB12CD34", "folio": "00456", "amount": 250.00}'

{
  "success": true,
  "data": {
    "points_earned": 25,
    "card": { "code": "AB12CD34", "balance_points": 70, ... }
  }
}

POST/lealtad_api_canjear.php

Canjea un premio del catálogo. A diferencia de la pantalla del cajero, esto no pide PIN de gerente — tu llave de API ya es la autorización, así que tu sistema es responsable de cuándo la usa.

Campo	Obligatorio	Descripción
code	Uno de los dos	Código de la tarjeta.
phone	Uno de los dos	Teléfono del cliente.
reward_id	Sí	ID del premio (ver /lealtad_api_premios.php).

curl -X POST "https://kredentik.com/api/lealtad_api_canjear.php" \
  -H "Authorization: Bearer lz_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{"code": "AB12CD34", "reward_id": 3}'

GET/lealtad_api_premios.php

Lista el catálogo de premios activos de tu negocio.

curl "https://kredentik.com/api/lealtad_api_premios.php" \
  -H "Authorization: Bearer lz_TU_LLAVE"

{ "success": true, "data": { "rewards": [
  { "id": 3, "name": "Postre gratis", "cost_points": 50 },
  { "id": 4, "name": "10% de descuento", "cost_points": 20 }
] } }

POST/lealtad_api_crear_tarjeta.php

Da de alta una tarjeta digital nueva por teléfono — útil si tu sistema registra clientes nuevos automáticamente en el punto de venta. Si el teléfono ya tenía tarjeta en tu negocio, regresa la existente en vez de duplicarla.

Campo	Obligatorio	Descripción
phone	Sí	Teléfono del cliente.
name	No	Nombre del cliente.

curl -X POST "https://kredentik.com/api/lealtad_api_crear_tarjeta.php" \
  -H "Authorization: Bearer lz_TU_LLAVE" \
  -H "Content-Type: application/json" \
  -d '{"phone": "5551234567", "name": "Ana López"}'

Códigos de error comunes

HTTP	Código	Significado
401	invalid_api_key	La llave no existe o fue revocada.
403	business_not_active	El negocio no tiene el servicio activo (pendiente de pago o vencido).
404	card_not_found	No existe ninguna tarjeta con ese código/teléfono en este negocio.
409	transaction_rejected	Folio repetido, o la tarjeta abonó hace muy poco tiempo.
409	insufficient_balance	La tarjeta no tiene saldo suficiente para el premio.
429	rate_limited	Más de 60 solicitudes por minuto con esa llave.

¿Ya tienes tu programa de Lealtad en Kredentik? Genera tu llave desde tu cuenta.

Iniciar sesión