Integraciones · versión 1.3.0

API de DeCAred

API de integraciones de DeCAred, incluida en el plan Documentos ilimitados + carta de porte. Consulta documentos y PDF, prepara y modifica borradores y mantiene la agenda. La version 1.3 incorpora seguimiento privado y operaciones de oficina en dos pasos: propuesta con resumen y confirmacion explicita vinculada a su revision. Las claves anteriores conservan solo sus permisos anteriores. Emitir y corregir usa los servicios de DeCAred y puede planificar entregas reales al conductor.

Especificación OpenAPI 3: https://decared.com/api/v1/openapi.json. Sirve para generar clientes y para conectores de Zapier, Make, n8n o Power Automate.

Autenticación

La API está incluida en el plan Documentos ilimitados + carta de porte. Con ese plan, crea una clave en DeCAred → Más → Integraciones. Cada clave pertenece a una empresa y tiene permiso de lectura, de escritura o de ambos. Envíala en cada petición:

curl https://decared.com/api/v1/me \
  -H "Authorization: Bearer dcr_xxxxxxxxxxxx_…"

Límite: 120 peticiones por minuto por clave. Al superarlo, la respuesta es 429 con la cabecera Retry-After.

Para nuevas conexiones, concede solo los permisos necesarios: documents:read, drafts:read, drafts:write, counterparties:read/write, vehicles:read/write, drivers:read/write y webhooks:manage. En los permisos de agenda, elige :read o :write por separado. Gestionar webhooks permite recibir datos de documentos. Las claves generales read y write siguen funcionando; read conserva también la gestión de webhooks.

Las respuestas autenticadas no se almacenan en cachés compartidas. Cada petición tiene una cabecera X-Request-ID para localizar incidencias; las respuestas correctas autenticadas también indican X-RateLimit-Limit y X-RateLimit-Remaining.

Operaciones

Crear un borrador desde tu sistema

POST /drafts crea el borrador sin emitirlo. Una persona puede revisarlo y emitirlo en DeCAred, habilitarlo para el conductor o utilizar las operaciones confirmadas de la API 1.3 con los permisos específicos. Indica el pedido de tu sistema en external_reference: si repites la misma petición, recibes el mismo registro.

curl -X POST https://decared.com/api/v1/drafts \
  -H "Authorization: Bearer dcr_…" -H "Content-Type: application/json" \
  -d '{
    "external_reference": "PED-2026-0457",
    "shipper_nif": "B23456783",
    "vehicle_plate": "2456KLM",
    "driver_nif": "12345678Z",
    "service_date": "2026-11-02",
    "shipments": [{"origin": "Madrid", "destination": "Zaragoza", "goods": "Fruta", "weight": 12000}]
  }'

Si repites el mismo pedido con los mismos datos, recibes 200 y Idempotent-Replayed: true, incluso después de pasar la fecha del servicio. Si utilizas esa referencia con otros datos, recibes 409 con código external_reference_conflict: consulta el registro existente antes de continuar. Se normalizan el orden de campos, los NIF, las matrículas y el peso numérico; conserva los mismos campos del pedido original. Los borradores antiguos sin huella de creación mantienen el comportamiento anterior. Sin referencia externa no se garantiza evitar duplicados.

Puedes buscar borradores pendientes con GET /api/v1/drafts?external_reference=PED-2026-0457. Un reintento no sobrescribe cambios hechos después por la oficina.

Sincronización por cursor

Para documentos, borradores y agenda, empieza con ?pagination=cursor&per_page=100. La respuesta incluye meta.next_cursor, meta.has_more y meta.sync_until. Repite la consulta con el cursor, codificado como parámetro de URL, y los mismos filtros hasta que has_more sea falso. Cada cursor pertenece a una empresa, un recurso y unos filtros, y caduca a las 24 horas. No lo combines con page.

Solo al completar todas las páginas, guarda sync_until. En el siguiente ciclo úsalo como updated_since y empieza sin cursor. El límite superior es exclusivo y los registros se ordenan por fecha de cambio e identificador: los cambios durante el recorrido se recuperan en el siguiente ciclo. No es una fotografía inmutable ni un historial de eliminaciones. Reconcilia por id y updated_at; un registro puede aparecer de nuevo si cambia. Los cambios del segundo actual se difieren al ciclo siguiente. La paginación anterior por páginas sigue disponible.

