API y avisos a tus sistemas

Con la API tu sistema (un ERP, una planilla automática, Power BI) lee la cartera de tu empresa en Cobrú y crea clientes y documentos sin subir archivos. Con los avisos, Cobrú le cuenta a tu sistema lo que pasa: un abono que entró, un pago aplicado, una factura pagada.

Está disponible en el plan Enterprise.

Crear una clave

1. Entra a Configuración → API y avisos (solo un Admin).
2. En Crear una clave, ponle un nombre que la identifique, por ejemplo «ERP».
3. Marca También puede crear clientes y documentos solo si tu sistema necesita escribir. Sin marcar, la clave solo lee.
4. Copia la clave en ese momento: no se vuelve a mostrar. Si la pierdes, revócala y crea otra.

Cada clave ve solo los datos de tu empresa. Si administras varias empresas, crea una clave en cada una.

Cómo se usa

Envía la clave en cada pedido, en el encabezado Authorization:

curl https://cobru-production.up.railway.app/api/v1/clientes \
  -H "Authorization: Bearer cobru_xxxxxxxx_…"

Las respuestas son JSON. Las listas traen datos y siguiente: si siguiente no es nulo, pídelo con ?cursor=<siguiente> para la página que sigue. Cada página trae hasta 50 filas (?limite= hasta 200).

Qué se puede leer

Qué se puede crear

Solo con una clave de lectura y escritura.

Un cliente (POST /api/v1/clientes). Si el RUT ya existe en tu empresa, devuelve el existente y no crea otro:

{ "rut": "76.123.456-0", "razonSocial": "Cliente SpA", "contacto": { "nombre": "Ana", "correo": "pagos@cliente.cl" } }

Documentos (POST /api/v1/documentos), hasta 500 por pedido. Un documento con el mismo tipo y folio no se duplica, así que puedes reenviar el lote sin miedo. Los clientes que no existan se crean con el RUT y la razón social del documento. Si no indicas vencimiento, se estima a 30 días:

{ "documentos": [ { "tipo": "33", "folio": "1234", "emision": "2026-10-01", "vencimiento": "2026-10-31", "monto": 1190000, "rutCliente": "76.123.456-0", "razonSocialCliente": "Cliente SpA" } ] }

Los documentos nuevos entran a la cobranza igual que los del SII y pueden calzar con abonos que estaban esperando.

Decidir una factura recibida (POST /api/v1/compras/{id}/decision, clave con escritura). Cobrú registra la decisión y, si la empresa tiene la clave del SII guardada, la envía al SII en la próxima vuelta: aceptar el contenido, reclamar (con motivo obligatorio) o dar acuse de recibo. sin_accion deja pasar el plazo (aceptación tácita). Las mismas reglas que en Compras → Revisión: dentro del plazo de 8 días y sin un evento previo en el SII.

{ "decision": "reclamar", "motivo": "No corresponde a una compra nuestra" }

Órdenes de compra (POST /api/v1/ordenes-compra, hasta 500 por pedido). Se crean o actualizan por numero; estado puede ser abierta (por defecto), cerrada o anulada, y requiereHes marca las de servicios, que necesitan una HES para calzar. Al entrar, Cobrú recalcula el calce de las facturas recibidas pendientes:

{ "ordenes": [ { "numero": "4512", "rutProveedor": "76.117.929-2", "razonSocialProveedor": "Proveedor SpA", "monto": 1190000, "fecha": "2026-10-01", "requiereHes": false, "descripcion": "Licencias" } ] }

HES (POST /api/v1/hes, hasta 500 por pedido), cada una contra su OC por número:

{ "hes": [ { "numero": "HES-88", "numeroOc": "4512", "monto": 1190000, "fecha": "2026-10-20" } ] }

Con qué OC va una factura (POST /api/v1/compras/{id}/orden-compra): { "numeroOc": "4512" } la vincula y recalcula su calce; { "numeroOc": null } la deja sin OC. Si la empresa activó las reglas por OC (Compras → Revisión), lo que calza se acepta solo y lo que no corresponde a una OC vigente, o se pasa del monto, se reclama solo con motivo; varias OC posibles o falta de HES quedan a una persona.

Límites y errores

• Hasta 1.000 pedidos por hora por empresa, sumando todas sus claves. Si te pasas, la respuesta es 429 con Retry-After.
• Los errores traen { "error": { "codigo": "…", "mensaje": "…" } }: sin_clave o clave_invalida (401), solo_lectura o plan_sin_api (403), no_encontrado (404), datos_invalidos (422).
• Lo que crea la API queda en el Registro de actividad con el nombre de la clave.

Avisos a tus sistemas

En Configuración → API y avisos → Agregar una dirección, escribe una dirección https:// de tu sistema y elige qué avisos quieres:

Cobrú envía un POST con un JSON como este:

{ "id": "…", "evento": "pago.aplicado", "creadoEn": "2026-10-18T14:03:00Z", "empresaId": "…", "datos": { "pagoId": "…", "monto": 1190000, "asignaciones": [ … ] } }

Tu sistema debe responder con un código 2xx en menos de 10 segundos. Si no responde, reintentamos a 1 minuto, 5 minutos, 30 minutos, 2 horas y 12 horas; después el aviso queda como fallido y lo puedes reintentar desde la pantalla. Usa el id para no procesar dos veces el mismo aviso.

Por seguridad no enviamos avisos a direcciones de redes privadas y no seguimos redirecciones.

Verificar que el aviso es de Cobrú

Al agregar la dirección te mostramos un secreto (whsec_…), una sola vez. Cada aviso trae el encabezado Cobru-Firma: t=<segundos>,v1=<firma>, donde la firma es HMAC-SHA256 del texto <t>.<cuerpo> con ese secreto. Verifícala así (Node.js):

const [t, v1] = firma.split(",").map((p) => p.split("=")[1]);
const esperado = crypto.createHmac("sha256", secreto).update(`${t}.${cuerpoCrudo}`).digest("hex");
const valido = crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(v1)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;

Usa el cuerpo tal como llegó, antes de convertirlo a JSON. Con Enviar prueba puedes comprobar que tu sistema recibe y verifica bien.