Desarrolladores
Integre su sistema con los expedientes de su organización mediante una interfaz de programación de solo lectura.
Envíe su credencial en cada petición con la cabecera Authorization. La credencial es de su organización y solo da acceso a sus expedientes.
Authorization: Bearer <credencial>El Administrador de su organización la crea en Administración, sección Integraciones. Se muestra completa una sola vez al crearla; después solo se ve su referencia. Se puede revocar en cualquier momento y deja de funcionar de inmediato.
El esquema Bearer no distingue mayúsculas. La credencial viaja solo en la cabecera Authorization; una credencial en la dirección, por ejemplo ?token=, no se lee (sin la cabecera responde 401).
La interfaz es de solo lectura: no crea, modifica ni cierra expedientes. Entrega solo los campos que su organización marcó como exportables.
GET /api/v1/dossiers: Lista los expedientes con decisión.GET /api/v1/dossiers/{code}: Consulta un expediente con decisión.
Solo se admite el método GET. Cualquier otro, incluido HEAD, responde 405 read_only con la cabecera Allow: GET.
Recorra los listados con el cursor: pida la página siguiente con el valor de next_cursor; cuando es null no hay más. El orden es por fecha de decisión, del más antiguo al más reciente. Si un expediente con decisión no tiene registrada la transición, su fecha de decisión es la de creación. Un expediente que recibe una nueva decisión vuelve a aparecer con su nueva fecha. Para sincronizar, pida desde un poco antes de la última fecha que recibió y descarte los códigos repetidos.
60 peticiones por minuto por credencial. Los listados devuelven 50 resultados por página (máximo 100). Al superar el límite recibe el estado 429 con la cabecera Retry-After.
Los intentos repetidos con credenciales no válidas desde una misma dirección también se frenan con el estado 429 y la cabecera Retry-After, aunque después use una credencial vigente. Si varios sistemas comparten una dirección, uno con credenciales no válidas puede afectar a los demás. Espere el tiempo de Retry-After antes de reintentar.
Toda respuesta de error tiene la forma { "error": { "code", "message" } }.
| Estado | Código | Significado |
|---|---|---|
| 400 | invalid_parameter | Un parámetro no tiene el formato esperado. |
| 401 | invalid_credential | La credencial no existe o fue revocada; no se distingue. |
| 403 | organization_unavailable | La organización no está disponible. |
| 404 | not_found | El expediente no existe o no es de su organización; no se distingue. |
| 405 | read_only | La interfaz es de solo lectura. |
| 409 | not_eligible | El expediente no tiene decisión y no está disponible. |
| 409 | no_fields | La organización no ha elegido qué campos salen. |
| 429 | rate_limited | Superó el límite de peticiones. |
| 503 | service_unavailable | El servicio no puede atender la petición ahora; reintente. |
400 invalid_parameterUn parámetro no tiene el formato esperado.
401 invalid_credentialLa credencial no existe o fue revocada; no se distingue.
403 organization_unavailableLa organización no está disponible.
404 not_foundEl expediente no existe o no es de su organización; no se distingue.
405 read_onlyLa interfaz es de solo lectura.
409 not_eligibleEl expediente no tiene decisión y no está disponible.
409 no_fieldsLa organización no ha elegido qué campos salen.
429 rate_limitedSuperó el límite de peticiones.
503 service_unavailableEl servicio no puede atender la petición ahora; reintente.
Un código inexistente y uno de otra organización dan exactamente la misma respuesta.
El estado 503 también se usa mientras la plataforma está en mantenimiento; incluye la cabecera Retry-After.
Las respuestas de los recursos no se guardan en caché (Cache-Control: no-store) y la interfaz no admite CORS: llámela desde su servidor, no desde un navegador.
Su organización puede registrar destinos https en Administración, Avisos por evento. Cada destino recibe un POST firmado cuando hay una decisión sobre un expediente, se cierra un caso, se abre una alerta o se suspende o termina una vinculación. El aviso dice qué pasó y no lleva datos personales: pida el detalle por la interfaz de programación.
Cuerpo
{
"id": "evt_01J9ZB7Q3W6XAAAAAAAAAAAAAA",
"type": "dossier.decided",
"occurred_at": "2026-10-01T10:14:03-05:00",
"organization": "alfa-ficticia",
"data": { "dossier_code": "EXP-0042", "decision": "aprobada" }
}Los tipos son dossier.decided, case.closed, alert.opened, relationship.suspended y relationship.terminated; la prueba que envía el botón del destino es ping. La fecha occurred_at va en hora de Colombia.
Cabeceras
Content-Type: application/json
User-Agent: Cotejia-Webhooks/1
Jdl-Event-Id: evt_01J9ZB7Q3W6XAAAAAAAAAAAAAA
Jdl-Signature: t=1759331643,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bdCómo verificar la firma
La firma es un HMAC SHA-256 en hexadecimal sobre el texto t, un punto y el cuerpo exacto, con el secreto completo (incluido whsec_) como llave. Rechace el aviso si la hora t difiere más de 5 minutos de la suya.
import { createHmac, timingSafeEqual } from 'node:crypto';
// secret: la llave completa que vio al crear el destino, con el prefijo whsec_
// rawBody: el cuerpo exacto que llegó, antes de convertirlo a objeto
export function verify(header, secret, rawBody, toleranceSeconds = 300) {
const parts = header.split(',').map((p) => p.split('='));
const t = Number(parts.find(([k]) => k === 't')?.[1]);
if (!Number.isInteger(t) || Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest();
// la firma puede traer dos v1 durante una rotación: basta con que uno coincida
return parts.some(([k, v]) => {
if (k !== 'v1' || !/^[0-9a-f]{64}$/.test(v ?? '')) return false;
return timingSafeEqual(Buffer.from(v, 'hex'), expected);
});
}Entrega y reintentos
- Responda con un código 2xx en menos de 10 segundos. Cualquier otra respuesta, o ninguna, cuenta como fallo. No se siguen redirecciones.
- Hay hasta 6 intentos: el primero al instante y los siguientes a 1 minuto, 5 minutos, 30 minutos, 2 horas y 12 horas del anterior.
- Cada reintento lleva el mismo id y el mismo cuerpo, con una firma nueva. Descarte los duplicados por el valor de Jdl-Event-Id.
- El orden de llegada puede variar: ordene por occurred_at si le importa.
- Si la organización está suspendida, los avisos esperan hasta 3 días y después se descartan.
Rotar el secreto
Al rotar, el secreto anterior sigue firmando durante 24 horas junto con el nuevo, y el aviso trae dos valores v1. Si rota dos veces dentro de esas 24 horas, el primer secreto anterior deja de valer: solo el último anterior sigue firmando.
Los ejemplos usan una credencial y datos ficticios. Reemplace la credencial por la suya.
Listar los expedientes con decisión desde una fecha
curl -H "Authorization: Bearer jdl_ab12cd34…" "https://cotejia.app/api/v1/dossiers?decided_since=2026-09-01T00:00:00-05:00&limit=50"Pedir la página siguiente
curl -H "Authorization: Bearer jdl_ab12cd34…" "https://cotejia.app/api/v1/dossiers?decided_since=2026-09-01T00:00:00-05:00&limit=50&cursor=<next_cursor>"Consultar un expediente
curl -H "Authorization: Bearer jdl_ab12cd34…" "https://cotejia.app/api/v1/dossiers/EXP-0042"