Desarrolladores

Big Fidelity API

La API pública de Big Fidelity permite que un POS, un e-commerce o un sistema propio registre clientes, emita tarjetas de Apple Wallet y Google Wallet, sume sellos, registre visitas y acredite o canjee puntos, sin pasar por el panel.

La especificación completa, lista para generar un cliente, está en /openapi.json (OpenAPI 3.1).

URL base

Producción: https://bigfidelity.xyz/api/v1
Staging: te pasamos la URL junto con las credenciales de prueba.

Autenticación

Cada request lleva dos credenciales: una API key que identifica al comercio y un token que identifica al usuario que actúa en su nombre.

X-API-Key: bf_live_xxxxxxxxxxxxxxxxxxxx
Authorization: Token abc123def456...

El token se obtiene una vez con POST /auth/token y no vence. El usuario debe pertenecer al mismo comercio que la API key. Las claves se emiten por comercio: pedí la tuya escribiendo a hello@bigfidelity.com. No hay alta automática.

Identificación de clientes

Los clientes se direccionan con tu propio identificador — external_id — más el business_template_id del programa. Nunca necesitás guardar los IDs internos de Big Fidelity: cada API key tiene su propio espacio de nombres de external_id.

Tipos de programa

Código	Tipo	Uso típico
`S`	Sellos	Cafeterías, panaderías, locales de visita frecuente.
`C`	Cupones	Promociones y descuentos de un solo uso.
`M`	Membresías	Gimnasios, clubes, programas con visitas.
`P`	Puntos	Retail y gastronomía con ticket variable.

Endpoints

Método	Ruta	Qué hace	Permiso
POST	`/auth/token`	Obtener el token de usuario a partir de sus credenciales.	`—`
POST	`/consumers/register`	Registrar un cliente y generar sus tarjetas de Apple Wallet y Google Wallet.	`can_register_consumers`
GET	`/consumers/info`	Consultar perfil y saldo (sellos, puntos, visitas) del cliente.	`can_read_consumers`
POST	`/consumers/update`	Actualizar los datos de perfil de un cliente ya registrado.	`can_register_consumers`
POST	`/stamps/add`	Agregar sellos a una tarjeta (admite valores negativos para corregir).	`can_update_stamps`
POST	`/visits/add`	Registrar una visita en una tarjeta de membresía.	`can_update_visits`
POST	`/points/earn`	Acreditar puntos por una compra.	`can_earn_points`
POST	`/points/redeem`	Canjear puntos por un descuento.	`can_redeem_points`

La API también expone catálogo de premios, emisión y canje de premios, productos y registro de ventas para integraciones de POS. Esos endpoints se documentan durante el onboarding de la integración; escribinos y te pasamos el detalle.

Ejemplo

# 1. Obtener el token (una sola vez, guardalo)
curl -X POST https://bigfidelity.xyz/api/v1/auth/token \
  -H "X-API-Key: bf_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"username":"caja@tunegocio.com","password":"..."}'

# 2. Acreditar puntos por una compra
curl -X POST https://bigfidelity.xyz/api/v1/points/earn \
  -H "X-API-Key: bf_live_xxxxx" \
  -H "Authorization: Token abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "cliente-123",
    "business_template_id": "6",
    "purchase_amount": "150.00",
    "metadata": {"invoice_number": "A-0001"}
  }'

Límites de uso

Cada API key tiene límites por minuto y por hora. Toda respuesta incluye los encabezados X-RateLimit-Limit-Minute, X-RateLimit-Remaining-Minute y sus equivalentes por hora. Al superarlos la API responde 429 con el código RATE_LIMIT_EXCEEDED.

Errores

Los errores siempre tienen esta forma:

{
  "error": {
    "message": "Consumer not registered for this template",
    "code": "NOT_REGISTERED"
  }
}

HTTP	Significado
`400`	Parámetros inválidos o incompletos.
`401`	API key o token de usuario ausente o inválido.
`403`	La API key no tiene el permiso requerido.
`404`	Cliente o programa inexistente.
`409`	El cliente ya estaba registrado en ese programa.
`429`	Se superó el límite de requests.
`500`	Error del servidor.

Pedir acceso

Escribinos a hello@bigfidelity.com contando qué sistema vas a integrar y qué operaciones necesitás. Emitimos la API key con los permisos acotados a eso y te damos acceso a staging para probar. Si todavía estás evaluando el producto, empezá por la página de contacto.