Ir al contenido
Krealo Wallet
es

API de Krealo Wallet

Crea tarjetas, emítelas a tus clientes y mueve sellos, puntos y saldos desde tu caja, tu web o tus automatizaciones. Todas las respuestas son JSON; los importes van en céntimos y las fechas en ISO 8601.

https://krealowallet.com/api/v1

Autenticación

Crea una clave en el panel (API y webhooks). Cada clave da acceso a una sola empresa. Mándala en la cabecera Authorization.

Authorization: Bearer kw_live_…

Errores y límites

Un error responde { "error": { "code", "message" } } con su código HTTP (400, 401, 402 suscripción inactiva, 403 plan sin API, 404, 429). Límites: 300 peticiones por minuto y clave, y una cuota diaria según el plan (prueba 500, Pro 10 000, Empresa 100 000). Cada respuesta lleva X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; un 429 añade Retry-After (segundos).

Idempotencia

Las operaciones que emiten o mueven saldo aceptan la cabecera Idempotency-Key: la misma clave durante 24 h devuelve la misma respuesta sin repetir la operación (cabecera Idempotent-Replayed: true).

Rutas

Todas las rutas, generadas desde nuestro contrato OpenAPI 3.1. Abre una ruta para ver un ejemplo con curl.

https://krealowallet.com/api/v1/openapi.json

Postman → Import → pega la URL del contrato OpenAPI. Insomnia, Bruno y los generadores de SDK también la aceptan.

Importar en Postman

Plantillas

Company

Clientes

Pases

Movimientos

Avisos

Webhooks

Ejemplo: emitir una tarjeta y sumar un sello

curl -X POST https://krealowallet.com/api/v1/passes \
  -H "Authorization: Bearer kw_live_…" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"templateId":"TEMPLATE_ID","customer":{"name":"Demo Customer","email":"demo@example.com"}}'

curl -X POST https://krealowallet.com/api/v1/passes/PASS_ID/stamps \
  -H "Authorization: Bearer kw_live_…" \
  -H "Content-Type: application/json" -d '{"count":1}'

Webhooks

Mandamos un POST JSON a tu URL HTTPS en cada evento. Responde 2xx en menos de 10 s; si no, reintentamos a 1 min, 5 min, 30 min, 2 h y 12 h. Verifica la firma con el secreto que recibiste al crearlo.

customer.created (cliente creado, venga de donde venga), pass.voided (tarjeta anulada), pass.expired (tarjeta que llega a su fecha, una vez), reward.ready (el cliente llega a un premio, una vez por umbral). En el panel, «Enviar un evento de prueba» manda un evento ping firmado; una entrega fallida se puede reenviar. Tras 3 eventos seguidos sin entregar, el webhook se desactiva y los administradores reciben un correo.

pass.issuedpass.installedpass.removedpoints.changedreward.redeemedbalance.changedcustomer.createdpass.voidedpass.expiredreward.ready
POST https://your-server.example/hook
Krealo-Event: points.changed
Krealo-Signature: t=1760300000,v1=5f2b…

{ "id": "evt_…", "type": "points.changed", "created": "2026-10-12T20:00:00.000Z",
  "data": { "pass": { "id": "…", "stamps": 4, … }, "movement": { "operation": "sumar", "before": 3, "after": 4 } } }

Verificar la firma (Node.js)

import crypto from 'node:crypto';

// header = req.headers['krealo-signature'], body = el cuerpo CRUDO (texto, antes de JSON.parse)
export function verify(header, body, secret) {
  if (typeof header !== 'string') return false;
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !/^[0-9a-f]{64}$/.test(parts.v1 ?? '')) return false;
  if (Math.abs(Date.now() / 1000 - t) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${body}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(parts.v1, 'hex'), Buffer.from(expected, 'hex'));
}

Shopify

Instala la app Krealo Wallet en tu tienda y vincúlala con tu empresa desde el panel (Integraciones → Shopify). Cada pedido pagado suma sellos o puntos en la tarjeta elegida, y cada cliente nuevo recibe la tarjeta de bienvenida; su enlace de instalación queda en el metacampo del cliente krealo_wallet.install_url. Incluido en todos los planes.

Sin esperar a la app: la guía de Shopify Flow

Shopify Flow → Krealo Wallet (sin app)

Cada pedido pagado suma un sello, puntos o reembolso en la tarjeta del cliente, y crea la tarjeta si aún no la tiene. Hace falta el plan Pro o Empresa de Krealo Wallet y una tienda Shopify Grow, Advanced o Plus (la acción «Send HTTP request» de Flow no está en Basic). Son unos 10 minutos.

  1. En Krealo Wallet, abre Integraciones → API y claves y crea una clave. Cópiala en el momento (empieza por kw_live_ y solo se muestra una vez).
  2. En Krealo Wallet, abre Tarjetas y luego la tarjeta de fidelidad que quieras usar (debe estar publicada). Su identificador es el final de la dirección del navegador, después de /plantillas/: cópialo.
  3. En Shopify, instala la app gratuita Shopify Flow desde la Shopify App Store, ábrela y crea un flujo de trabajo.
  4. Elige el disparador «Order paid».
  5. Añade la acción «Send HTTP request». HTTP method: POST. URL: https://krealowallet.com/api/v1/purchases
  6. Headers: añade Key «Authorization» con Value «Bearer», un espacio y tu clave; y Key «Content-Type» con Value «application/json». Consejo: guarda la clave con «Add secret» para que nunca se vea en claro.
  7. Body: pega el texto de abajo y cambia TEMPLATE_ID por el identificador del paso 2. Shopify rellena los {{…}} en cada pedido: no los cambies.
  8. Para las respuestas 4XX elige «Fail»; para 5XX/429 deja «Retry». Nada cuenta doble: el mismo pedido enviado dos veces se suma una sola vez.
  9. Activa el flujo (Turn on workflow).

