¿Ya tienes tu propio ERP o software de gestión de transporte?

Aprovecha el motor de DeCAFacil sin cambiar de herramienta: emite el DeCA directamente desde tu sistema, con la misma trazabilidad y el mismo QR legal que la aplicación web. Esta página es la documentación de referencia del canal /api/v1 para quien va a integrarlo.

Las claves de API son una mejora de la suscripción Premium (precio y condiciones en precios y tarifas): hace falta tenerla activa para crear y gestionar tus claves desde /claves-api. Actívala ya, gratis: no empezarás a pagar hasta enero de 2027 — ver modo de pruebas y condiciones.

Última actualización: 4 de septiembre de 2026.

Qué es y para quién es

El canal de API está pensado para la misma empresa que hoy usaría la aplicación web, pero emitiendo desde su propio software en vez de entrar en la PWA. No es una API abierta para programadores en general: la clave pertenece a la empresa (identificada por su NIF), no a quien escribe la integración, y esa empresa debe figurar siempre como cargador contractual o transportista efectivo en cada DeCA que emita por esta vía — la misma regla de «parte activa» que rige el resto del servicio.

El valor práctico: no mantener dos bases de datos. DeCAFacil no necesita ni usa tus maestros de clientes, vehículos o direcciones — le mandas los datos del envío, genera el documento con su código QR, y tu sistema sigue siendo la única fuente de verdad para todo lo demás.

Cómo empezar

Da de alta tu empresa en DeCAFacil — como cualquier cuenta, con nombre y NIF, desde la aplicación. La clave de API cuelga de una cuenta real, no hay atajos.
Activa la suscripción — desde /suscripcion dentro de la aplicación. Gratis hasta enero de 2027 (ver condiciones).
Crea tu clave tú mismo — en /claves-api: le pones un identificador para reconocerla, aceptas el anexo de términos de la API y se genera al momento. El secreto se muestra una única vez: apúntalo en un lugar seguro en cuanto lo veas, porque ni nosotros podemos volver a mostrártelo.

Autenticación

Cada petición lleva la clave en la cabecera:

Authorization: Bearer <tu-clave>

Nada impide tener varias claves para la misma empresa (por ejemplo, una para oficina y otra para almacén): todas identifican a la misma titular y se pueden revocar por separado.

Qué puedes hacer

El esquema completo de peticiones y respuestas se publicará aquí en cuanto esté cerrado (ver ejemplos de código, a continuación). Por ahora, las operaciones disponibles en /api/v1:

Emitir un DeCA nuevo, con soporte de identificador propio para evitar duplicados si reintentas una petición.
Consultar un DeCA por su identificador, listar los tuyos con paginación, y descargar el PDF vigente.
Modificar un DeCA durante el servicio (fraccionar o eliminar envíos, con la misma lógica que la PWA).
Finalizar el servicio, cuando corresponda.
Avisar al conductor del documento generado.
Anular un DeCA.

Ejemplos de código

Nota sobre estos ejemplos. Emiten el mismo DeCA de ejemplo (Cargas Ejemplo SA → Transportes Ejemplo SL, Getafe → Valencia) que usa el resto de esta documentación. Sustituye <tu-clave> por tu clave real y, si no tienes una todavía, empieza por cómo empezar.

cURL

