API de integraciones
Conecta tu punto de venta, ERP u otro sistema con Fidly: identifica al beneficiario, calcula su descuento con las mismas reglas que la Caja de Fidly y registra la venta.
Inicio rápido
URL base
https://psxmyooqmdeqnuiseakm.supabase.co/functions/v1/api-v1
- Un administrador con acceso completo entra al panel de su empresa, abre Integraciones (API) y crea una llave con los permisos necesarios.
- Guarda la llave en el conector o en el servidor del POS. Se muestra una sola vez.
- Comprueba la conexión:
curl https://psxmyooqmdeqnuiseakm.supabase.co/functions/v1/api-v1/me \
-H "X-API-Key: cd_live_xxxxxxxxxx_..."
Todas las respuestas son JSON con la forma {"ok": true, "data": …} o {"ok": false, "error": {"code", "message"}}.
Autenticación y permisos
Envía la llave en el header X-API-Key (también se acepta Authorization: Bearer <llave>). Cada llave pertenece a una sola empresa: no puede ver beneficiarios, sucursales ni ventas de otra.
| Permiso (scope) | En el panel | Permite |
|---|---|---|
beneficiaries.read | Identificar beneficiarios | GET /beneficiaries/resolve |
discounts.quote | Cotizar descuentos | POST /discounts/quote |
discounts.write | Registrar ventas | POST /transactions |
/me y /branches funcionan con cualquier llave activa.
Límite: 120 solicitudes por minuto por llave (429 RATE_LIMITED al excederlo). Cada solicitud queda auditada y el panel muestra el último uso de cada llave. Revocar una llave desde el panel la desactiva de inmediato.
Flujo recomendado en caja
- Configura la sucursal una vez: llama
GET /branchesy guarda en el POS elidde la sucursal donde está instalado. - Identifica al cliente: escanea el QR de su app Fidly (o captura su código) y llama
GET /beneficiaries/resolve?token=…. Obtienes suid. - Cotiza:
POST /discounts/quoteconmember_id,subtotalybranch_id. Muestra el descuento y el total al cajero. - Cobra en tu POS.
- Registra la venta:
POST /transactionscon unIdempotency-Keyúnico por ticket. Si la red falla, reintenta con el mismo key: no se duplica.
Errores
| HTTP | code | Qué significa |
|---|---|---|
| 400 | INVALID_SUBTOTAL, MEMBER_ID_REQUIRED, BRANCH_REQUIRED, IDEMPOTENCY_KEY_REQUIRED, TOKEN_REQUIRED | Falta un dato o no es válido. |
| 401 | API_KEY_REQUIRED, API_KEY_INVALID, API_CLIENT_INVALID | Sin llave, llave incorrecta o revocada. |
| 403 | API_SCOPE_FORBIDDEN | La llave no tiene el permiso de ese endpoint. |
| 404 | BENEFICIARY_NOT_FOUND, MEMBER_NOT_FOUND, BRANCH_NOT_FOUND, NOT_FOUND | No existe o no pertenece a la empresa de la llave. |
| 409 | IDEMPOTENCY_KEY_REUSED, EXTERNAL_REFERENCE_DUPLICATED | Ese key ya se usó con otros datos, o ese folio ya se registró. |
| 422 | MEMBER_INACTIVE, INVALID_MEMBER_TYPE, MEMBER_NOT_ALLOWED_AT_BRANCH | El beneficiario no puede comprar con beneficio en esa sucursal. |
| 429 | RATE_LIMITED | Demasiadas solicitudes; espera y reintenta. |
Endpoints
/health
sin llaveComprueba que el servicio responde.
{ "ok": true, "api_version": "v1", "service": "control-descuentos" }
/me
cualquier llaveIdentidad y permisos de la llave. Úsalo para validar la configuración del conector.
{ "ok": true, "data": { "client_id": "uuid", "name": "POS Centro", "client_type": "pos",
"company_id": "uuid", "scopes": ["beneficiaries.read","discounts.quote","discounts.write"], "key_prefix": "41d27588d6" } }
/branches
cualquier llaveSucursales de la empresa con su franquicia y subfranquicia.
{ "ok": true, "data": [ { "id": 33, "code": "SG_CENTRO", "name": "SantaGloria Centro", "active": true,
"franchise_code": "SG_INDEFMX", "franchise_name": "SANTAGLORIA",
"subfranchise_code": null, "subfranchise_name": null } ] }
/beneficiaries/resolve?token=…
beneficiaries.readtoken puede ser el contenido del QR de la app del cliente o su código de miembro.
{ "ok": true, "data": { "id": "uuid", "member_code": "MEM-00123", "name": "Ana López",
"member_type": "customer", "discount_percent": 10, "active": true, "photo_url": null, "company_id": "uuid" } }
discount_percent es informativo. Para cobrar usa siempre /discounts/quote, que aplica límites y reglas por sucursal.
/discounts/quote
discounts.quote| Campo | Tipo | |
|---|---|---|
member_id | uuid | Obligatorio. El id de /beneficiaries/resolve. |
subtotal | número | Obligatorio, mayor que 0. |
branch_id | entero | Recomendado. Sin sucursal no se aplican las reglas por sucursal. |
curl -X POST …/api-v1/discounts/quote \
-H "X-API-Key: $FIDLY_KEY" -H "Content-Type: application/json" \
-d '{"member_id":"uuid","subtotal":500,"branch_id":33}'
{ "ok": true, "data": { "member_id": "uuid", "member_code": "MEM-00123", "member_name": "Ana López",
"member_type": "customer", "branch_id": 33, "subtotal": 500, "discount_percent": 10,
"eligible_amount": 500, "discount_amount": 50, "total_amount": 450, "company_id": "uuid" } }
eligible_amount es la parte del subtotal que recibe descuento (puede ser menor si el beneficiario alcanzó su límite).
/transactions
discounts.writeRegistra una venta completada. Suma la visita y el consumo del beneficiario, y aparece en Reportería como cualquier venta de Caja.
| Campo | Tipo | |
|---|---|---|
Idempotency-Key (header) | texto ≤ 100 | Obligatorio. Único por ticket, por ejemplo el UUID o folio interno del POS. |
member_id | uuid | Obligatorio. |
branch_id | entero | Obligatorio. |
subtotal | número | Obligatorio. Antes de descuento. |
external_reference | texto | Folio del ticket en el POS. No se puede repetir por llave. |
terminal_id | texto ≤ 60 | Caja o terminal, por ejemplo CAJA-01. |
notes | texto ≤ 500 | Opcional. |
curl -X POST …/api-v1/transactions \
-H "X-API-Key: $FIDLY_KEY" -H "Content-Type: application/json" \
-H "Idempotency-Key: 7f9c2e1a-ticket-84721" \
-d '{"member_id":"uuid","branch_id":33,"subtotal":500,"external_reference":"TICKET-84721","terminal_id":"CAJA-01"}'
HTTP 201
{ "ok": true, "data": { "operation_id": "uuid", "operation_code": "API-20260926-15D4C6B2",
"external_reference": "TICKET-84721", "member_id": "uuid", "member_code": "MEM-00123", "member_name": "Ana López",
"branch_id": 33, "branch_name": "SantaGloria Centro", "terminal_id": "CAJA-01", "subtotal": 500,
"discount_percent": 10, "discount_amount": 50, "total_amount": 450, "member_total_visits": 8,
"created_at": "2026-09-26T17:40:00Z", "replayed": false } }
Reintentos: si repites la solicitud con el mismo Idempotency-Key y los mismos datos, recibes la misma respuesta con "replayed": true y HTTP 200, sin crear otra venta. Con el mismo key y otros datos recibes 409 IDEMPOTENCY_KEY_REUSED.
Por ahora la API registra el descuento del beneficiario. Los cupones de campañas y las cancelaciones se siguen operando desde la Caja y el panel de Fidly.
Seguridad
- La llave es secreta: guárdala en el servidor o conector del POS. Nunca la pongas en una app móvil, en JavaScript de una página pública ni en un repositorio.
- Fidly solo guarda el hash de la llave; si se pierde, revócala y crea otra.
- Usa una llave por sistema o sucursal para poder revocar una sin afectar a las demás.
- Da solo los permisos necesarios. Un sistema que solo consulta no necesita "Registrar ventas".