API y webhooks (para desarrolladores)

Autenticación

Crea una llave en Panel → Integraciones y mándala en cada solicitud: Authorization: Bearer kliq_xxxxxx_… Las llaves de sólo lectura no pueden crear. Límite: 600 solicitudes por minuto por llave.

Clientes

GET /api/v1/contacts?limit=50&after=<id>&updated_since=<ISO>&phone=<10 dígitos> — lista paginada (usa next_cursor como after).

GET /api/v1/contacts/{id} — cliente con sus tarjetas, saldos y segmento.

POST /api/v1/contacts — {"first_name", "phone" o "email", "last_name"?, "birthday"?, "consent_whatsapp"?, "consent_email"?}. Si el teléfono ya existe regresa el cliente existente (created: false) sin modificarlo. Sólo marca permisos de promoción si el cliente los dio en tu sistema: quedan registrados con origen "api".

Ventas de tu caja o tienda en línea

POST /api/v1/purchases — {"external_id", "amount", "phone" o "email" o "contact_id", "first_name"?, "program_id"?, "location_id"?}. Registra una venta hecha en otro sistema (Clip, Shopify, Tiendanube, tu punto de venta) y suma en todos tus programas activos: un sello en los de sellos y el monto en los de puntos, cashback o descuento.

external_id es el folio de la venta en tu sistema: si la misma venta llega dos veces sólo cuenta una. Si el cliente no existe y mandas first_name, se da de alta. Respeta el máximo de sellos por día. La API nunca canjea premios ni gasta saldo: eso sólo pasa en el mostrador.

Responde {contact_id, contact_created, results: [{program, type, stamps, points, cashback_balance, rewards_available, reward_completed, duplicate}]}.

Citas y eventos

GET /api/v1/appointments?from=<ISO>&to=<ISO> — citas en un rango de hasta 62 días.

GET /api/v1/events?after=<id>&type=card.purchase — todo lo que pasa en el negocio, en orden (alternativa a los webhooks).

Webhooks

Kliq envía un POST JSON a tu URL con cada evento: {id, type, occurred_at, business_id, contact_id, data}. No incluye datos personales; consúltalos con la API.

Verifica el encabezado X-Kliq-Signature: es sha256= más el HMAC-SHA256 del cuerpo exacto recibido, con el secreto del webhook. En Node: crypto.createHmac('sha256', secreto).update(cuerpoCrudo).digest('hex').

Tipos: contact.created, card.issued, card.stamp_added, card.purchase, card.reward_redeemed, appointment.booked, appointment.deposit_paid, feedback.received, feedback.low, referral.rewarded, coupon.redeemed, prepaid.sold, queue.joined, order.placed, quote.sent, quote.accepted, order.delivered, order.paid y más.

Errores

Las respuestas de error traen {error: {code, message}}: 401 llave inválida, 402 suscripción inactiva o límite del plan, 403 llave de sólo lectura, 404 cliente o programa inexistente, 409 venta que no se pudo aplicar (por ejemplo, ya se sumó el máximo de sellos de hoy), 422 datos inválidos, 429 demasiadas solicitudes.