API REST y Webhooks para tu ERP o TMS

1. Cómo empezar

1. La API REST está disponible desde el plan GESTIONA. Con GESTIONA o ESCALA ya la tienes; la integración no lleva tarifa aparte.
2. En el panel, ve a Ajustes → API y crea una clave con permiso de escritura.
3. Guarda la clave (tcr_…): solo se muestra una vez.
4. Empléala en la cabecera Authorization de cada petición.

Con la cuenta recibes el manual de integración completo en PDF y la colección de Postman con todas las llamadas de esta página listas para enviar. Esta página es el resumen; el manual es el documento de referencia.

2. Autenticación

Todas las llamadas requieren tu clave como Bearer token:

Authorization: Bearer tcr_TU_CLAVE

Base de la API: https://app.tucontrolderutas.com

Un 401 significa siempre que la clave no vale (ausente, mal copiada o revocada): no lo reintentes, revísala. Si el problema es nuestro recibirás un 503 con codigo: "servicio_no_disponible" y cabecera Retry-After, nunca un 401. Por eso es seguro que tu integración desactive la clave ante un 401.

3. Crear un documento

Campos obligatorios en los tres modos (datos del art. 6 · Orden FOM/2861/2012)

Obligatorios además, según el modo

Si falta alguno, la respuesta es 422 con la lista exacta en detalles[]. Nunca se emite un documento a medias.

Campos opcionales (los tres modos)

Solo modo_b · menciones de la carta de porte (Ley 15/2009 art. 10)

Solo ecmr · Convenio CMR

Ejemplo

curl -X POST https://app.tucontrolderutas.com/api/v1/documentos \
  -H "Authorization: Bearer tcr_TU_CLAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "referencia_externa": "PEDIDO-2026-00123",
    "referencia_cliente": "ALB-77120",
    "expedidor_nombre": "Logística Ebro SL",
    "expedidor_nif": "B12345678",
    "expedidor_direccion": "Pol. Ind. Malpica, nave 7, 50057 Zaragoza",
    "transportista_nombre": "Trans López SL",
    "transportista_nif": "B87654321",
    "origen_direccion": "Pol. Ind. Malpica, nave 7",
    "origen_ciudad": "Zaragoza",
    "destino_direccion": "C/ Embajadores 120",
    "destino_ciudad": "Madrid",
    "descripcion_mercancias": "22 palés de bebidas",
    "peso_valor": 18400,
    "peso_unidad": "kg",
    "fecha_hora_prevista": "2026-10-06T08:15:00+02:00",
    "matricula_vehiculo": "4521KTM",
    "conductor_email": "conductor@translopez.com"
  }'

Respuesta 201 Created

{
  "ok": true,
  "idempotente": false,
  "documento": {
    "id": "8f0d…",
    "numero_control": "70268072",
    "estado": "emitido",
    "tipo_documento": "nacional",
    "modo": "solo_deca",
    "referencia_externa": "PEDIDO-2026-00123",
    "pdf_url": "https://<proyecto>.supabase.co/storage/v1/object/public/documentos/....pdf",
    "url_inspeccion": "https://app.tucontrolderutas.com/inspeccion/8f0d…",
    "url_pdf_publico": "https://app.tucontrolderutas.com/api/pdf/v/8f0d…",
    "created_at": "2026-10-06T06:15:02Z"
  }
}

# Si el documento se crea pero su PDF falla, la respuesta sigue siendo 201 y
# ademas trae "pdf_estado": "error" y "advertencia" con el motivo. Sin PDF no
# hay QR: ese documento AUN NO sirve ante inspeccion. No lo ignores.

Ojo con el campo modo: el que se ENVÍA y el que se DEVUELVE no usan el mismo vocabulario. En la petición es deca / modo_b / ecmr; en la respuesta y en los webhooks es solo_deca (DeCA) o carta_porte_como_deca, que vale tanto para la carta de porte nacional como para el eCMR. Para saber si es internacional mira tipo_documento (nacional o ecmr), no modo.

Tipos de documento (campo modo)

