Guía para integradores

← Kancha Connect

Qué hay hoy. Cuentas de clientes, llaves, auditoría, WhatsApp (alta del número con link de alta, envío de mensajes y webhooks: sección 6) y módulos listos por API o embebidos, empezando por el lector de órdenes de pago con IA (sección 7). Todavía no factura contra AFIP.

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:

LlaveQuién la tieneQué 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

RutaLlave
GET /v1/mecualquiera
POST /v1/accounts · GET /v1/accountsintegrador
GET /v1/accounts/:idintegrador (su cartera) o cliente (sí mismo)
POST /v1/accounts/:id/keys · POST /v1/keys/:id/revocarintegrador
GET /v1/account · GET /v1/connections · GET /v1/connections/:idcliente

5. Respuestas de error

401 {"error":"llave_invalida"}Falta la llave, está mal escrita, no existe o fue revocada. Siempre la misma respuesta.
403La 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

  1. Vos das de alta a tu cliente (paso 3) y le pedís a Connect un link de alta.
  2. 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).
  3. 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 URLPor qué
HTTPS con certificado válido, puerto 443 u 8443Los mensajes de tus clientes no viajan en claro.
Un dominio que resuelva a una IP públicaConnect no llama a IPs privadas, locales ni internas.
Contestar 2xx en menos de 10 segundosSi 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-Signaturet=<unix>,v1=<hex>: HMAC-SHA256 con tu whsec_… sobre "<t>.<cuerpo crudo>".
Kancha-Event-Id · Kancha-Event-Type · Kancha-TimestampEl 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

tipocuándo
mensaje.recibidoAlguien le escribió al número de tu cliente.
mensaje.estadoUn mensaje que mandaste pasó a enviado, entregado, leido o fallido.
mensaje.ecoTu cliente contestó desde la app del celular (si Meta lo informa).
conexion.activa · conexion.bajaEl WhatsApp de una cuenta quedó conectado / se desconectó.
pingLa 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_conectadoLa cuenta todavía no conectó su WhatsApp.
422 rechazado_por_metaMeta 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_reusadaUsaste la misma clave con otro cuerpo.
502 meta_no_disponibleMeta 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

RutaLlave
GET /v1/whatsappcliente — ¿está conectado?, número, nombre verificado
GET /v1/accounts/:id/whatsappintegrador — lo mismo, para una cuenta suya
POST /v1/accounts/:id/whatsapp/desconectarintegrador — da de baja la conexión; la credencial se destruye
POST /v1/accounts/:id/onboarding-linksintegrador — link de alta
POST · GET /v1/webhooks · POST /v1/webhooks/:id/revocar · /probar · GET /v1/webhooks/:id/entregasintegrador 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 }
}
RespuestaQué significa
403 modulo_no_habilitadoEl módulo no está habilitado para esa cuenta (paso 1).
415 tipo_no_permitidoSólo PDF, JPG, PNG o WEBP, y el contenido tiene que coincidir con el Content-Type.
413 archivo_muy_grandeHasta 10 MB por archivo. Un archivo por llamada.
502 lector_no_disponibleNo 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

RutaLlave
GET /v1/moduloscualquiera
GET /v1/accounts/:id/modulos · POST …/modulos/:modulo/habilitar · …/deshabilitarintegrador
POST /v1/embed/dominios · GET /v1/embed/dominios · POST /v1/embed/dominios/:id/verificar · …/revocarintegrador
POST /v1/modulos/:modulo/:operacion · GET /v1/modulos/usocliente
POST /v1/embed/sesiones · GET /v1/embed/sesiones/:idcliente