curl -X POST https://decafacil.es/api/v1/deca \
  -H "Authorization: Bearer <tu-clave>" \
  -H "Content-Type: application/json" \
  -d '{
  "datos": {
    "cargador_contractual": {
      "nombre": "Cargas Ejemplo SA",
      "nif": "A76543214",
      "direccion": {
        "empresa": "Cargas Ejemplo SA",
        "via": "Calle Mayor 12",
        "localidad": "Getafe",
        "provincia": "Madrid",
        "codigo_postal": "28901",
        "pais": "España"
      }
    },
    "transportista_efectivo": {
      "nombre": "Transportes Ejemplo SL",
      "nif": "B12345674",
      "direccion": {
        "empresa": "Transportes Ejemplo SL",
        "via": "Polígono Industrial, Nave 4",
        "localidad": "Valencia",
        "provincia": "Valencia",
        "codigo_postal": "46001",
        "pais": "España"
      }
    },
    "matricula_vehiculo": "1234ABC",
    "envios": [
      {
        "origen": {
          "via": "Calle Mayor 12",
          "localidad": "Getafe",
          "provincia": "Madrid",
          "codigo_postal": "28901",
          "pais": "España"
        },
        "destino": {
          "via": "Polígono Industrial, Nave 4",
          "localidad": "Valencia",
          "provincia": "Valencia",
          "codigo_postal": "46001",
          "pais": "España"
        },
        "mercancia": {
          "naturaleza": "Palets de material de construcción",
          "peso_kg": 8200,
          "bultos": 12
        },
        "fecha_efectiva_servicio": "2026-08-28"
      }
    ]
  },
  "ejecutado_por": "Nombre Apellido",
  "external_id": "PED-2026-0842"
}'

Python

Con la librería requests (pip install requests):

import requests

respuesta = requests.post(
    "https://decafacil.es/api/v1/deca",
    headers={"Authorization": "Bearer <tu-clave>"},
    json={
  "datos": {
    "cargador_contractual": {
      "nombre": "Cargas Ejemplo SA",
      "nif": "A76543214",
      "direccion": {
        "empresa": "Cargas Ejemplo SA",
        "via": "Calle Mayor 12",
        "localidad": "Getafe",
        "provincia": "Madrid",
        "codigo_postal": "28901",
        "pais": "España"
      }
    },
    "transportista_efectivo": {
      "nombre": "Transportes Ejemplo SL",
      "nif": "B12345674",
      "direccion": {
        "empresa": "Transportes Ejemplo SL",
        "via": "Polígono Industrial, Nave 4",
        "localidad": "Valencia",
        "provincia": "Valencia",
        "codigo_postal": "46001",
        "pais": "España"
      }
    },
    "matricula_vehiculo": "1234ABC",
    "envios": [
      {
        "origen": {
          "via": "Calle Mayor 12",
          "localidad": "Getafe",
          "provincia": "Madrid",
          "codigo_postal": "28901",
          "pais": "España"
        },
        "destino": {
          "via": "Polígono Industrial, Nave 4",
          "localidad": "Valencia",
          "provincia": "Valencia",
          "codigo_postal": "46001",
          "pais": "España"
        },
        "mercancia": {
          "naturaleza": "Palets de material de construcción",
          "peso_kg": 8200,
          "bultos": 12
        },
        "fecha_efectiva_servicio": "2026-08-28"
      }
    ]
  },
  "ejecutado_por": "Nombre Apellido",
  "external_id": "PED-2026-0842"
},
)
respuesta.raise_for_status()  # 201 si todo fue bien
print(respuesta.json())

Node.js

Con el fetch incluido en Node 18 y versiones posteriores, sin dependencias:

const respuesta = await fetch("https://decafacil.es/api/v1/deca", {
  method: "POST",
  headers: {
    Authorization: "Bearer <tu-clave>",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "datos": {
    "cargador_contractual": {
      "nombre": "Cargas Ejemplo SA",
      "nif": "A76543214",
      "direccion": {
        "empresa": "Cargas Ejemplo SA",
        "via": "Calle Mayor 12",
        "localidad": "Getafe",
        "provincia": "Madrid",
        "codigo_postal": "28901",
        "pais": "España"
      }
    },
    "transportista_efectivo": {
      "nombre": "Transportes Ejemplo SL",
      "nif": "B12345674",
      "direccion": {
        "empresa": "Transportes Ejemplo SL",
        "via": "Polígono Industrial, Nave 4",
        "localidad": "Valencia",
        "provincia": "Valencia",
        "codigo_postal": "46001",
        "pais": "España"
      }
    },
    "matricula_vehiculo": "1234ABC",
    "envios": [
      {
        "origen": {
          "via": "Calle Mayor 12",
          "localidad": "Getafe",
          "provincia": "Madrid",
          "codigo_postal": "28901",
          "pais": "España"
        },
        "destino": {
          "via": "Polígono Industrial, Nave 4",
          "localidad": "Valencia",
          "provincia": "Valencia",
          "codigo_postal": "46001",
          "pais": "España"
        },
        "mercancia": {
          "naturaleza": "Palets de material de construcción",
          "peso_kg": 8200,
          "bultos": 12
        },
        "fecha_efectiva_servicio": "2026-08-28"
      }
    ]
  },
  "ejecutado_por": "Nombre Apellido",
  "external_id": "PED-2026-0842"
}),
});

