API de DeCA gratis

Empezar en 3 pasos

1. Crea una clave en Integraciones (lo hace quien administra la cuenta). Empieza por dg_live_ y solo se enseña una vez.

2. Pruébala en el entorno de pruebas: abre una cuenta en deca-demo.transportistastop10.com y crea allí una clave dg_test_. Base: https://deca-demo.transportistastop10.com/api/v1. Nada de lo que hagas allí vale ni se mezcla con datos reales.

3. Crea tu primer DeCA:

   curl -X POST https://deca.transportistastop10.com/api/v1/decas \
     -H "Authorization: Bearer dg_live_…" \
     -H "Content-Type: application/json" \
     -d '{
       "ref_externa": "PED-1001",
       "referencia": "Albarán 1001",
       "fecha_transporte": "2026-10-07",
       "cargador_nombre": "Frutas Huerta S.L.",
       "cargador_nif": "B12345674",
       "cargador_domicilio": "Calle Mayor 1, 03001 Alicante",
       "matricula": "1234BCD",
       "matricula_remolque": "R5678BCF",
       "conductor_nombre": "Juan Pérez",
       "conductor_tel": "600123456",
       "envios": [
           {
               "origen": "Alicante",
               "destino": "Valencia",
               "naturaleza": "Fruta en cajas",
               "peso": 12000,
               "unidad": "kg"
           }
       ]
   }'

   No hace falta dar de alta antes clientes, direcciones ni vehículos: si eres el transportista, tu lado se rellena con tu empresa. La respuesta (201) trae el DeCA con la URL del PDF y del QR:

   {
       "deca": {
           "id": 4821,
           "numero": "2026-000123",
           "estado": "emitido",
           "version": 1,
           "emisor_rol": "transportista",
           "ref_externa": "PED-1001",
           "canal": "api",
           "cargador_nombre": "Frutas Huerta S.L.",
           "…": "(todos los campos de entrada)",
           "envios": [
               {
                   "origen": "Alicante",
                   "destino": "Valencia",
                   "naturaleza": "Fruta en cajas",
                   "peso": 12000,
                   "unidad": "kg",
                   "nota": null
               }
           ],
           "urls": {
               "pdf": "https://deca.transportistastop10.com/d/Xy7….pdf",
               "qr_png": "https://deca.transportistastop10.com/d/Xy7….png",
               "conductor": "https://deca.transportistastop10.com/c/Xy7…",
               "completar": null,
               "ficha": "https://deca.transportistastop10.com/deca/4821"
           },
           "pdf_sha256": "9f2c…",
           "pdf_bytes": 108544,
           "emitido_at": "2026-10-06 09:14:03",
           "modificado_at": "2026-10-06 09:14:03",
           "fin_servicio_at": null,
           "created_at": "2026-10-06 09:14:02",
           "sustituye_a": null,
           "sustituido_por": null,
           "archivado": false,
           "descargas": 0
       },
       "avisos": []
   }

Autenticación, formato y límites

• Clave en Authorization: Bearer dg_live_… (o en X-API-Key). Permiso de lectura y escritura o de solo lectura. Si una clave se filtra, revócala en Integraciones.
• JSON en UTF-8. Los campos se llaman igual al mandar y al leer. Fechas AAAA-MM-DD; peso numérico (12000) o como lo escribiría una persona («12.000»).
• Sin duplicados: manda ref_externa (o la cabecera Idempotency-Key). Si repites la petición, te devolvemos el DeCA que ya existe (200 y Idempotent-Replayed: true), no uno nuevo.
• Límites: 120 peticiones por minuto y clave (cabeceras RateLimit-*; si te pasas, 429 con Retry-After). Hasta 48 envíos por DeCA y 500 DeCA por CSV.
• Cada respuesta lleva X-Request-Id: dánoslo si nos escribes por un problema.
• Los POST llevan siempre cuerpo, aunque sea {} (el cortafuegos del servidor rechaza con 403 un POST sin Content-Length).

Campos del DeCA

Los datos del art. 6 de la Orden FOM/2861/2012. Te decimos en el error exactamente cuál falta.

Con matricula_remolque el vehículo pasa a ser articulado. Si mandas solo tu lado con "emitir": false, el DeCA queda pendiente y urls.completar es el enlace para el otro lado.

Errores

{
    "error": {
        "codigo": "validacion",
        "mensaje": "Faltan datos o no son válidos: Falta la matrícula del vehículo.",
        "campos": {
            "matricula": "Falta la matrícula del vehículo."
        },
        "avisos": [],
        "request_id": "req_…"
    }
}

Webhooks

POST con JSON a tu URL (https) en cuanto pasa algo. Si no respondes 2xx en 10 s, reintentamos a 1 min, 5 min, 30 min, 2 h y 12 h. Cada entrega queda registrada en Integraciones.

POST /tu-webhook
X-Deca-Evento: deca.emitido
X-Deca-Entrega: ev_…            (único: úsalo para no procesar dos veces)
X-Deca-Firma: t=1759651200,v1=5b1c…