El mismo endpoint crea los tres tipos, y el catálogo es cerrado: deca, modo_b o ecmr. Cualquier otro valor devuelve 422 con codigo: "modo_no_reconocido". Una errata no emite nada: preferimos un 422 ruidoso a un documento equivocado viajando en la cabina. Si tu mapeo escribe el modo desde una tabla de configuración, revísalo antes de pasar a producción. El 422 llega también cuando la referencia_externa ya existe: la validación del cuerpo va por delante de la idempotencia, para que un reintento no tape el mapeo roto.

# Si omites "modo" se crea un DeCA. Es el unico respaldo que existe.

# modo_b · carta de porte que vale tambien como DeCA
{ "modo": "modo_b", ...campos comunes...,
  "destinatario_nombre": "Distribuciones Sur SL",
  "destinatario_direccion": "C/ Sevilla 10, Madrid",
  "email_expedidor": "firma@ebro.com",
  "email_transportista": "firma@translopez.com",
  "cdp_clase_embalaje": "Pales retractilados",
  "cdp_num_bultos": 24,
  "cdp_quien_paga": "destinatario",
  "cdp_declaracion_valor": 25000 }
# → queda "emitido" YA, con PDF y QR: la firma no es obligatoria para el
#   documento de control. En paralelo salen los enlaces de firma AdES, y al
#   firmar ambos el PDF se regenera en la MISMA URL (el QR no cambia).

# ecmr · carta de porte internacional
{ "modo": "ecmr", ...campos comunes...,
  "pais_origen": "ES", "pais_destino": "FR",
  "valor_mercancias": 18000, "moneda": "EUR",
  "email_expedidor": "firma@ebro.com",
  "email_transportista": "firma@translopez.com" }
# → queda "emitido" al instante, con PDF y QR, y salen los enlaces de firma AdES
#   (igual que modo_b). Hasta que firmen los dos, las casillas 22/23 del PDF dicen
#   "Pendiente de firma"; al firmar se regenera en la MISMA URL (documento.firmado).

# Cualquier otro valor escrito en "modo" → 422:
{ "ok": false, "error": "Validación de campos",
  "codigo": "modo_no_reconocido",
  "detalles": ["modo no reconocido: \"CDP\". Admitidos: deca, modo_b, ecmr ..."] }

Números: sin separador de millares

Number("1.500") en JavaScript es 1,5, no mil quinientos. Un ERP que serialice a la española mandaría un peso mil veces menor a un documento legal, y con coma decimal un dato que no es un número. No se adivina: se rechaza con 422 y el motivo exacto.

# MAL · 422 · separador de millares o coma decimal
{ "peso_valor": "1.500" }          se leeria como 1.5, no como 1500
{ "cdp_declaracion_valor": "12.000" }
{ "valor_mercancias": "1.234,56" } con coma decimal no es un numero

# BIEN · numero JSON, o cadena con punto decimal y sin separador de millares
{ "peso_valor": 1500 }
{ "peso_valor": "1500.50" }

# Campos con esta comprobacion:
#   peso_valor · peso_kg · num_bultos · cdp_num_bultos   (los tres modos)
#   cdp_declaracion_valor                                (solo modo_b)
#   valor_mercancias                                     (solo ecmr)
# En el modo que no guarda el campo NO se comprueba, porque ahi se descarta.

4. Idempotencia

Envía tu número de pedido en referencia_externa. Si repites la llamada con la misma referencia, la API no duplica el documento: devuelve el ya creado con 200 OK e idempotente: true. Así tu ERP puede reintentar tras un timeout sin riesgo de duplicar documentos. Se imprime en el PDF con el rótulo «Ref. ERP:». No la confundas con referencia_cliente: tu referencia del envío (el albarán), que también se imprime y no controla nada.

5. Restringir la clave a tus IP

Cada clave puede atarse a las direcciones de salida a internet desde las que llama tu sistema. Se configura en Ajustes → API → Claves, al crearla o después. Admite IPv4, IPv6 y notación CIDR.