if (!respuesta.ok) {
  throw new Error(`Error ${respuesta.status}: ${await respuesta.text()}`);
}

console.log(await respuesta.json()); // 201 si todo fue bien

PHP

Con la extensión curl, incluida por defecto en la mayoría de instalaciones de PHP:

<?php
$datos = [
    "datos" => [
        "cargador_contractual" => [
            "nombre" => "Cargas Ejemplo SA",
            "nif" => "A76543214",
            "direccion" => [
                "empresa" => "Cargas Ejemplo SA",
                "via" => "Calle Mayor 12",
                "localidad" => "Getafe",
                "provincia" => "Madrid",
                "codigo_postal" => "28901",
                "pais" => "España",
            ],
        ],
        "transportista_efectivo" => [
            "nombre" => "Transportes Ejemplo SL",
            "nif" => "B12345674",
            "direccion" => [
                "empresa" => "Transportes Ejemplo SL",
                "via" => "Polígono Industrial, Nave 4",
                "localidad" => "Valencia",
                "provincia" => "Valencia",
                "codigo_postal" => "46001",
                "pais" => "España",
            ],
        ],
        "matricula_vehiculo" => "1234ABC",
        "envios" => [
            [
                "origen" => [
                    "via" => "Calle Mayor 12",
                    "localidad" => "Getafe",
                    "provincia" => "Madrid",
                    "codigo_postal" => "28901",
                    "pais" => "España",
                ],
                "destino" => [
                    "via" => "Polígono Industrial, Nave 4",
                    "localidad" => "Valencia",
                    "provincia" => "Valencia",
                    "codigo_postal" => "46001",
                    "pais" => "España",
                ],
                "mercancia" => [
                    "naturaleza" => "Palets de material de construcción",
                    "peso_kg" => 8200,
                    "bultos" => 12,
                ],
                "fecha_efectiva_servicio" => "2026-08-28",
            ],
        ],
    ],
    "ejecutado_por" => "Nombre Apellido",
    "external_id" => "PED-2026-0842",
];

$ch = curl_init("https://decafacil.es/api/v1/deca");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer <tu-clave>",
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => json_encode($datos),
]);

$respuesta = curl_exec($ch);
$codigo = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 201 si todo fue bien
curl_close($ch);

echo $respuesta;

Respuesta

Los cuatro ejemplos anteriores, si la clave y los datos son correctos, devuelven 201 Created con el mismo cuerpo:

{
  "id": 4213,
  "token": "a1b2c3d4e5f6",
  "url": "https://decafacil.es/d/a1b2c3d4e5f6",
  "n_version": 1,
  "external_id": "PED-2026-0842"
}

Documentación interactiva y colección Postman

Si prefieres explorar el esquema completo en vez de leerlo aquí: documentación interactiva (Swagger) — prueba cada operación desde el navegador con tu propia clave — o su equivalente en ReDoc. El esquema en bruto está en /api/v1/openapi.json (OpenAPI 3.1), por si tu herramienta genera un cliente a partir de él.

Para probar la API sin escribir nada: descarga la colección Postman (seis carpetas, en el orden natural de una integración: verificación, emitir, consultar, modificar, avisar/finalizar, anular). Trae una guarda de seguridad incorporada — bloquea sola cualquier ejecución si detecta que la clave no está en modo de pruebas, para que un «Run collection» sin pensar no emita DeCA reales.

Errores

Todos los errores de /api/v1 — validación de datos incluida — llevan la misma forma, con un código estable para que tu integración pueda distinguir un caso de otro sin depender del texto:

{"detail": {"code": "external_id_duplicado", "mensaje": "..."}}