Body para pegar:

{
  "template_id": "TEMPLATE_ID",
  "email": "{{order.email}}",
  "phone": "{{order.phone}}",
  "name": "{{order.customer.displayName}}",
  "amount": "{{order.totalPriceSet.shopMoney.amount}}",
  "order_id": "{{order.id}}",
  "source": "shopify-flow"
}

Probar: haz un pedido de prueba con tu propio correo y captura el pago. En Shopify Flow, el historial de ejecuciones muestra la respuesta (200 = todo bien). En Krealo Wallet, abre Clientes: el cliente aparece con su tarjeta y el movimiento en su historial. En el primer pedido, la respuesta trae install_links: el enlace para añadir la tarjeta a Apple Wallet o Google Wallet.

Cuando se crea una tarjeta por POST /purchases (Shopify Flow), el cliente la recibe por correo si tiene dirección. Con Twilio conectado, la recibe también por SMS si tiene teléfono: un mensaje corto, en su idioma (FR, EN, ES), con el nombre de tu empresa y el enlace de instalación (acortado con Krealo QR si está conectado). Los clientes que responden STOP ya no reciben SMS. Tarjeta enviada por correo y por SMS (Twilio)

Problemas frecuentes

  • 401: falta la clave o está mal copiada. Revisa «Bearer» + espacio + la clave completa, o crea otra.
  • 403: tu plan de Krealo Wallet no incluye la API. Pasa al plan Pro o Empresa.
  • 400 «email or phone is required»: el pedido no tiene ni correo ni teléfono (venta sin cliente). No se suma nada; es lo esperado.
  • 400 en template_id o 404: el identificador de la tarjeta está mal copiado, o no es una tarjeta de fidelidad (sellos, puntos o reembolso).

Tarjeta enviada por correo y por SMS (Twilio)

Cuando se crea una tarjeta por POST /purchases (Shopify Flow), el cliente la recibe por correo si tiene dirección. Con Twilio conectado, la recibe también por SMS si tiene teléfono: un mensaje corto, en su idioma (FR, EN, ES), con el nombre de tu empresa y el enlace de instalación (acortado con Krealo QR si está conectado). Los clientes que responden STOP ya no reciben SMS.

  1. En Krealo Wallet, abre Integraciones → Twilio (SMS) (plan Pro o Empresa).
  2. Pega el Account SID y el Auth Token de tu consola de Twilio (Account Info), o una clave de API (SK… + secreto).
  3. Remitente: tu número de Twilio (+15145550000) o un Messaging Service SID (MG…). Pulsa Conectar Twilio: las credenciales se comprueban con Twilio y se guardan cifradas.
  4. Envía un SMS de prueba a tu número. La tarjeta dice Conectada.

En la API: send_email y send_sms (sí por defecto en /purchases cuando se crea la tarjeta); en POST /passes y la herramienta MCP issue_pass, enviarCorreo y send_sms son opcionales. La respuesta trae email_sent y sms_sent {sent, error}. Sin Twilio, sms_sent.error es twilio_not_configured y el correo sale como siempre.

Servidor MCP (Claude y otros agentes)

Gestiona tus tarjetas desde Claude: añade un conector personalizado con la URL de abajo. Entras con tu cuenta (OAuth) y eliges la empresa; un agente que no haga OAuth puede usar una clave de API.

https://krealowallet.com/mcp

Zapier

Conecta Krealo Wallet con más de 7 000 aplicaciones sin escribir código. Disparadores: pase emitido, premio canjeado, cliente creado. Acciones: crear un cliente, emitir un pase (con su enlace de instalación), sumar sellos.

  1. La app de Zapier es por invitación de momento: abre el enlace de abajo (o pídeselo a Krealo) y acepta la invitación.
  2. En Zapier, crea un Zap y busca «Krealo Wallet».
  3. Al conectar, pega una clave de API (ver Autenticación); la conexión toma el nombre de tu empresa.
Aceptar la invitación de Zapier

Botón «Añadir a mi Wallet»

Añade a tu web un botón que abre el alta de tu tarjeta de fidelidad o de tu cupón. El código de cada tarjeta está en el panel (Enlace y QR de alta): pégalo donde quieras el botón.

<script src="https://krealowallet.com/embed.js" data-carte="/u/ORG_ID/CARD_ID" data-lang="es" async></script>

data-carte acepta la ruta /u/… o la URL completa del alta. Sin data-lang, el botón toma el idioma de la página (fr, en o es). Funciona con una CSP estricta: basta con añadir https://krealowallet.com a script-src.