GET /api/v1/documents?pagination=cursor&per_page=100
GET /api/v1/documents?pagination=cursor&per_page=100&cursor=TOKEN_CODIFICADO

// Tras completar el recorrido, empieza otro ciclo:
GET /api/v1/documents?pagination=cursor&updated_since=SYNC_UNTIL_CODIFICADO

Errores y reintentos

Los errores conservan message y, en validación, errors. Añaden code y request_id. Usa el código para automatizar la respuesta y facilita el identificador al soporte; nunca envíes la clave ni el secreto del webhook.

Operaciones confirmadas · API 1.3

Preparar propuestas tiene un límite adicional de treinta peticiones por minuto y clave, con 429 y Retry-After. El resto conserva el límite general de 120 peticiones por minuto y clave.

Las claves generales read y write mantienen su alcance anterior. Para editar borradores existentes se necesita drafts:edit; para seguimiento privado, tracking:read; para descargar sus adjuntos, attachments:read. Este seguimiento incluye mensajes y notas internas: concede el permiso solo a programas de confianza.

Las acciones de oficina necesitan su permiso específico: documents:issue, documents:correct, documents:close, documents:annul, documents:resend, issues:report, issues:manage o messages:send. El creador de la clave debe seguir activo, con acceso a la empresa y con un rol de gestión; no basta con poseer el token.

1. Consulta el documento o borrador y su revision. Si editas el borrador, usa PATCH /drafts/{id} con revision y data. Los nombres nativos se encuentran en document_data; no son los nombres de creación inicial. Solo se combinan los campos enviados; shipments sustituye la lista completa.
2. Prepara la acción con POST /documents/{id}/actions. No ejecuta la acción. Devuelve un resumen, el identificador y un confirmation_token de un solo procedimiento, válido durante quince minutos.
3. Muestra el resumen y solicita autorización expresa. Confirma con la misma clave mediante POST /operations/{operation}/confirm. La integración declara esa autorización con confirmed: true; el servidor no verifica por sí mismo quién pulsó un botón externo.
4. Guarda el identificador. Si pierdes la respuesta, consulta GET /operations/{operation} o repite la misma confirmación: si terminó, devuelve su resultado sin repetir el efecto. Un estado executing o uncertain exige conciliación; no prepares otra emisión o reenvío a ciegas.

// 1. Propuesta; utiliza la revisión que acabas de consultar.
POST /api/v1/documents/123/actions
{"action":"issue","revision":4}

// 2. Después de revisar el resumen y autorizarlo expresamente:
POST /api/v1/operations/UUID_DEVUELTO/confirm
{"confirmed":true,"confirmation_token":"TOKEN_DEVUELTO"}

Una corrección usa action: correct, reason y los cambios nativos en data; conserva las versiones anteriores. Cerrar exige que el conductor ya haya comunicado la finalización. Anular requiere motivo, no cancela firmas ni devuelve créditos. Emitir o corregir puede consumir cupo y planificar entregas reales al conductor. Reenviar puede duplicar una entrega; la aceptación de ese riesgo se declara en la propuesta con accept_duplicate.

Para una incidencia de oficina prepara report_issue con body, categoría, prioridad y motivo si es urgente; se registra como nota interna, sin atribuirla al conductor. Para resolverla usa resolve_issue con issue_id y la resolución en body. Para escribir usa message, body y visibility: shared (conductor) o internal (solo oficina). Los adjuntos se envían al preparar mediante multipart/form-data, en attachments[]: máximo tres JPEG, PNG o PDF de 1 MiB cada uno, comprobados por contenido.

El estado se consulta en /documents/{id}/tracking. Sus colecciones deliveries, interactions, issues, issue_events, messages y attachments usan paginación por páginas, con hasta cien registros. No son un cursor de sincronización. Los adjuntos tienen descarga protegida y comprobación de integridad.

Alcance: las acciones de esta versión gestionan DeCA independientes de mercancías; no crean cartas de porte, hojas de ruta, anexos contractuales ni firmas. Tampoco confirman recepción o finalización en nombre del conductor. Cerrar no resuelve incidencias: se pueden seguir gestionando y anotando internamente después del cierre. Los eventos de mercancía y sus evidencias específicas mantienen sus pantallas actuales. Los webhooks existentes no incorporan todavía eventos de incidencias o mensajes.

Webhooks