203.0.113.7            una direccion suelta
198.51.100.0/24        un rango en notacion CIDR
2001:db8::/32          IPv6, igual de valido

Por qué importa: una clave de API acaba en un fichero de configuración, en un ticket y en el portapapeles de quien hace la integración. Con la lista puesta, una clave filtrada no sirve desde fuera de tu red. Si la dejas vacía no hay restricción, que es como funciona por defecto. Una petición desde una IP no declarada recibe un 403 con el código ip_no_permitida y la dirección que hemos visto, y queda registrada en la auditoría.

6. Consultar

La consulta de un documento devuelve una lista FIJA y publicada de campos, no "todo lo que haya en la tabla". Los tokens de firma no se devuelven nunca: son credenciales de un solo uso con las que se firma la entrega, y una clave de lectura no debe poder obtenerlas. Tampoco salen los campos de fontanería interna. Añadir campos a esa lista es aditivo; si alguna vez hubiera que retirar uno, se avisaría por adelantado.

Los dos endpoints de consulta de un documento devuelven exactamente el mismo objeto: la lista de campos vive en un solo sitio y no pueden divergir.

La URL del QR. Las tres consultas (la lista, por id y por referencia) devuelven url_pdf_publico, la URL que codifica el QR del PDF (descarga directa, sin login), y url_inspeccion, igual que la respuesta de crear y los webhooks. Si imprimes el QR en tus propios documentos, codifica url_pdf_publico tal cual, sin componer la URL.

Las firmas. Cada una trae quién firmó, cuándo, su tipo_firmante (receptor, el recibo de entrega, o conductor_testigo, una entrega rechazada con el motivo en notas), su numero_entrega y el hash_documento. En un DeCA agrupado la entrega 1 son las columnas destino_* y destinatario_* del documento, y la entrega k es paradas[k-2], con su referencia_cliente si se creó con entregas; las fotos de entrega (fotos_entrega) llevan el mismo numero_entrega. El hash_documento es el SHA-256 de los datos sellados en el instante de firmar: cargador (nombre, NIF y domicilio), transportista (nombre y NIF), origen y destino de la entrega 1, descripción de la mercancía, fecha prevista, matrícula, conductor, precio de referencia y número de control. Los datos de las entregas 2 en adelante no entran en él.

Las listas de conductores y vehículos traen total, pagina, limite y total_paginas. limite: null significa "sin paginar". Sin parámetros no se truncan solas a propósito: un ERP con 800 conductores viendo 50 y creyendo que tiene 50 es peor que no paginar. Un limite o una pagina que no sean enteros positivos devuelven 400 con el motivo, y pagina exige limite. Una lista vacía significa que no hay maestros: un fallo del servidor se ve como 500, no como cero filas.

7. Firma de la entrega

Un documento puede llevar tres firmas, y no se mezclan. La del contrato, en la carta de porte y el eCMR, la hacen el cargador y el transportista con firma electrónica avanzada: su enlace sale automáticamente al crear el documento, a los correos de email_expedidor y email_transportista. La de la entrega, en los tres documentos, es el acuse de recibo de quien recibe la mercancía: nombre, DNI y firma. Y la del conductor solo existe como testigo cuando quien recibe rechaza la entrega.

Por API nunca se firma en nombre de quien recibe: firma esa persona, en el móvil del conductor o con este enlace. El cuerpo es opcional: entrega solo hace falta en un DeCA agrupado (por API cada documento tiene una sola entrega) y email si quieres que enviemos el correo. La respuesta trae el enlace (url, caduca_at) y si el correo salió; lleva Cache-Control: no-store, y en la auditoría queda documento.enlace_firma con la huella del enlace, nunca el enlace. Con una clave de pruebas se devuelve el enlace y se puede firmar con él, pero no sale ningún correo.

Pedir el enlace no dispara ningún webhook. Lo que se firme te llega por los de siempre (documento.firmado_receptor y documento.completado, o documento.entrega_rechazada) y en las firmas del documento, con su numero_entrega.

