API und Webhooks: Kundenkarte anbinden

Erste Schritte

Ihren API-Schlüssel finden Sie im Dashboard unter Integrationen. Senden Sie ihn bei jeder Anfrage im Header:

Authorization: Bearer fdz_tu_clave

Alle Endpunkte beginnen mit https://fidelizando.io/api/v1, nehmen JSON an und antworten mit JSON mit "ok": true oder "ok": false und einem "error" auf Spanisch. Um einen Kunden zu finden, können Sie seine email, seine telefono oder den codigo seiner Karte nutzen.

Endpunkte

GET/yo

Prüft, ob der Schlüssel funktioniert, und liefert Geschäft und Programmart. Zapier nutzt diesen Endpunkt zum Testen der Verbindung.

Antwort

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

POST/clientes

Meldet einen Kunden an und erstellt seine Karte (mit Willkommensgeschenk, falls aktiviert). Gibt es ihn schon, kommt seine Karte zurück. consentimiento ist Pflicht: Es bestätigt, dass der Kunde Ihre Datenschutzerklärung akzeptiert hat.

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

Antwort

{
  "ok": true,
  "tarjeta": {
    "codigo": "F5TGSLQRZE",
    "nombre": "Lena Martin",
    "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

Schreibt der Karte gut. Bei Stempeln cantidad Stempel (1, wenn Sie nichts senden). Bei Punkten so viele, wie dem importe laut Ihrem Programm entsprechen. Ihre Limits gelten, etwa die maximalen Stempel pro Tag.

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

Antwort

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

GET/tarjetas?email=lucia@ejemplo.com

Fragt Guthaben und Status einer Karte ab.

Antwort

{
  "ok": true,
  "tarjeta": {
    "codigo": "F5TGSLQRZE",
    "nombre": "Lena Martin",
    "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

Löst die Prämie ein, wenn das Guthaben reicht. Bei Punkten ist premio die Position der Prämie in Ihrem Katalog (0 ist die erste).

{
  "codigo": "F5TGSLQRZE"
}

Antwort

{
  "ok": true,
  "premio": "Gratis-Kaffee",
  "tarjeta": { … }
}

Onlineshops

Shopify und WooCommerce erlauben keine eigenen Header, daher steht der Schlüssel in der Adresse. Jede bezahlte Bestellung wird der Karte des Käufers (über seine E-Mail) einmal gutgeschrieben, auch wenn der Shop die Meldung wiederholt. Die genauen Adressen mit Ihrem Schlüssel finden Sie im Dashboard.

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

Webhooks

Hinterlegen Sie in Ihrem Dashboard eine https://-Adresse und wir senden Ihnen bei jedem Ereignis einen POST mit JSON. Antwortet Ihr Server nicht mit einem 2xx-Code, versuchen wir es bis zu 5 Mal erneut.

Ereignis	Wann
`cliente.alta`	Ein Kunde holt sich die Karte (in Ihrer App, an der Theke oder über die API).
`tarjeta.suma`	Stempel oder Punkte werden gutgeschrieben, auch Geschenke (Willkommen, Geburtstag, Freunde, Rubbeln und gewinnen).
`tarjeta.canje`	Eine Prämie wird eingelöst.

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

Zapier, Make und n8n

Webhooks empfangen: „Webhooks by Zapier → Catch Hook“ (in Make „Custom webhook“). Kopieren Sie die Adresse in Ihr Dashboard.
Gutschreiben oder anmelden: „Webhooks by Zapier → POST“ an https://fidelizando.io/api/v1/sumar oder /clientes, mit dem Header Authorization: Bearer und Ihrem Schlüssel.
So verbinden Sie Square, Holded, Odoo, Revo, Ihr CRM oder eine Google-Tabelle: Jeder Verkauf wird der Karte Ihres Kunden gutgeschrieben.

Brauchen Sie noch etwas? Schreiben Sie uns an hola@fidelizando.io.