API y webhooks

Dónde encontrarlo

Si en tu despacho los documentos nacen en otro sitio que no es DocuTract, ese sistema puede hablar directamente con nosotros. Abre el menú con tu dirección en la esquina superior derecha y elige Integraciones: ahí se emite el token con el que tu sistema nos llama y ahí añades la dirección a la que le avisamos de los documentos terminados.

La pantalla empieza con las conexiones listas para CRM (Integraciones con CRM); los tokens y webhooks que se describen aquí están debajo, en la sección API y webhooks.

El token

Pulsa Crear un token, ponle un nombre que reconozcas más adelante (para saber qué sistema lo usa) y marca lo que puede hacer: leer plantillas, crear documentos, trabajar con expedientes.

El token en sí se muestra una sola vez, justo después de crearlo: solo guardamos un hash, así que mostrarlo una segunda vez es algo que ni siquiera nosotros podemos hacer. Cópialo directamente en los ajustes de tu sistema.

La lista muestra los primeros caracteres de cada token, lo que puede hacer y cuándo se usó por última vez. Revocar desactiva un token de inmediato; su registro se conserva, de modo que se ve que existió y cuándo dejó de funcionar.

Qué puede hacer la API

Tu sistema puede:

• abrir un expediente y subir escaneos a él;
• crear un documento a partir de una plantilla con los valores ya rellenados;
• preguntar en qué fase está un documento;
• obtener todos los valores junto con el escaneo del que se leyó cada uno;
• obtener un enlace de corta duración al archivo terminado.

La descripción completa de cada dirección y campo se genera a partir del propio código y se publica abiertamente: la descripción de la API.

Webhooks

En lugar de preguntarnos si un documento está listo, danos una dirección y te escribiremos. Añádela en Webhooks y marca los eventos: documento listo, documento fallido, expediente listo, discrepancia encontrada, un cliente ha enviado un archivo.

Cada solicitud va firmada con la cabecera X-DocuTract-Signature, y el secreto que verifica la firma se muestra una sola vez, como el token. Tu sistema tiene que comprobar la firma y responder con un código 2xx. Si responde otra cosa, o no responde, lo volvemos a intentar: al cabo de un minuto, de cinco, de media hora, de dos horas y de diez, y después paramos.

Cuando algo no ha llegado

El botón Entregas muestra el registro: qué evento enviamos, cuándo, cuántas veces, qué código de respuesta volvió y el principio del cuerpo de la respuesta. Esa es la respuesta a «nuestro sistema no ha recibido nada»: consta por escrito que respondió 500 cuatro veces a las 14:12.

Enviar prueba envía ahora mismo un ping a la dirección, sin esperar a un evento real, para que el receptor pueda configurarse antes de que pase trabajo real por él. Reintentar, junto a una entrega fallida, hace un intento más de inmediato.

Zapier, Make y n8n

Las plataformas no-code (servicios donde una integración se monta sin programar) se suscriben solas a nuestros eventos mediante la parte de REST hooks de la API, así que nadie tiene que copiar sus direcciones en DocuTract. Da a la plataforma un token con los permisos webhooks:read y webhooks:write, además de los que necesiten sus acciones (por ejemplo, templates:read y documents:write).

• POST /api/v1/hooks con {"event": "document.ready", "target_url": "https://…"} suscribe una dirección a un evento. La respuesta incluye el id de la suscripción y, una sola vez, su secret de firma.
• GET /api/v1/hooks lista las suscripciones creadas así; DELETE /api/v1/hooks/{id} elimina una.
• GET /api/v1/hooks/events lista los eventos: document.ready, document.failed, case.ready, finding.raised, intake.uploaded.
• GET /api/v1/hooks/samples/{event} devuelve un ejemplo del contenido, que la plataforma muestra en su «disparador de prueba» antes de que ocurra ningún evento real.

Una suscripción es una dirección de webhook normal: se firma, se reintenta y se registra igual, y se ve en la lista de Webhooks. Deja de funcionar cuando el token que la creó se revoca o caduca, o cuando la plataforma responde a una entrega con 410 Gone.

Así es document.ready:

{
  "document_id": "00000000-0000-4000-8000-000000000001",
  "reference": "DOC-26-0001",
  "template_id": "00000000-0000-4000-8000-000000000002",
  "template_version": 1,
  "event": "document.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

y así case.ready:

{
  "case_id": "00000000-0000-4000-8000-000000000003",
  "title": "Sample case",
  "documents": [
    { "id": "00000000-0000-4000-8000-000000000001", "reference": "DOC-26-0001" }
  ],
  "event": "case.ready",
  "occurred_at": "2026-01-15T10:30:00+00:00"
}

Los campos de una plantilla

GET /api/v1/templates/{id}/fields (permiso templates:read) lista lo que necesita una plantilla: la key de cada campo (la que usan los values de POST /api/v1/documents), su label, de dónde se rellena y fillable, que es false para un campo que DocuTract rellena por sí mismo, como una fecha. Un formulario en Zapier o Make se construye con esta lista, así que siempre coincide con la plantilla tal como está ahora.

Búsquedas

Algunas llamadas existen para que un sistema, o una plataforma no-code, encuentre lo que necesita sin adivinar:

• GET /api/v1/me (sin permiso) devuelve el espacio de trabajo al que pertenece el token, su plan y el nombre y los permisos del propio token. Es la forma más sencilla de comprobar que un token funciona.
• GET /api/v1/documents (permiso documents:read) lista los documentos, los más recientes primero. Acótala con reference (la referencia DOC-… exacta), status o template_id; limit admite hasta 100, 25 por defecto.
• GET /api/v1/cases (permiso cases:read) lista los expedientes más recientes, si quieres solo los de un status, con el mismo limit. Cada expediente incluye ahora también su created_at.
• GET /api/v1/case-types (permiso cases:read) lista los tipos de expediente con los que se puede abrir un expediente.
• GET /api/v1/templates?name=… deja solo las plantillas cuyo nombre contiene el texto, sin distinguir mayúsculas.

No hay paginación a propósito: estas listas sirven para encontrar lo más reciente, no para exportar todo un espacio de trabajo.

Qué plan

La API y los webhooks forman parte del plan Team. En cualquier otro plan, los tokens y direcciones que ya creaste siguen visibles y se pueden revocar, pero no se emiten nuevos y las llamadas hechas con un token dejan de atenderse. Compara los planes en la página de precios.