Finaliza después del recibo, no antes. Un documento finalizado no admite la firma de la entrega (409 con estado_no_admite_firma_entrega) y deja de verse en la app del conductor. La firma de la entrega no es obligatoria: si no la vas a pedir, finaliza cuando termine el servicio.

8. Fin de servicio, borrado y auditoría

Marcar el fin del servicio es lo que arranca el calendario legal del documento: los 16 días de descarga pública, el año de conservación mínima y los 4 años hasta la destrucción definitiva. Si nadie lo marca, ese reloj no empieza a contar.

Estados desde los que se puede finalizar: emitido, firmado_*, completado, entrega_rechazada y pendiente_firma_aes (de los firmado_*, el único que produce un flujo es firmado_receptor, el paso previo a completado; firmado_cargador y firmado_conductor están en el catálogo, ningún flujo los produce y se tratan como emitido). Un documento que siga en ese estado (sin PDF ni QR, con las firmas AdES sin llegar) también se puede cerrar: se le anota el fin de servicio pero conserva su estado, porque nunca se emitió. La respuesta lo dice con emitido: false y una nota. No compruebes el éxito con estado === "finalizado"; compruébalo con ok: true. En cualquier otro estado se devuelve 409 con codigo: "estado_no_finalizable", estado_actual y la lista de estados admitidos.

Un documento de control no se puede borrar antes de 1 año desde el fin del servicio: lo impone la Resolución DGTCyF (apartado Segundo.4) y no lo puede saltar nadie. A partir de ahí sí se borra a petición, y a los 4 años se destruye solo. La única excepción son los documentos que nunca llegaron a emitirse (borrador o pendiente_firma_aes): no fueron válidos ni un segundo, no tienen PDF ni QR y no hay nada que conservar, así que se borran en el acto, con o sin fin de servicio marcado.

En la exportación al SIEM aparecen también los accesos de nuestro soporte a tu cuenta (superadmin.acceder), los intentos de acceso denegados (usuario.login con resultado: denegado) y el uso de una clave que ya habías revocado (api.autenticar con detalles.motivo: "clave_revocada", que es la señal de una credencial filtrada). La tabla es de solo-añadir: nadie puede reescribirla, nosotros tampoco.

9. Sincronizar maestros

Da de alta y mantén al día conductores, vehículos y clientes desde tu ERP. El alta es idempotente por la clave natural (dni_nie / matricula / nif): si ya existen, se devuelven sin duplicar (200). Para cambiar un dato, PATCH: manda solo lo que cambia y localiza la ficha por tu propia clave, sin guardar identificadores nuestros.

# Alta de conductor (idempotente por dni_nie)
curl -X POST https://app.tucontrolderutas.com/api/v1/conductores \
  -H "Authorization: Bearer tcr_TU_CLAVE" -H "Content-Type: application/json" \
  -d '{ "nombre": "Juan", "apellidos": "Martín Ruiz",
        "dni_nie": "51234829Y", "telefono": "612345678",
        "email": "juan@translopez.com" }'
# → { "ok": true, "idempotente": false, "conductor": { "id": "…", … } }
#   Ese "id" es el conductor_id que se manda al crear el documento.

# Conductor extranjero: se acepta su documento tal cual y su telefono con prefijo
  -d '{ "nombre": "Ion", "apellidos": "Popescu",
        "dni_nie": "RO-CJ-472019", "telefono": "0040712345678" }'

# Alta de vehiculo (idempotente por matricula)
curl -X POST https://app.tucontrolderutas.com/api/v1/vehiculos \
  -H "Authorization: Bearer tcr_TU_CLAVE" -H "Content-Type: application/json" \
  -d '{ "matricula": "4521KTM", "tipo": "articulado", "remolque": "R5678CD" }'

# Alta de cliente / contraparte (idempotente por nif)
curl -X POST https://app.tucontrolderutas.com/api/v1/clientes \
  -H "Authorization: Bearer tcr_TU_CLAVE" -H "Content-Type: application/json" \
  -d '{ "nombre": "Logistica Ebro SL", "nif": "B50123456",
        "direccion": "Pol. Ind. Malpica, calle A, 12",
        "ciudad": "Zaragoza", "cp": "50016", "pais": "ES" }'

