API e webhook: collega la tua carta fedeltà

Per iniziare

La tua chiave API è nel pannello, in Integrazioni. Inviala in ogni richiesta con l’intestazione:

Authorization: Bearer fdz_tu_clave

Tutti gli indirizzi iniziano con https://fidelizando.io/api/v1, ricevono JSON e rispondono in JSON con "ok": true o "ok": false e un "error" in spagnolo. Per trovare un cliente puoi usare la sua email, il suo telefono o il codigo della sua carta.

Indirizzi

GET/yo

Verifica che la chiave funzioni e ti restituisce l’attività e il tipo di programma. È quello che usa Zapier per testare la connessione.

Risposta

{
  "ok": true,
  "negocio": { "nombre": "Café Martina", "slug": "cafe-martina" },
  "programa": { "tipo": "sellos", "nombre": "Carta timbri" }
}

POST/clientes

Iscrive un cliente e gli crea la carta (con il regalo di benvenuto, se attivo). Se esisteva già, restituisce la sua carta. consentimiento è obbligatorio: conferma che ha accettato la tua informativa sulla privacy.

{
  "nombre": "Giulia Martini",
  "email": "lucia@ejemplo.com",
  "consentimiento": true,
  "marketing": false
}

Risposta

{
  "ok": true,
  "tarjeta": {
    "codigo": "F5TGSLQRZE",
    "nombre": "Giulia Martini",
    "email": "lucia@ejemplo.com",
    "programa": "sellos",
    "saldo": 6,
    "estado": "Te faltan 3 para: café gratis",
    "visitas": 6,
    "app": "https://fidelizando.io/c/cafe-martina"
  }
}

POST/sumar

Accredita sulla carta. Per i timbri, cantidad timbri (1 se non lo invii). Per i punti, quelli che corrispondono all’importe secondo il tuo programma. Rispetta i tuoi limiti, come il massimo di timbri al giorno.

{
  "email": "lucia@ejemplo.com",
  "importe": 12.50,
  "concepto": "Ticket 1043"
}

Risposta

{
  "ok": true,
  "sumado": 1,
  "premio_listo": false,
  "tarjeta": { … }
}

GET/tarjetas?email=lucia@ejemplo.com

Consulta saldo e stato di una carta.

Risposta

{
  "ok": true,
  "tarjeta": {
    "codigo": "F5TGSLQRZE",
    "nombre": "Giulia Martini",
    "email": "lucia@ejemplo.com",
    "programa": "sellos",
    "saldo": 6,
    "estado": "Te faltan 3 para: café gratis",
    "visitas": 6,
    "app": "https://fidelizando.io/c/cafe-martina"
  }
}

POST/canjear

Riscatta il premio se il saldo è sufficiente. Per i punti, premio è la posizione del premio nel tuo catalogo (0 il primo).

{
  "codigo": "F5TGSLQRZE"
}

Risposta

{
  "ok": true,
  "premio": "Caffè gratis",
  "tarjeta": { … }
}

E-commerce

Shopify e WooCommerce non permettono intestazioni personalizzate, quindi la chiave va nell’indirizzo. Ogni ordine pagato accredita una sola volta la carta dell’acquirente (tramite la sua email), anche se il negozio ripete la notifica. Gli indirizzi esatti, con la tua chiave, sono nel tuo pannello.

https://fidelizando.io/api/v1/tiendas/shopify?clave=fdz_tu_clave
https://fidelizando.io/api/v1/tiendas/woocommerce?clave=fdz_tu_clave

Webhook

Inserisci nel pannello un indirizzo https:// e ti invieremo un POST in JSON ogni volta che succede qualcosa. Se il tuo server non risponde con un codice 2xx, riproviamo fino a 5 volte.

Evento	Quando
`cliente.alta`	Un cliente prende la carta (nella tua app, al bancone o tramite API).
`tarjeta.suma`	Si accreditano timbri o punti, compresi i regali (benvenuto, compleanno, amici, gratta e vinci).
`tarjeta.canje`	Si riscatta un premio.

{
  "evento": "tarjeta.suma",
  "fecha": "2026-10-23T12:36:08+02:00",
  "codigo": "F5TGSLQRZE",
  "tipo": "suma",
  "cantidad": 1,
  "saldo": 7,
  "concepto": "Ticket 1043"
}

Zapier, Make e n8n

Ricevere i webhook: «Webhooks by Zapier → Catch Hook» (in Make, «Custom webhook»). Copia il suo indirizzo nel tuo pannello.
Accreditare o iscrivere: «Webhooks by Zapier → POST» a https://fidelizando.io/api/v1/sumar o /clientes, con l’intestazione Authorization: Bearer e la tua chiave.
Così colleghi Square, Holded, Odoo, Revo, il tuo CRM o un foglio Google: ogni vendita si accredita sulla carta del tuo cliente.

Ti serve altro? Scrivici a hola@fidelizando.io.