Fidly

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
  1. Un administrador con acceso completo entra al panel de su empresa, abre Integraciones (API) y crea una llave con los permisos necesarios.
  2. Guarda la llave en el conector o en el servidor del POS. Se muestra una sola vez.
  3. 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 panelPermite
beneficiaries.readIdentificar beneficiariosGET /beneficiaries/resolve
discounts.quoteCotizar descuentosPOST /discounts/quote
discounts.writeRegistrar ventasPOST /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

  1. Configura la sucursal una vez: llama GET /branches y guarda en el POS el id de la sucursal donde está instalado.
  2. Identifica al cliente: escanea el QR de su app Fidly (o captura su código) y llama GET /beneficiaries/resolve?token=…. Obtienes su id.
  3. Cotiza: POST /discounts/quote con member_id, subtotal y branch_id. Muestra el descuento y el total al cajero.
  4. Cobra en tu POS.
  5. Registra la venta: POST /transactions con un Idempotency-Key único por ticket. Si la red falla, reintenta con el mismo key: no se duplica.
El descuento siempre lo calcula Fidly. La API no acepta montos de descuento enviados por el POS. Usa las mismas reglas que la Caja de Fidly: porcentaje del tipo de beneficiario, límites de monto y sucursales de subfranquicia sin descuento. No guardes porcentajes en el POS como fuente de verdad.

Errores

HTTPcodeQué significa
400INVALID_SUBTOTAL, MEMBER_ID_REQUIRED, BRANCH_REQUIRED, IDEMPOTENCY_KEY_REQUIRED, TOKEN_REQUIREDFalta un dato o no es válido.
401API_KEY_REQUIRED, API_KEY_INVALID, API_CLIENT_INVALIDSin llave, llave incorrecta o revocada.
403API_SCOPE_FORBIDDENLa llave no tiene el permiso de ese endpoint.
404BENEFICIARY_NOT_FOUND, MEMBER_NOT_FOUND, BRANCH_NOT_FOUND, NOT_FOUNDNo existe o no pertenece a la empresa de la llave.
409IDEMPOTENCY_KEY_REUSED, EXTERNAL_REFERENCE_DUPLICATEDEse key ya se usó con otros datos, o ese folio ya se registró.
422MEMBER_INACTIVE, INVALID_MEMBER_TYPE, MEMBER_NOT_ALLOWED_AT_BRANCHEl beneficiario no puede comprar con beneficio en esa sucursal.
429RATE_LIMITEDDemasiadas solicitudes; espera y reintenta.

Endpoints

GET

/health

sin llave

Comprueba que el servicio responde.

{ "ok": true, "api_version": "v1", "service": "control-descuentos" }
GET

/me

cualquier llave

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

/branches

cualquier llave

Sucursales 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 } ] }
GET

/beneficiaries/resolve?token=…

beneficiaries.read

token 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.

POST

/discounts/quote

discounts.quote
CampoTipo
member_iduuidObligatorio. El id de /beneficiaries/resolve.
subtotalnúmeroObligatorio, mayor que 0.
branch_identeroRecomendado. 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).

POST

/transactions

discounts.write

Registra una venta completada. Suma la visita y el consumo del beneficiario, y aparece en Reportería como cualquier venta de Caja.

CampoTipo
Idempotency-Key (header)texto ≤ 100Obligatorio. Único por ticket, por ejemplo el UUID o folio interno del POS.
member_iduuidObligatorio.
branch_identeroObligatorio.
subtotalnúmeroObligatorio. Antes de descuento.
external_referencetextoFolio del ticket en el POS. No se puede repetir por llave.
terminal_idtexto ≤ 60Caja o terminal, por ejemplo CAJA-01.
notestexto ≤ 500Opcional.
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