Fonealo

Conecta tu sistema con Fonealo

La API de integraciones permite que tu punto de venta u otro sistema opere el programa de lealtad de un negocio: sellar visitas, inscribir clientes y canjear recompensas, con autorización del dueño mediante OAuth2.

Crea tu aplicaciónCómo funciona

Cómo funciona la conexión

Usamos el flujo estándar de OAuth2 con código de autorización y PKCE. El dueño del negocio aprueba el acceso desde su cuenta de Fonealo y tu sistema recibe un token con los permisos que solicitaste.

  1. 1. Envía al dueño a autorizar

    Desde tu sistema, un botón «Conectar Fonealo» redirige al dueño del negocio a la pantalla de autorización. Genera un code_verifier aleatorio, guárdalo, y envía como code_challenge su SHA-256 en base64url. Siempre usamos S256; no necesitas indicar el método.

    https://fonealo.com/oauth/authorize    ?client_id=TU_CLIENT_ID    &redirect_uri=https://tusistema.mx/callback    &response_type=code    &scope=service:read loyalty:read loyalty:write    &code_challenge=SHA256_BASE64URL_DEL_VERIFIER

  2. 2. El dueño elige su negocio y aprueba

    Fonealo le muestra qué permisos pides y le pide elegir cuál de sus negocios conectar. Al aprobar, lo regresamos a tu redirect_uri con un código de un solo uso.

    https://tusistema.mx/callback    ?code=CODIGO_DE_UN_SOLO_USO

  3. 3. Intercambia el código por tokens

    Envía el code_verifier que guardaste en el paso 1 y el client_secret que obtuviste al crear tu aplicación (si es una app pública sin secreto, omite esa línea). El access token dura 12 horas y el refresh token 30 días; renueva con grant_type=refresh_token cuando expire.

    curl -X POST https://fonealo.com/oauth/token \    -d grant_type=authorization_code \    -d client_id=TU_CLIENT_ID \    -d client_secret=TU_CLIENT_SECRET \    -d redirect_uri=https://tusistema.mx/callback \    -d code_verifier=TU_VERIFIER \    -d code=CODIGO_DE_UN_SOLO_USO

  4. 4. Confirma el negocio conectado

    Con el token, consulta /me: devuelve el negocio que el dueño conectó a tu aplicación. No necesitas construir un selector; el token solo opera ese negocio.

    curl https://fonealo.com/api/integrations/v1/me \    -H "Authorization: Bearer TU_ACCESS_TOKEN"

Permisos disponibles

Solicita solo los alcances que tu integración necesita. El dueño ve esta misma descripción al autorizar.

AlcancePermite
service:readConsultar la información de tus negocios
loyalty:readConsultar tarjetas de lealtad y el estado de los pases de tus clientes
loyalty:writeAgregar sellos, inscribir clientes y canjear recompensas de lealtad

Dos formas de sellar

Con escáner, cuando el cliente está presente

Envía a /scan el código tal como lo leyó tu escáner, sin procesarlo. Puede ser el QR del pase de cartera del cliente (un UUID) o su QR personal de Fonealo con su usuario, en cualquiera de sus formas: ana, @ana o fonealo://u/ana. Nosotros lo resolvemos, sin importar mayúsculas. Si el cliente aún no está inscrito en la tarjeta, la primera lectura de su usuario lo inscribe automáticamente, igual que el escáner de caja de la app.

Sin QR, desde tu punto de venta

Si tu sistema ya conoce al cliente, llama a /auto-stamp al cerrar la orden con su correo o teléfono, y opcionalmente su nombre, el monto y tu referencia de orden. Si ese cliente después muestra su QR de Fonealo, llama a /link una vez y todo su historial aparece en su app. Los teléfonos se comparan por sus últimos 10 dígitos, así que las diferencias de formato con +52 no duplican clientes.

Reintentos seguros

Todos los endpoints de escritura aceptan un encabezado Idempotency-Key. En /auto-stamp, tu external_reference funciona como esa clave. Si reintentas con la misma clave, respondemos el resultado original con el encabezado Idempotent-Replay: true en lugar de sellar dos veces. Las peticiones se limitan a 120 por minuto por token.

Endpoints principales

Rutas completas sobre https://fonealo.com. Todas responden JSON y requieren Authorization: Bearer con tu access token.

GET/api/integrations/v1/me

El negocio conectado a tu aplicación, el usuario que autorizó y los alcances del token. Toma de aquí el {slug} para las demás rutas.

Ver ejemplo
curl https://fonealo.com/api/integrations/v1/me \    -H "Authorization: Bearer TU_ACCESS_TOKEN"# Respuesta{    "user": { "id": 7, "name": "Ana" },    "scopes": ["service:read", "loyalty:read", "loyalty:write"],    "services": [{ "id": 4, "slug": "taqueria-la-nortena", "name": "Taquería La Norteña" }]}
GET/api/integrations/v1/services/{slug}

Perfil del negocio. Requiere el alcance service:read.

