Fidelify
{ }
Desarrolladores

API para punto de venta

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

01

Antes de empezar

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:

  • •Buscar a un cliente por teléfono, por el código de su pase o por su id.
  • •Registrar una venta y acreditar la recompensa que define el programa.
  • •Revertir una venta completa o en parte (devoluciones).
  • •Consultar una venta para conciliar contra el corte de caja.

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.

02

Conexión y autenticación

  • •URL base: https://auth.fidelify.mx/functions/v1/api-v1
  • •Autenticación: header Authorization: Bearer fk_live_… en cada solicitud.
  • •Formato: JSON en UTF-8, con Content-Type: application/json en los POST.
  • •Montos: enteros en centavos de peso mexicano. 35000 = $350.00. Un monto con decimales o como texto se rechaza.
  • •Límite: 60 solicitudes por minuto por API key. Al pasarlo respondemos 429 rate_limited con el header Retry-After: 60.
  • •Cada respuesta trae el header 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"
03

API keys

  • •Las crea el dueño o un administrador del negocio en Configuración → Integraciones → API para punto de venta. La key completa se muestra una sola vez; Fidelify solo guarda su huella.
  • •Formato: fk_live_ o fk_test_ seguido de 43 letras y números.
  • •Cada key queda ligada a un negocio, a un programa de lealtad y, si el negocio lo elige, a una sucursal. Esos datos nunca se mandan en la solicitud: los resuelve la key.
  • •Permisos: customers:read para buscar clientes y transactions:write para registrar, revertir y consultar ventas.
  • •Las keys no caducan. Dejan de funcionar al instante si el negocio las revoca, y también si la API se desactiva para el negocio, si el plan deja de ser Pro o si el programa se desactiva (401 o 403; ver errores).
  • •Trata la key como una contraseña: guárdala en el servidor o en la configuración protegida de la caja, nunca en una página web ni en código que se distribuya.
04

Modo de prueba

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.

  • •Las respuestas traen "mode": "test".
  • •La venta sale con "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.
  • •Las ventas de prueba tienen su propio espacio de external_ref: no chocan con las reales.
  • •Cuentan para el límite de 60 solicitudes por minuto.
05

Buscar cliente

GET/customers/lookuppermiso: customers:read

Manda uno solo de estos parámetros:

ParámetroQué acepta
phoneTelé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_codeEl código del QR o del código de barras del pase del cliente (sin distinguir mayúsculas).
customer_idEl 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.

06

Registrar venta

POST/transactionspermiso: transactions:write

Requiere el header Idempotency-Key (ver idempotencia).

CampoDescripción
amount_centsobligatorioTotal de la venta en centavos. Entero mayor que 0.
external_refobligatorioTu 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.
customeropcionalObjeto 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_atopcionalFecha 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_refopcionalQuién cobró (clave o nombre del cajero). Se guarda hasta 80 caracteres.
itemsopcionalLista 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 }]
  }'

Reglas

  • •La recompensa (porcentaje de cashback, puntos o sellos) la define el programa en el panel del negocio. Si el body trae rate, rate_bps, cashback_rate, percentage o cashback_percentage, la venta se rechaza con 422.
  • •Si el cliente se busca por 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).
  • •Tope por ticket: $5,000 por omisión, configurable por el negocio entre $500 y $50,000, y nunca más de $100,000 por solicitud. Por encima: 422 limit_exceeded.
  • •El cashback queda pendiente durante el periodo de retención del negocio (24 horas por omisión, contadas desde que se registra la venta) y después pasa a disponible. 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.

07

Revertir venta

POST/transactions/{id}/reversepermiso: transactions:write

Para devoluciones y cancelaciones. Requiere Idempotency-Key.

CampoDescripción
amount_centsopcionalCuánto se devuelve, en centavos. Sin este campo se revierte todo lo que queda de la venta.
reasonopcionalMotivo, 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" }'
  • •El cashback y los puntos se revierten en proporción al monto devuelto.
  • •Los sellos solo se retiran cuando se revierte la venta completa.
  • •Si el cliente ya usó ese cashback, su saldo puede quedar negativo; se compensa con sus siguientes compras.
  • •La respuesta (200) tiene la misma forma que la de la venta, con status partially_reversed o reversed y el campo extra cashback_reversed_cents.
  • •Pedir más de lo que queda da 422 amount_exceeds_remaining; revertir una venta ya revertida por completo da 409 invalid_state.
08

Consultar venta

GET/transactions/{id}permiso: transactions:write

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

Idempotencia y reintentos

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.

  • •Si se cae la red o no recibes respuesta, reintenta con la misma key y el mismo body: si la venta ya se registró, recibes la respuesta original con el header Idempotent-Replayed: true y no se duplica nada.
  • •La misma key con un body distinto da 409 idempotency_conflict.
  • •Si la primera solicitud sigue en proceso, recibes 409 idempotency_in_progress: espera unos segundos y reintenta.
  • •Un rechazo (4xx) también queda guardado: reintentar con la misma key devuelve el mismo error. Corrige los datos y usa una key nueva.
  • •Un error 5xx libera la key: reintenta con la misma.
10

Errores

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_…"
  }
}
HTTPcodeQué hacer
400missing_idempotency_key invalid_jsonCorregir la solicitud.
401missing_api_key invalid_api_keyRevisar la key o pedir una nueva al negocio.
403insufficient_scope feature_disabled plan_required ip_not_allowed program_inactive account_blockedHablar con el negocio: es un tema de su cuenta o de los permisos de la key.
404customer_not_found transaction_not_found not_foundRevisar el identificador o la ruta.
405method_not_allowedUsar el método indicado en esta guía.
409duplicate_external_ref idempotency_conflict idempotency_in_progress invalid_stateNo reintentar igual (salvo idempotency_in_progress, que se reintenta tras unos segundos).
422validation_error limit_exceeded stale_transaction invalid_occurred_at invalid_amount amount_exceeds_remainingCorregir los datos. message dice qué campo falló.
429rate_limitedEsperar lo que indica Retry-After.
5xxinternal_errorReintentar con la misma Idempotency-Key.
11

Soporte

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.