El texto en mensaje ya viene traducido al español (incluidos los errores de validación de campos). Sin soporte de integración dedicado (ver condiciones), este mensaje es, en la práctica, tu primera línea de soporte.

Modo de pruebas

Al crear una clave en /claves-api eliges entre real y pruebas: con una clave de pruebas, los documentos que generes quedan marcados de forma visible en el PDF y no se cuentan como emisiones reales. Es el entorno recomendado para probar tu integración antes de pasar a una clave real — puedes tener las dos a la vez, cada una con su propio secreto.

Límites y buen uso

El canal aplica límites de frecuencia por clave; si los superas, la respuesta indica cuánto esperar antes de reintentar (cabecera Retry-After). Se aplica además la misma cláusula de uso razonable que rige el resto del servicio: un volumen claramente desproporcionado respecto al perfil de tu empresa puede dar lugar a que te contactemos.

Versionado y compatibilidad

/api/v1 es la única versión del canal por ahora, y la mantenemos estable: los cambios dentro de v1 son siempre aditivos — campos nuevos opcionales, operaciones nuevas — nunca un campo que desaparece o cambia de significado. Si alguna vez hiciera falta un cambio incompatible, se abriría como /api/v2 en paralelo, avisando con antelación a quien tenga clave activa, en vez de desactivar v1 de un día para otro.

Para que tu integración no dependa de detalles que sí pueden cambiar: programa siempre contra el code del error (sección anterior), nunca contra el texto de mensaje — ese texto puede mejorar con el tiempo sin que sea, en ningún caso, un cambio que rompa nada.

Condiciones

El uso de este canal se rige, además de por las condiciones generales del servicio, por el anexo de términos de la API: custodia de la clave, tarifa, alcance del soporte y ausencia de SLA. Se acepta al solicitar la clave, no antes.

Preguntas frecuentes

¿Esto sustituye a la aplicación web?

No. Es un canal alternativo para la misma cuenta: los DeCA que emitas por la API aparecen en tu cuenta igual que los que emitirías desde la PWA, con su propia marca de origen para que puedas distinguirlos si lo necesitas.

¿Puedo tener varias claves para la misma empresa?

Sí. Nada impide una clave por integración (oficina, almacén, un ERP y una herramienta de reporting, por ejemplo), todas ligadas a la misma empresa y revocables por separado.

Mi ERP es un servicio de un tercero (SaaS). ¿Quién responde de los datos ahí?

Ese proveedor es encargado del tratamiento de tu empresa, no de DeCAFacil — la relación con él, y su cumplimiento, es responsabilidad tuya. DeCAFacil solo recibe y procesa lo que tu integración le envía.

¿Cuánto cuesta?

La suscripción Premium (de la que forman parte las claves de API) tiene el precio y las condiciones actualizadas en la comparativa completa. Puedes activarla ya: no empezarás a pagar hasta enero de 2027, te avisaremos con preaviso razonable y nunca con carácter retroactivo — el detalle está en el anexo de términos de la API.

¿Cómo sé si un DeCA cambió después de emitirlo (por ejemplo, si alguien lo corrigió o lo finalizó por teléfono)?

De momento no hay webhooks: sondea GET /deca con modificado_desde (guarda el actualizado_en mayor que veas como valor para tu próxima consulta) combinado con estado — estado=finalizado te da los recién finalizados, y estado=emitido junto con n_version > 1 te da los corregidos en ruta (un n_version de 1 es una emisión nueva, no una corrección). El detalle exacto de los parámetros está en la documentación interactiva.

¿Tienes ya cuenta en DeCAFacil?

Activa la suscripción y crea tu clave tú mismo desde «Mis claves de API», sin esperar a que te contestemos.

Activar suscripción →

Seguir leyendo

Emitir el DeCA gratis con DeCAFacilCómo funciona la aplicación web y qué incluye el plan gratuito.
Qué datos lleva el DeCALos ocho apartados del artículo 6, uno a uno — el contenido que también genera esta API.
DeCA obligatorio en 2026A quién afecta, qué transportes quedan fuera y qué cambia.

Esta página describe el estado actual del canal de API, en evolución. Si algo no coincide con lo que ves al integrarlo, escríbenos y lo corregimos.