Ver ejemplo
curl https://fonealo.com/api/integrations/v1/services/taqueria-la-nortena \    -H "Authorization: Bearer TU_ACCESS_TOKEN"
GET/api/integrations/v1/services/{slug}/loyalty-cards

Tarjetas de lealtad del negocio, con su vigencia. También acepta /{id} para una sola. Requiere el alcance loyalty:read.

Ver ejemplo
curl https://fonealo.com/api/integrations/v1/services/taqueria-la-nortena/loyalty-cards \    -H "Authorization: Bearer TU_ACCESS_TOKEN"
GET/api/integrations/v1/services/{slug}/loyalty-cards/{id}/scan

Consulta el estado de un pase escaneado sin agregar sellos. Requiere el alcance loyalty:read.

  • coderequerido

    en la query, tal como lo leyó tu escáner: QR del pase (UUID) o QR Fonealo del cliente (usuario, con o sin @, o fonealo://u/…). Si el cliente existe pero no está inscrito responde 404 con code not_enrolled

Ver ejemplo
curl "https://fonealo.com/api/integrations/v1/services/taqueria-la-nortena/loyalty-cards/12/scan?code=CODIGO_ESCANEADO" \    -H "Authorization: Bearer TU_ACCESS_TOKEN"
POST/api/integrations/v1/services/{slug}/loyalty-cards/{id}/scan

Agrega un sello a partir de un código escaneado. Si el código es un usuario Fonealo sin inscribir, lo inscribe automáticamente. Requiere el alcance loyalty:write.

  • coderequerido

    tal como lo leyó tu escáner: QR del pase (UUID) o QR Fonealo del cliente (usuario, con o sin @, o fonealo://u/…)

  • amount

    monto de la venta, para tus reportes

Ver ejemplo
curl -X POST https://fonealo.com/api/integrations/v1/services/taqueria-la-nortena/loyalty-cards/12/scan \    -H "Authorization: Bearer TU_ACCESS_TOKEN" \    -H "Idempotency-Key: TU_CLAVE_UNICA" \    -d code=CODIGO_ESCANEADO \    -d amount=150.50
POST/api/integrations/v1/services/{slug}/loyalty-cards/{id}/redeem

Canjea una tarjeta completada y comienza un nuevo ciclo de sellos. Requiere el alcance loyalty:write.

  • coderequerido

    tal como lo leyó tu escáner: QR del pase (UUID) o QR Fonealo del cliente (usuario, con o sin @, o fonealo://u/…)

Ver ejemplo
curl -X POST https://fonealo.com/api/integrations/v1/services/taqueria-la-nortena/loyalty-cards/12/redeem \    -H "Authorization: Bearer TU_ACCESS_TOKEN" \    -d code=CODIGO_ESCANEADO
POST/api/integrations/v1/services/{slug}/loyalty-cards/{id}/members

Inscribe a un cliente en la tarjeta sin sellar. Requiere el alcance loyalty:write.

  • emailphonenameal menos uno

    datos del cliente

Ver ejemplo
curl -X POST https://fonealo.com/api/integrations/v1/services/taqueria-la-nortena/loyalty-cards/12/members \    -H "Authorization: Bearer TU_ACCESS_TOKEN" \    -d [email protected] \    -d name="Cliente Nuevo"
POST/api/integrations/v1/services/{slug}/loyalty-cards/{id}/members/{memberId}/link

Vincula un miembro existente con su cuenta de Fonealo cuando el cliente muestra su QR personal. Combina duplicados conservando el mayor progreso; desde entonces el cliente ve su tarjeta en su app y su cartera. El memberId viene en las respuestas de scan, members y auto-stamp. Requiere el alcance loyalty:write.

  • coderequerido

    el QR Fonealo del cliente, tal como lo leyó tu escáner (usuario, con o sin @, o fonealo://u/…)

Ver ejemplo
curl -X POST https://fonealo.com/api/integrations/v1/services/taqueria-la-nortena/loyalty-cards/12/members/34/link \    -H "Authorization: Bearer TU_ACCESS_TOKEN" \    -d code=fonealo://u/ana
POST/api/integrations/v1/services/{slug}/loyalty-cards/{id}/auto-stamp

Sella sin QR: tu sistema identifica al cliente por correo o teléfono, por ejemplo al cerrar una orden. Requiere el alcance loyalty:write.

  • emailphoneal menos uno

    identifica al cliente; los teléfonos se comparan por sus últimos 10 dígitos

  • name

    nombre del cliente, para crearlo en su primera visita

  • amount

    monto de la venta, para tus reportes

  • external_reference

    tu id de orden; funciona como clave de idempotencia

Ver ejemplo
curl -X POST https://fonealo.com/api/integrations/v1/services/taqueria-la-nortena/loyalty-cards/12/auto-stamp \    -H "Authorization: Bearer TU_ACCESS_TOKEN" \    -d [email protected] \    -d name="Cliente Frecuente" \    -d amount=189.00 \    -d external_reference=ORDEN-1042

Listo para integrar tu sistema

Crea tu aplicación con tu cuenta de Fonealo: obtienes tu client_id al instante y administras tus redirect_uris cuando quieras.

Crea tu aplicación