{
    "id": "ev_…",
    "evento": "deca.emitido",
    "creado_at": "2026-10-06T11:16:12+02:00",
    "entorno": "produccion",
    "data": {
        "deca": "(el mismo objeto que GET /decas/{id})"
    }
}

Comprueba la firma: HMAC-SHA256 con tu secreto (whsec_…) de t + "." + cuerpo, y rechaza si t tiene más de 5 minutos.

// PHP
[$t, $v1] = array_map(fn($p) => explode('=', $p, 2)[1], explode(',', $_SERVER['HTTP_X_DECA_FIRMA']));
$cuerpo = file_get_contents('php://input');
$ok = abs(time() - (int)$t) < 300 && hash_equals(hash_hmac('sha256', $t . '.' . $cuerpo, $SECRETO), $v1);

// Node.js
const [t, v1] = req.headers['x-deca-firma'].split(',').map(p => p.split('=')[1]);
const ok = Math.abs(Date.now()/1000 - t) < 300 &&
  crypto.timingSafeEqual(Buffer.from(crypto.createHmac('sha256', SECRETO).update(t + '.' + cuerpoCrudo).digest('hex')), Buffer.from(v1));

# Python
t, v1 = [p.split('=', 1)[1] for p in request.headers['X-Deca-Firma'].split(',')]
ok = abs(time.time() - int(t)) < 300 and hmac.compare_digest(hmac.new(SECRETO.encode(), f"{t}.".encode() + cuerpo, 'sha256').hexdigest(), v1)

deca.descargado te avisa cuando alguien abre la URL pública o el QR: en ruta, suele ser una inspección.

Importación CSV

Desde la web (Integraciones → Importar) o por la API (POST /importar). Cada fila es un envío; las filas con la misma ref_externa (o la misma referencia) forman un DeCA. Volver a subir el mismo fichero no duplica nada. Separador «;» o «,»; UTF-8 o el CSV de Excel.

Columnas: ref_externa;referencia;fecha_transporte;cargador;cargador_nif;cargador_domicilio;transportista;transportista_nif;origen;destino;mercancia;peso;unidad;tipo_vehiculo;matricula;remolque;autorizacion_especial;conductor;conductor_tel;observaciones — y opcional emisor_rol. Son las mismas que la exportación de «Mis DeCA», así que puedes exportar, cambiar y volver a importar. Descargar la plantilla.

curl -X POST "https://deca.transportistastop10.com/api/v1/importar?validar=1" -H "Authorization: Bearer dg_live_…" -H "Content-Type: text/csv" --data-binary @decas.csv

Agentes de IA (MCP)

Conecta Claude, Cursor o VS Code a tu cuenta y pídele en lenguaje normal «hazme el DeCA del porte de mañana a Valencia con el 1234BCD». El servidor MCP usa la misma clave que la API y sus mismos permisos: con una clave de solo lectura, el agente solo puede consultar.

Servidor: https://deca.transportistastop10.com/mcp (HTTP «streamable», JSON-RPC 2.0). Herramientas: ver_cuenta, listar_decas, ver_deca, historial_deca, descargas_deca, buscar_agenda y, con clave de escritura, leer_albaran (foto → datos), validar_deca, crear_deca, modificar_deca, sustituir_deca, emitir_deca, enviar_deca, pedir_datos y fin_servicio.

# Claude Code
claude mcp add --transport http deca-gratis https://deca.transportistastop10.com/mcp --header "Authorization: Bearer dg_live_…"

# Cursor (~/.cursor/mcp.json) · VS Code (.vscode/mcp.json, con "servers" y "type": "http")
{ "mcpServers": { "deca-gratis": { "url": "https://deca.transportistastop10.com/mcp",
    "headers": { "Authorization": "Bearer dg_live_…" } } } }

# Claude Desktop (claude_desktop_config.json), a través de mcp-remote
{ "mcpServers": { "deca-gratis": { "command": "npx",
    "args": ["mcp-remote", "https://deca.transportistastop10.com/mcp", "--header", "Authorization: Bearer dg_live_…"] } } }

Para probar sin riesgo, usa una clave dg_test_ con https://deca-demo.transportistastop10.com/mcp. Los conectores que solo admiten OAuth (como ChatGPT) todavía no.

n8n, Make y Zapier

• n8n: descarga la plantilla e impórtala (menú del flujo → «Import from file»). Trae dos flujos: uno recibe los avisos de DeCA gratis y separa las posibles inspecciones (deca.descargado), y otro crea un DeCA con los datos que le pases. Pon tu clave en el nodo «Crear DeCA».
• Make: para crear DeCA, módulo HTTP › Make a request: método POST, URL https://deca.transportistastop10.com/api/v1/decas, cabecera Authorization: Bearer dg_live_…, cuerpo JSON como el del ejemplo de arriba. Para recibir avisos, módulo Webhooks › Custom webhook y pega su URL en Integraciones.
• Zapier: igual, con Webhooks by Zapier: «POST» para crear DeCA y «Catch Hook» para recibir los avisos (en los planes de Zapier que incluyen Webhooks).

Preguntas frecuentes