Guía para integradores
1. La URL base y la llave
Todo vive bajo https://connect.kancha.com.ar/v1. Cada pedido lleva la llave en el header, y sólo ahí (nunca en la URL):
Authorization: Bearer kc_int_test_…
Hay dos tipos de llave y dos ambientes, y se ven en el texto:
| Llave | Quién la tiene | Qué puede |
|---|---|---|
kc_int_test_… / kc_int_live_… | El integrador. Se la da Kancha. | Dar de alta sus clientes, listarlos y crearles llaves. |
kc_acc_test_… / kc_acc_live_… | Un cliente del integrador. | Leer su cuenta y sus conexiones, mandar WhatsApp, administrar sus webhooks. |
Una llave de test sólo ve y crea cosas de test. La llave completa se muestra una sola vez, al crearla: Kancha guarda sólo su hash y no la puede recuperar.
2. Probar la llave
curl https://connect.kancha.com.ar/v1/me \ -H "Authorization: Bearer $KANCHA_CONNECT_KEY"
3. Dar de alta un cliente y darle su llave
curl -X POST https://connect.kancha.com.ar/v1/accounts \
-H "Authorization: Bearer $KANCHA_CONNECT_KEY" \
-H "Content-Type: application/json" \
-d '{"nombre":"Ferretería Sur","referenciaExterna":"cli-123","cuit":"30712345678"}'
curl -X POST https://connect.kancha.com.ar/v1/accounts/<id>/keys \
-H "Authorization: Bearer $KANCHA_CONNECT_KEY" \
-H "Content-Type: application/json" -d '{}'
referenciaExterna es el id del cliente en tu sistema: si reintentás el alta con la misma, recibís 409 en vez de un duplicado.
4. Rutas
| Ruta | Llave |
|---|---|
GET /v1/me | cualquiera |
POST /v1/accounts · GET /v1/accounts | integrador |
GET /v1/accounts/:id | integrador (su cartera) o cliente (sí mismo) |
POST /v1/accounts/:id/keys · POST /v1/keys/:id/revocar | integrador |
GET /v1/account · GET /v1/connections · GET /v1/connections/:id | cliente |
5. Respuestas de error
401 {"error":"llave_invalida"} | Falta la llave, está mal escrita, no existe o fue revocada. Siempre la misma respuesta. |
403 | La llave no es del tipo o no tiene el permiso para esa ruta. |
404 {"error":"no_encontrado"} | No existe o no es tuyo: no se distingue a propósito. |
Cada respuesta trae x-request-id. Si algo falla, mandanos ese id: cada pedido queda auditado (sin cuerpos).
6. WhatsApp — cómo funciona
- Vos das de alta a tu cliente (paso 3) y le pedís a Connect un link de alta.
- Tu cliente abre el link: una página de Kancha Connect con tu marca. Acepta los términos y conecta su WhatsApp Business con la ventana oficial de Meta, escaneando un QR con su celular. Sigue usando la app WhatsApp Business en el celular (coexistencia).
- Tu sistema usa la API de Connect con la llave de ese cliente (
kc_acc_…) para enviar mensajes, y recibe en tu URL los webhooks de Connect: mensajes entrantes y estados (enviado, entregado, leído, fallido).
Nunca tocás Meta ni ves un token de Meta. Kancha es el proveedor tecnológico (Tech Provider) de Meta. Las conversaciones que cobra Meta las paga cada negocio a Meta con su propio medio de pago; Kancha no cobra por mensaje.
7. Registrar tu webhook (antes del alta)
Con tu llave de integrador (para todas tus cuentas o una sola, con cuentaId) o con la llave del cliente (sólo esa cuenta):
curl -X POST https://connect.kancha.com.ar/v1/webhooks \
-H "Authorization: Bearer $KANCHA_CONNECT_KEY" \
-H "Content-Type: application/json" \
-d '{"url":"https://tu-servidor.com/webhooks/kancha","cuentaId":"<id>"}'
La respuesta trae secreto (whsec_…) una sola vez: guardalo, con él verificás la firma. Opcional: "eventos":["mensaje.recibido","mensaje.estado"] para recibir sólo esos.
| Requisito de la URL | Por qué |
|---|---|
| HTTPS con certificado válido, puerto 443 u 8443 | Los mensajes de tus clientes no viajan en claro. |
| Un dominio que resuelva a una IP pública | Connect no llama a IPs privadas, locales ni internas. |
| Contestar 2xx en menos de 10 segundos | Si no, se reintenta. Los redirects (3xx) no se siguen: cuentan como fallo. |
Probalo: POST /v1/webhooks/<id>/probar te manda un evento ping, y GET /v1/webhooks/<id>/entregas te muestra qué se entregó, el código que contestó tu servidor y el próximo reintento.
8. Pedir el link de alta
curl -X POST https://connect.kancha.com.ar/v1/accounts/<id>/onboarding-links \
-H "Authorization: Bearer $KANCHA_CONNECT_KEY" \
-H "Content-Type: application/json" \
-d '{"marca":{"nombre":"Tu Empresa","color":"#0f766e"},"returnUrl":"https://tu-sistema.com/listo","venceEnHoras":72}'
Devuelve url: mandásela a tu cliente. Es de un solo uso, vence (72 h por defecto, máximo 7 días) y queda atada a esa cuenta. Pedir otro invalida el anterior. Si la cuenta ya tiene un WhatsApp conectado, devuelve 409 conexion_viva.
Lo que necesita tu cliente: el celular con WhatsApp Business actualizado (el número activo hace 7 días o más), el Facebook de quien administra el negocio y la página abierta en otro dispositivo para escanear el QR. Cuando termina, te llega conexion.activa.
9. Verificar la firma
Cada entrega trae estos headers:
Kancha-Signature | t=<unix>,v1=<hex>: HMAC-SHA256 con tu whsec_… sobre "<t>.<cuerpo crudo>". |
Kancha-Event-Id · Kancha-Event-Type · Kancha-Timestamp | El id del evento (para no procesarlo dos veces), el tipo y la hora. |
Rechazá si la firma no coincide o si t tiene más de 5 minutos. Node.js:
const crypto = require("node:crypto");
// La firma se calcula sobre los BYTES crudos: no parsees el JSON antes de verificar.
function firmaValida(cuerpoCrudo, header, secreto) {
const partes = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")));
const t = Number(partes.t);
if (!t || Math.abs(Date.now() / 1000 - t) > 300) return false; // ventana de 5 min
const esperada = crypto.createHmac("sha256", secreto).update(t + "." + cuerpoCrudo).digest("hex");
const a = Buffer.from(esperada, "hex");
const b = Buffer.from(partes.v1 || "", "hex");
return a.length === b.length && crypto.timingSafeEqual(a, b);
}
// Express
app.post("/webhooks/kancha", express.raw({ type: "application/json" }), (req, res) => {
const crudo = req.body.toString("utf8");
if (!firmaValida(crudo, req.get("Kancha-Signature") || "", process.env.KANCHA_WEBHOOK_SECRET)) {
return res.sendStatus(401);
}
const evento = JSON.parse(crudo);
// Guardá evento.id: si te llega dos veces (reintento), procesalo una sola.
res.sendStatus(200); // contestá rápido (menos de 10 s) y procesá después
});
Python:
import hashlib, hmac, json, os, time
def firma_valida(cuerpo: bytes, header: str, secreto: str) -> bool:
partes = dict(p.strip().split("=", 1) for p in header.split(",") if "=" in p)
try:
t = int(partes.get("t", "0"))
except ValueError:
return False
if abs(time.time() - t) > 300: # ventana de 5 min
return False
esperada = hmac.new(secreto.encode(), f"{t}.".encode() + cuerpo, hashlib.sha256).hexdigest()
return hmac.compare_digest(esperada, partes.get("v1", ""))
# Flask
@app.post("/webhooks/kancha")
def webhook_kancha():
crudo = request.get_data() # bytes, tal cual llegaron
if not firma_valida(crudo, request.headers.get("Kancha-Signature", ""), os.environ["KANCHA_WEBHOOK_SECRET"]):
return "", 401
evento = json.loads(crudo)
# Guardá evento["id"]: si te llega dos veces (reintento), procesalo una sola.
return "", 200
10. Los eventos
| tipo | cuándo |
|---|---|
mensaje.recibido | Alguien le escribió al número de tu cliente. |
mensaje.estado | Un mensaje que mandaste pasó a enviado, entregado, leido o fallido. |
mensaje.eco | Tu cliente contestó desde la app del celular (si Meta lo informa). |
conexion.activa · conexion.baja | El WhatsApp de una cuenta quedó conectado / se desconectó. |
ping | La prueba de /probar. |
{
"id": "evt_3f2b9c0e8a7d4c1b9e6f5a4d3c2b1a09",
"tipo": "mensaje.recibido",
"creadoEn": "2026-09-20T14:03:11.402Z",
"ambiente": "live",
"cuentaId": "b1c2…",
"conexionId": "9e8d…",
"datos": {
"mensajeId": "wamid.HBgNNTQ5MTEy…",
"de": "5491122334455",
"nombre": "Juan",
"fecha": "2026-09-20T14:03:10.000Z",
"tipo": "text",
"texto": "Hola, ¿tienen stock?",
"media": null,
"respondeA": null,
"numeroDelNegocio": "5491155550001",
"crudo": { "…": "el mensaje tal como lo manda Meta" }
}
}
{
"id": "evt_…",
"tipo": "mensaje.estado",
"cuentaId": "b1c2…",
"datos": {
"mensajeId": "wamid.HBgNNTQ5MTEy…",
"estado": "entregado", // enviado | entregado | leido | fallido
"estadoMeta": "delivered",
"para": "5491122334455",
"fecha": "2026-09-20T14:05:00.000Z",
"errores": [] // si fallido: [{ codigo, titulo, detalle }]
}
}
datos.crudo trae el mensaje tal como lo manda Meta, para los tipos que no normalizamos (ubicación, contactos, reacciones…). Para audio, imagen o documento viene datos.media.id (la descarga del archivo por la API todavía no está).
Reintentos si tu servidor no contesta 2xx: a los 10 s, 30 s, 2 min, 10 min, 30 min, 1 h, 3 h y 6 h. Después queda como fallido y lo ves en /entregas.
11. Enviar mensajes (llave del cliente)
Idempotency-Key es obligatorio: un valor único por mensaje (por ejemplo un UUID). Si reintentás con la misma clave y el mismo cuerpo, te devolvemos la misma respuesta y no se manda dos veces; con la misma clave y otro cuerpo, 422.
curl -X POST https://connect.kancha.com.ar/v1/whatsapp/mensajes \
-H "Authorization: Bearer $KANCHA_CLIENTE_KEY" \
-H "Idempotency-Key: 6f1c2a0e-1d8b-4a3e-9d6b-2b1f0c9e8a71" \
-H "Content-Type: application/json" \
-d '{"tipo":"texto","para":"5491122334455","texto":"Hola! Tu pedido ya salió."}'
curl -X POST https://connect.kancha.com.ar/v1/whatsapp/mensajes \
-H "Authorization: Bearer $KANCHA_CLIENTE_KEY" \
-H "Idempotency-Key: 0b7e…" \
-H "Content-Type: application/json" \
-d '{"tipo":"plantilla","para":"5491122334455","plantilla":{"nombre":"pedido_enviado","idioma":"es_AR","componentes":[{"type":"body","parameters":[{"type":"text","text":"#1234"}]}]}}'
Respuesta 201: {"mensajeId":"wamid…","estado":"aceptado"}. "Aceptado" quiere decir que Meta lo tomó; si llegó, te enterás por mensaje.estado.
409 sin_whatsapp_conectado | La cuenta todavía no conectó su WhatsApp. |
422 rechazado_por_meta | Meta no lo aceptó; en meta.codigo va su código. El más común: 131047, pasaron más de 24 h desde el último mensaje de esa persona: sólo se puede escribir con una plantilla aprobada. |
422 idempotency_key_reusada | Usaste la misma clave con otro cuerpo. |
502 meta_no_disponible | Meta no contestó. Si incierto es true, reintentá con la misma clave. |
GET /v1/whatsapp/plantillas lista las plantillas de la cuenta (con su estado de aprobación). Las plantillas se crean y aprueban en el WhatsApp Manager de Meta del cliente.
12. Estado y baja
| Ruta | Llave |
|---|---|
GET /v1/whatsapp | cliente — ¿está conectado?, número, nombre verificado |
GET /v1/accounts/:id/whatsapp | integrador — lo mismo, para una cuenta suya |
POST /v1/accounts/:id/whatsapp/desconectar | integrador — da de baja la conexión; la credencial se destruye |
POST /v1/accounts/:id/onboarding-links | integrador — link de alta |
POST · GET /v1/webhooks · POST /v1/webhooks/:id/revocar · /probar · GET /v1/webhooks/:id/entregas | integrador o cliente |
13. Probarlo sin escribir código
https://connect.kancha.com.ar/probar es un integrador de prueba: pegás tu llave kc_int_test_… y hace, con botones, todo lo de arriba. Con llaves de test ofrece además un receptor de webhooks dentro de Connect, para ver los eventos llegar sin tener un servidor.
7. Módulos listos, por API o embebidos
Si estás haciendo tu propio sistema, podés sumarle módulos nuestros que ya funcionan y resuelven quilombos, sin construirlos vos. Corren en nuestros servidores: vos los llamás por API o embebés su pantalla. No hace falta instalar nada ni usar otro sistema nuestro.
Catálogo: connect.kancha.com.ar/modulos (en JSON: /modulos.json, o GET /v1/modulos con tu llave). Hoy: Lector de órdenes de pago con IA: le pasás una foto o PDF de una orden de pago, transferencia, cheque o retención y te devuelve montos, medios de pago, fecha, pagador y CUIT, las facturas que cancela y un nivel de confianza. Sólo lee: no registra pagos ni comprobantes en ningún lado; eso lo decide tu sistema.
En 3 pasos, por API
1. Habilitá el módulo para tu cliente (llave de integrador). Sus llaves reciben el permiso al instante:
curl -X POST https://connect.kancha.com.ar/v1/accounts/<cuentaId>/modulos/lector-ordenes-pago/habilitar \ -H "Authorization: Bearer $KANCHA_INT_KEY"
2. Desde tu servidor, mandá el archivo crudo con la llave del cliente:
curl -X POST "https://connect.kancha.com.ar/v1/modulos/lector-ordenes-pago/leer?cobraCuit=30709998885" \ -H "Authorization: Bearer $KANCHA_ACC_KEY" \ -H "Content-Type: application/pdf" \ --data-binary @orden-de-pago.pdf
cobraCuit / cobraNombre (opcionales) son los de tu cliente, el que cobra: así el lector nunca lo confunde con el pagador.
3. Usá el JSON:
{
"lecturaId": "…",
"fecha": "2026-09-15", "moneda": "ARS", "total": 1275000,
"pagador": { "nombre": "Distribuidora Ejemplo SA", "cuit": "30712345671", "cuitValido": true },
"pagos": [ { "medio": "Transferencia", "importe": 850000, "referencia": "99887766", "banco": "…", "fecha": "2026-09-15", "pagador": {…} },
{ "medio": "Cheque", "importe": 400000, "numeroCheque": "00012345", "fecha": "2026-10-15", … } ],
"retenciones": [ { "tipo": "IIBB", "importe": 25000, "certificado": "R-0001-000123", … } ],
"comprobantesCancelados": [ { "numero": "FC A 0001-00004567", "importe": 775000 }, … ],
"confianza": { "nivel": "alta", "puntaje": 0.9, "motivos": [] },
"uso": { "unidad": "documento", "cantidad": 1 }
}
| Respuesta | Qué significa |
|---|---|
403 modulo_no_habilitado | El módulo no está habilitado para esa cuenta (paso 1). |
415 tipo_no_permitido | Sólo PDF, JPG, PNG o WEBP, y el contenido tiene que coincidir con el Content-Type. |
413 archivo_muy_grande | Hasta 10 MB por archivo. Un archivo por llamada. |
502 lector_no_disponible | No se pudo leer esta vez. Reintentá; no cuenta como uso. |
confianza.nivel es alta, media, baja o nula (no se encontró ningún pago). No es sólo lo que opina la IA: baja si el CUIT no pasa el dígito verificador, si la fecha no existe o si las facturas no suman lo pagado. Con baja, que lo mire una persona.
En 3 pasos, embebido en tu pantalla
Mostrale a tu usuario nuestra pantalla del módulo, con tu marca, adentro de tu sistema. Tu llave nunca va al navegador.
1. Una sola vez: registrá el dominio desde donde lo vas a embeber y verificalo con un registro TXT en tu DNS (llave de integrador):
curl -X POST https://connect.kancha.com.ar/v1/embed/dominios -H "Authorization: Bearer $KANCHA_INT_KEY" \
-H "Content-Type: application/json" -d '{"origen":"https://app.tuempresa.com"}'
# → te dice qué TXT crear: _kancha-connect.app.tuempresa.com = kancha-connect-verificacion=…
curl -X POST https://connect.kancha.com.ar/v1/embed/dominios/<id>/verificar -H "Authorization: Bearer $KANCHA_INT_KEY"
Con llaves de test podés usar http://localhost:<puerto> sin verificar.
2. Cada vez que vas a mostrar la pantalla, tu backend pide una sesión (llave del cliente). Es de un solo uso y vence en minutos:
curl -X POST https://connect.kancha.com.ar/v1/embed/sesiones -H "Authorization: Bearer $KANCHA_ACC_KEY" \
-H "Content-Type: application/json" \
-d '{"modulo":"lector-ordenes-pago","origen":"https://app.tuempresa.com","referencia":"cobranza-123",
"marca":{"nombre":"Tu Sistema","color":"#7c3aed","logoUrl":"https://app.tuempresa.com/logo.png"}}'
# → { "id": "…", "url": "https://connect.kancha.com.ar/embed/lector-ordenes-pago?s=kes_…", "venceEn": "…" }
3. Tu página muestra la url en un iframe y escucha el resultado:
<iframe src="URL_DE_LA_SESION" style="width:100%;min-height:480px;border:0"></iframe>
<script>
window.addEventListener("message", (ev) => {
if (ev.origin !== "https://connect.kancha.com.ar") return; // sólo mensajes nuestros
if (ev.data.tipo === "kancha-connect:resultado") {
// ev.data.sesionId, ev.data.referencia, ev.data.resultado (el mismo JSON de la API)
// Para guardarlo, pedíselo a tu backend: GET /v1/embed/sesiones/:id con la llave.
}
if (ev.data.tipo === "kancha-connect:alto") { /* ajustá el alto del iframe */ }
});
</script>
El navegador sólo dibuja la pantalla dentro del origen que pediste (Content-Security-Policy: frame-ancestors): desde cualquier otro dominio queda en blanco. Lo que llega por postMessage sirve para la pantalla; la fuente de verdad es tu backend: GET /v1/embed/sesiones/:id con la llave del cliente (el resultado se guarda 7 días). Si registraste un webhook (sección 6), también te llega el evento modulo.resultado con los ids.
Probalo ahora con tus llaves de prueba →
Rutas de los módulos
| Ruta | Llave |
|---|---|
GET /v1/modulos | cualquiera |
GET /v1/accounts/:id/modulos · POST …/modulos/:modulo/habilitar · …/deshabilitar | integrador |
POST /v1/embed/dominios · GET /v1/embed/dominios · POST /v1/embed/dominios/:id/verificar · …/revocar | integrador |
POST /v1/modulos/:modulo/:operacion · GET /v1/modulos/uso | cliente |
POST /v1/embed/sesiones · GET /v1/embed/sesiones/:id | cliente |