API e webhooks: ligue o seu cartão

Começar

A sua chave de API está no painel, em Integrações. Envie-a em cada pedido com o cabeçalho:

Authorization: Bearer fdz_tu_clave

Todos os endereços começam por https://fidelizando.io/api/v1, recebem JSON e respondem JSON com "ok": true ou "ok": false e um "error" em espanhol. Para encontrar um cliente serve o email, o telefono ou o codigo do cartão.

Endereços

GET/yo

Confirma que a chave funciona e devolve o negócio e o tipo de programa. É o que o Zapier usa para testar a ligação.

Resposta

{
  "ok": true,
  "negocio": { "nombre": "Café Martina", "slug": "cafe-martina" },
  "programa": { "tipo": "sellos", "nombre": "Cartão de selos" }
}

POST/clientes

Regista um cliente e cria-lhe o cartão (com a oferta de boas-vindas, se estiver ativa). Se já existia, devolve o cartão dele. consentimiento é obrigatório: confirma que aceitou a sua política de privacidade.

{
  "nombre": "Inês Martins",
  "email": "lucia@ejemplo.com",
  "consentimiento": true,
  "marketing": false
}

Resposta

{
  "ok": true,
  "tarjeta": {
    "codigo": "F5TGSLQRZE",
    "nombre": "Inês Martins",
    "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

Soma ao cartão. Em selos, cantidad selos (1 se não o enviar). Em pontos, os que corresponderem ao importe segundo o seu programa. Respeita os seus limites, como o máximo de selos por dia.

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

Resposta

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

GET/tarjetas?email=lucia@ejemplo.com

Consulta o saldo e o estado de um cartão.

Resposta

{
  "ok": true,
  "tarjeta": {
    "codigo": "F5TGSLQRZE",
    "nombre": "Inês Martins",
    "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

Troca o prémio se houver saldo suficiente. Em pontos, premio é a posição do prémio no seu catálogo (0 o primeiro).

{
  "codigo": "F5TGSLQRZE"
}

Resposta

{
  "ok": true,
  "premio": "Café grátis",
  "tarjeta": { … }
}

Lojas online

O Shopify e o WooCommerce não deixam pôr cabeçalhos, por isso a chave vai no endereço. Cada encomenda paga soma uma vez ao cartão do comprador (pelo email), mesmo que a loja repita o aviso. Os endereços exatos, com a sua chave, estão no seu painel.

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

Webhooks

Indique no seu painel um endereço https:// e enviamos-lhe um POST com JSON sempre que acontecer algo. Se o seu servidor não responder com um código 2xx, tentamos de novo até 5 vezes.

Evento	Quando
`cliente.alta`	Um cliente obtém o cartão (na sua app, no balcão ou pela API).
`tarjeta.suma`	Somam-se selos ou pontos, incluindo ofertas (boas-vindas, aniversário, amigos, raspe e ganhe).
`tarjeta.canje`	Troca-se um prémio.

{
  "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

Receber webhooks: «Webhooks by Zapier → Catch Hook» (no Make, «Custom webhook»). Copie o endereço para o seu painel.
Somar ou registar: «Webhooks by Zapier → POST» para https://fidelizando.io/api/v1/sumar ou /clientes, com o cabeçalho Authorization: Bearer e a sua chave.
Assim liga o Square, o Holded, o Odoo, o Revo, o seu CRM ou uma folha do Google: cada venda soma ao cartão do seu cliente.

Precisa de mais alguma coisa? Escreva-nos para hola@fidelizando.io.