Añade una dirección https:// en Integraciones y elige los eventos. DeCAred envía un POST con este cuerpo y reintenta los fallos durante unas horas. Entrega al menos una vez: usa el id para no procesar dos veces el mismo evento, y responde 2xx en menos de 10 segundos.

{
  "id": "6f1c…-uuid",
  "event": "document.issued",
  "created_at": "2026-10-21T08:15:02+02:00",
  "company_id": 12,
  "data": { "id": 1095, "reference": "DECA-2026-001095", "status": "open", "current_version": { "number": 1, "pdf_url": "…" }, … }
}

Verificar la firma. La cabecera DeCAred-Signature tiene la forma t=1792490894,v1=…: calcula HMAC-SHA256 de t + "." + cuerpo con el secreto del destino y compáralo con v1. Rechaza las firmas de más de cinco minutos.

// PHP
$body = file_get_contents('php://input');
$valid = preg_match('/\At=(\d{1,12}),v1=([a-f0-9]{64})\z/', $_SERVER['HTTP_DECARED_SIGNATURE'] ?? '', $parts) === 1;
$ok = $valid && abs(time() - (int) $parts[1]) < 300 &&
  hash_equals(hash_hmac('sha256', $parts[1].'.'.$body, $secret), $parts[2]);

// Node.js
const parts = typeof header === 'string' ? /^t=(\d{1,12}),v1=([a-f0-9]{64})$/.exec(header) : null;
const ok = parts !== null && Math.abs(Date.now() / 1000 - Number(parts[1])) < 300 &&
  crypto.timingSafeEqual(crypto.createHmac('sha256', secret).update(`${parts[1]}.${rawBody}`).digest(), Buffer.from(parts[2], 'hex'));

n8n

Conecta DeCAred con n8n con una clave de API. Para recibir avisos, tu n8n debe ser accesible desde Internet con https://, como n8n Cloud o un servidor propio con certificado.

Permisos. Las claves generales conservan las operaciones anteriores. Las acciones de API 1.3, la edición y el seguimiento requieren permisos nuevos explícitos; no se heredan de read/write. Cada flujo necesita los suyos: documents:read para documentos y PDF, drafts:write para crear borradores, drafts:edit para editarlos y tracking:read para seguimiento.

Plantillas. Con los nodos estándar de n8n (Webhook, HTTP Request y Code). Descarga el archivo e impórtalo en n8n con Import from File; cada plantilla explica en una nota qué debes rellenar y qué permiso necesita la clave.

En las plantillas, la clave va en una credencial Header Auth con nombre Authorization y valor Bearer dcr_…. La plantilla de avisos comprueba la firma con el nodo estándar Crypto: guarda el secreto del destino en una credencial Crypto, en el campo Hmac Secret.

Las dos plantillas de operaciones usan nodos estándar y no necesitan instalar el nodo de la comunidad. Revisa la propuesta exacta antes de confirmar, con la misma clave y dentro de quince minutos. No conectes automáticamente preparación y confirmación. Protege y elimina el token de la configuración y de las ejecuciones tras usarlo; no exportes el flujo con él. Ante timeout consulta la misma operación; los estados executing o uncertain requieren conciliación manual.

Power Automate

Descargar conector personalizado API 1.3 y guía. Incluye Swagger 2.0, configuración de conexión y recetas para aprobación humana, confirmación y recuperación. Ofrece las 28 operaciones del contrato de la API, incluidos edición, seguimiento y descarga de adjuntos. Para subir archivos al preparar, configura una acción HTTP multipart según la guía.

Importa apiDefinition.swagger.json en Conectores personalizados. La conexión usa API key en la cabecera Authorization: introduce Bearer dcr_… completo. Necesitas una cuenta y licencia que permitan conectores personalizados. Leer la guía de configuración y pruebas.

Estado de validación: archivos comprobados localmente; pendientes la importación y las pruebas en una cuenta Microsoft. No es un conector certificado del catálogo. El nodo de comunidad de n8n sigue pendiente de publicación en npm; las plantillas de nodos estándar ya se pueden descargar.

Buenas prácticas

• Para sondear cambios sin webhooks, consulta /documents?updated_since= con la fecha de tu última consulta.
• Los datos de un documento emitido proceden de su versión: no cambian aunque después se edite la agenda. Una corrección crea otra versión y el evento document.corrected.
• Comprueba la huella sha256 del PDF descargado. Guarda las claves y secretos como contraseñas: si se filtran, revócalos en Integraciones.

¿Dudas o un conector que necesites? info@decared.com