# MODIFICAR: manda solo lo que cambia, localizando la ficha por TU clave natural
curl -X PATCH https://app.tucontrolderutas.com/api/v1/conductores/51234829Y \
  -H "Authorization: Bearer tcr_TU_CLAVE" -H "Content-Type: application/json" \
  -d '{ "telefono": "+34600111222" }'
# → { "ok": true, "actualizado": true, "campos_actualizados": ["telefono"], … }
#   Lo que no mandas NO se toca. "email": null lo vacia a proposito.
#   La clave natural (dni_nie / matricula / nif) no se cambia por esta via.

# Baja de una ficha: deja de aparecer para elegir y no toca los documentos emitidos
curl -X PATCH https://app.tucontrolderutas.com/api/v1/vehiculos/4521KTM \
  -H "Authorization: Bearer tcr_TU_CLAVE" -H "Content-Type: application/json" \
  -d '{ "activo": false }'

10. Webhooks

Registra una URL en Ajustes → API → Webhooks y te enviaremos un POST cada vez que un documento cambie de estado, sin que tengas que sondear la API. Puedes suscribirte a * (todos) o a los eventos concretos de la lista. Un evento que no esté en ella se rechaza con 400 y la lista de los válidos.

Eventos

Esos son todos. Al completarse las dos firmas AdES (carta de porte y eCMR) llega documento.firmado y el PDF se regenera en la misma URL. Como cada entrega puede reintentarse, el receptor debe ser idempotente.

DeCA agrupado (varias entregas en un documento, apartado Sexto de la Resolución). Se crea por API con entregas (modo deca), o lo emiten tu oficina o tus conductores, y te llega por los mismos webhooks. Cada entrega tiene su recibo y el documento sigue en emitido hasta resolver la última: un recibo intermedio no manda nada, cada rechazo llega en el momento y documento.firmado_receptor y documento.completado llegan con la última entrega, si todas tienen recibo. Si alguna se rechazó, el documento se cierra en entrega_rechazada y documento.entrega_rechazada puede llegarte más de una vez: distínguelo por el estado del cuerpo. El cuerpo no dice qué entrega fue; lo dicen las firmas del documento, por su numero_entrega.

Qué recibes

POST  https://tu-erp.com/webhooks/tcr
X-TCR-Evento:     documento.completado
X-TCR-Entrega:    3f9c1d0e-…          ← id de ESTA entrega · usalo para deduplicar
X-TCR-Timestamp:  1791450730           ← segundos Unix
X-TCR-Firma:      sha256=2b1c…         ← HMAC-SHA256 del cuerpo
X-TCR-Firma-V2:   sha256=9ad4…         ← HMAC-SHA256 de "<timestamp>.<cuerpo>"
User-Agent:       TuControlDeRutas-Webhook/1

{
  "evento": "documento.completado",
  "enviado_at": "2026-10-06T14:32:10.412Z",
  "prueba": false,
  "documento": {
    "id": "8f0d…",
    "numero_control": "70268072",
    "estado": "completado",
    "tipo_documento": "nacional",
    "modo": "solo_deca",
    "referencia_externa": "PEDIDO-2026-00123",
    "pdf_url": "https://<proyecto>.supabase.co/storage/v1/object/public/documentos/….pdf",
    "url_inspeccion": "https://app.tucontrolderutas.com/inspeccion/8f0d…",
    "url_pdf_publico": "https://app.tucontrolderutas.com/api/pdf/v/8f0d…",
    "origen_ciudad": "Zaragoza",
    "destino_ciudad": "Madrid",
    "created_at": "2026-10-06T06:15:02.000Z",
    "updated_at": "2026-10-06T14:32:09.880Z"
  }
}

El objeto documento lleva siempre las mismas claves; lo que no se conozca viaja como null. El campo prueba también va siempre: false en los eventos reales y true en el que lanzas desde el panel. El evento de prueba tiene exactamente la misma forma que el real (mismas claves y en el mismo orden), así que puedes cablear y validar tu esquema contra él: lo que recibas en producción es idéntico salvo los valores.

