
Conecta tu sistema de caja (Aspel, un POS propio o cualquier software) con el programa de lealtad del negocio: busca al cliente, registra la venta y Fidelify calcula el cashback, los puntos o los sellos y actualiza el pase del cliente en su Wallet.
Versión 1 · Última actualización — 19 de noviembre de 2026
La API está disponible para negocios con plan Pro y se activa por negocio. Si eres el integrador, pide al negocio que te genere una API key desde su panel; si eres el negocio y todavía no ves la opción, escríbenos a soporte@fidelify.mx.
Esta versión permite:
Los canjes de saldo desde la caja llegan en la siguiente versión. La API no crea clientes: el cliente se registra en el programa desde el link o el QR del negocio.
https://auth.fidelify.mx/functions/v1/api-v1Authorization: Bearer fk_live_… en cada solicitud.Content-Type: application/json en los POST.35000 = $350.00. Un monto con decimales o como texto se rechaza.429 rate_limited con el header Retry-After: 60.Fidelify-Request-Id (también en el cuerpo de los errores). Inclúyelo cuando nos reportes un problema.curl "https://auth.fidelify.mx/functions/v1/api-v1/customers/lookup?phone=5512345678" \
-H "Authorization: Bearer fk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"fk_live_ o fk_test_ seguido de 43 letras y números.customers:read para buscar clientes y transactions:write para registrar, revertir y consultar ventas.401 o 403; ver errores).Una key fk_test_ hace las mismas validaciones y registra la venta, pero no mueve ningún saldo ni actualiza el pase del cliente. Úsala para desarrollar contra clientes reales del programa sin afectarlos.
"mode": "test"."status": "credited" y con el cashback, los puntos y los sellos que le habrían tocado, para que verifiques el cálculo. cashback.available_at viene en null y customer_balance muestra el saldo real del cliente, que no cambia.external_ref: no chocan con las reales./customers/lookuppermiso: customers:readManda uno solo de estos parámetros:
| Parámetro | Qué acepta |
|---|---|
phone | Teléfono en cualquier formato. Se ignoran espacios, guiones, paréntesis y +, y se comparan los últimos 10 dígitos: 5512345678, (55) 1234-5678 y +52 55 1234 5678 encuentran al mismo cliente. Con menos de 10 dígitos se rechaza. |
pass_code | El código del QR o del código de barras del pase del cliente (sin distinguir mayúsculas). |
customer_id | El id que devuelve la API, con forma cus_…. |
En la URL, el signo + debe ir codificado como %2B. Si dos clientes del programa comparten teléfono, se devuelve el que tuvo actividad más reciente; para no depender de eso, usa pass_code o customer_id.
200 OK
{
"customer_id": "cus_3f2a…",
"display_name": "Ana M.",
"cashback_available_cents": 4550,
"cashback_pending_cents": 1200,
"points": 0,
"stamps": 3,
"rewards_available": [{ "id": "rwd_stamps", "name": "Café gratis", "quantity": 1 }]
}display_name es el nombre con la inicial del apellido. cashback_pending_cents es cashback ganado que todavía está en su periodo de retención. Si no existe el cliente en el programa: 404 customer_not_found.
/transactionspermiso: transactions:writeRequiere el header Idempotency-Key (ver idempotencia).
| Campo | Descripción | |
|---|---|---|
amount_cents | obligatorio | Total de la venta en centavos. Entero mayor que 0. |
external_ref | obligatorio | Tu folio o número de ticket, de 1 a 120 caracteres. Es único por negocio, sucursal de la key y modo: repetirlo da 409 duplicate_external_ref. |
customer | opcional | Objeto con uno solo de customer_id, phone o pass_code (mismas reglas que en la búsqueda). Sin cliente, la venta se registra sin recompensa. |
occurred_at | opcional | Fecha y hora de la venta en ISO 8601 con zona horaria, p. ej. 2026-11-17T16:40:00-06:00. Si no se manda, se usa la hora en que Fidelify recibe la venta. |
cashier_ref | opcional | Quién cobró (clave o nombre del cajero). Se guarda hasta 80 caracteres. |
items | opcional | Lista de hasta 200 renglones con el formato que use tu sistema. Se guarda para consulta; no cambia la recompensa. |
curl -X POST "https://auth.fidelify.mx/functions/v1/api-v1/transactions" \
-H "Authorization: Bearer fk_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: suc01-ticket-000123" \
-d '{
"customer": { "phone": "5512345678" },
"amount_cents": 35000,
"external_ref": "TICKET-000123",
"occurred_at": "2026-11-17T16:40:00-06:00",
"cashier_ref": "CAJERO-02",
"items": [{ "sku": "CAF-01", "qty": 2, "amount_cents": 9000 }]
}'rate, rate_bps, cashback_rate, percentage o cashback_percentage, la venta se rechaza con 422.phone y no existe, la venta se registra igual, sin cliente y sin recompensa. Si se busca por customer_id o pass_code y no existe, se rechaza con 404 customer_not_found.occurred_at no puede estar más de 5 minutos en el futuro (422 invalid_occurred_at) ni tener más antigüedad de la que permite el negocio, 72 horas por omisión (422 stale_transaction).422 limit_exceeded.cashback.available_at dice cuándo.201 Created
{
"id": "txn_8c1d…",
"status": "credited",
"mode": "live",
"amount_cents": 35000,
"external_ref": "TICKET-000123",
"customer_id": "cus_3f2a…",
"cashback": { "rate_bps": 1000, "amount_cents": 3500, "available_at": "2026-11-18T22:40:00Z" },
"points": 0,
"stamps": 0,
"customer_balance": { "available_cents": 4550, "pending_cents": 4700 }
}rate_bps es la tasa en puntos base (1000 = 10 %). customer_id y customer_balance vienen en null cuando la venta no tiene cliente.
/transactions/{id}/reversepermiso: transactions:writePara devoluciones y cancelaciones. Requiere Idempotency-Key.
| Campo | Descripción | |
|---|---|---|
amount_cents | opcional | Cuánto se devuelve, en centavos. Sin este campo se revierte todo lo que queda de la venta. |
reason | opcional | Motivo, hasta 200 caracteres. |
curl -X POST "https://auth.fidelify.mx/functions/v1/api-v1/transactions/txn_8c1d…/reverse" \
-H "Authorization: Bearer fk_live_…" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: suc01-devolucion-000123-1" \
-d '{ "amount_cents": 17500, "reason": "devolucion" }'200) tiene la misma forma que la de la venta, con status partially_reversed o reversed y el campo extra cashback_reversed_cents.422 amount_exceeds_remaining; revertir una venta ya revertida por completo da 409 invalid_state./transactions/{id}permiso: transactions:writePara conciliar contra el corte de caja. Devuelve la venta con sus reversos acumulados:
200 OK
{
"id": "txn_8c1d…",
"status": "partially_reversed",
"mode": "live",
"amount_cents": 35000,
"reversed_cents": 17500,
"external_ref": "TICKET-000123",
"cashier_ref": "CAJERO-02",
"occurred_at": "2026-11-17T22:40:00+00:00",
"customer_id": "cus_3f2a…",
"cashback": { "rate_bps": 1000, "amount_cents": 3500, "reversed_cents": 1750, "available_at": "2026-11-18T22:40:00+00:00" },
"points": 0,
"stamps": 0,
"created_at": "2026-11-17T22:40:01+00:00"
}Todo POST lleva el header Idempotency-Key: un texto de hasta 200 caracteres que tú generas y que identifica esa operación, por ejemplo suc01-ticket-000123.
Idempotent-Replayed: true y no se duplica nada.409 idempotency_conflict.409 idempotency_in_progress: espera unos segundos y reintenta.4xx) también queda guardado: reintentar con la misma key devuelve el mismo error. Corrige los datos y usa una key nueva.5xx libera la key: reintenta con la misma.Todos los errores tienen la misma forma:
{
"error": {
"code": "duplicate_external_ref",
"message": "Ya existe una venta con ese external_ref en esta sucursal",
"request_id": "req_…"
}
}| HTTP | code | Qué hacer |
|---|---|---|
| 400 | missing_idempotency_key invalid_json | Corregir la solicitud. |
| 401 | missing_api_key invalid_api_key | Revisar la key o pedir una nueva al negocio. |
| 403 | insufficient_scope feature_disabled plan_required ip_not_allowed program_inactive account_blocked | Hablar con el negocio: es un tema de su cuenta o de los permisos de la key. |
| 404 | customer_not_found transaction_not_found not_found | Revisar el identificador o la ruta. |
| 405 | method_not_allowed | Usar el método indicado en esta guía. |
| 409 | duplicate_external_ref idempotency_conflict idempotency_in_progress invalid_state | No reintentar igual (salvo idempotency_in_progress, que se reintenta tras unos segundos). |
| 422 | validation_error limit_exceeded stale_transaction invalid_occurred_at invalid_amount amount_exceeds_remaining | Corregir los datos. message dice qué campo falló. |
| 429 | rate_limited | Esperar lo que indica Retry-After. |
| 5xx | internal_error | Reintentar con la misma Idempotency-Key. |
Escríbenos a soporte@fidelify.mx con el request_id de la respuesta, la fecha y hora y, si aplica, el external_ref del ticket. Nunca nos mandes la API key completa: con sus últimos 4 caracteres basta para identificarla.