Entrega y reintentos

Tu endpoint tiene 1,5 segundos para responder 2xx. Si tarda más, abortamos la conexión y la entrega se reintenta: 6 intentos con esperas de 1, 5, 30, 120 y 360 minutos, unas 8 horas y media de margen. El barrido corre cada 5 minutos, así que si tu receptor se cae diez minutos el evento vuelve enseguida, no al día siguiente. Encola y responde de inmediato; no hagas el trabajo pesado dentro de la petición del webhook, y haz tu receptor idempotente: un mismo evento puede llegarte más de una vez. Deduplica por X-TCR-Entrega.

El secreto de firma

Cada webhook lleva su propio secreto. Puedes traer el tuyo al crearlo, útil si ya lo guardas en tu gestor de secretos, así no tiene que salir de ahí, o dejar el campo vacío y lo generamos nosotros. Mínimo 24 caracteres, máximo 200, ASCII imprimible y sin espacios.

Se rota sin perder nada: hay un botón para ello y no hace falta borrar el webhook ni su historial. Desde la rotación firmamos con el nuevo, y como reintentamos hasta 6 veces durante unas 8 horas, tienes ese margen para actualizarlo sin perder ningún evento.

Verificar la firma

Cada envío incluye dos firmas, y las dos van siempre. X-TCR-Firma es el HMAC-SHA256 del cuerpo crudo con tu secret. X-TCR-Firma-V2 firma "<timestamp>.<cuerpo>", y es la que deberías usar: comprobando que X-TCR-Timestamp cae dentro de una ventana (5 minutos es lo habitual) puedes rechazar una entrega vieja reenviada, cosa que la v1 por sí sola no permite. La v1 se mantiene para no romper a quien ya la verifica.

// Node.js (Express) · se verifica la V2, que ademas corta los reenvios
const crypto = require('crypto')

app.post('/webhooks/tcr', express.raw({ type: '*/*' }), (req, res) => {
  const ts    = req.headers['x-tcr-timestamp'] || ''
  const firma = req.headers['x-tcr-firma-v2'] || ''

  // Ventana anti-reenvio: sin ella, una entrega capturada vale para siempre.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.status(401).end()

  const esperado = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(ts + '.' + req.body)   // cuerpo CRUDO, sin parsear
    .digest('hex')

  const a = Buffer.from(String(firma)), b = Buffer.from(esperado)
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) return res.status(401).end()

  // Responde YA (tienes 1,5 s) y procesa despues, de forma idempotente:
  // una misma entrega puede llegarte mas de una vez. Deduplica por X-TCR-Entrega.
  res.status(200).end()
  encolar(JSON.parse(req.body))
})

<?php // PHP
$cuerpo = file_get_contents('php://input');
$ts     = $_SERVER['HTTP_X_TCR_TIMESTAMP'] ?? '';
$firma  = $_SERVER['HTTP_X_TCR_FIRMA_V2']  ?? '';

if (abs(time() - (int)$ts) > 300) { http_response_code(401); exit; }

$esperado = 'sha256=' . hash_hmac('sha256', $ts . '.' . $cuerpo, $WEBHOOK_SECRET);
if (!hash_equals($esperado, $firma)) { http_response_code(401); exit; }

http_response_code(200);          // responde primero
$evento = json_decode($cuerpo, true);
// … encola y procesa fuera de esta peticion …

11. Errores y límites

Toda respuesta de error lleva ok: false y error (texto para leer). Cuando existe, trata el campo codigo, que es estable, y no el texto del mensaje, que puede cambiar. No todos los errores traen codigo; los de validación de documentos y de maestros traen siempre detalles[], un array de cadenas campo a campo.

Límites por clave

Son cortafuegos anti-abuso, no un freno a la emisión legítima. Y como crear es idempotente por referencia_externa, reintentar tras un 429 nunca duplica un documento. Respeta el Retry-After: la ventana es fija, así que un reintento anticipado se lleva otro 429.

Códigos estables