API de DeCA Profesional

Para qué sirve

La API está pensada para empresas de transporte y cargadores que ya gestionan sus pedidos o expediciones en un ERP o TMS y quieren que el DeCA se genere solo, sin volver a teclear datos.

El acceso a la API es un complemento de pago del plan Business (49,95 €/mes + IVA) para integraciones ERP/TMS. Los DeCA creados por la API cuentan en el mismo cupo mensual del plan que los creados desde el panel.

Primeros pasos

1. Solicita el acceso escribiendo a integraciones@praetoriaabogados.es o activa el complemento API desde Plan y facturación si ya tienes el plan Business.
2. Recibe tus credenciales: te enviamos una clave por integración (por ejemplo, una para tu ERP), con los permisos que necesite. La clave completa solo se muestra una vez.
3. Prueba la conexión con GET /api/v1/me.
4. Valida un DeCA con POST /api/v1/decas/validate: no crea nada ni consume cupo.
5. Crea tu primer DeCA con POST /api/v1/decas y guarda la URL de verificación.

curl https://decaprofesional.es/api/v1/me \
  -H "Authorization: Bearer $DECA_API_KEY"

Autenticación

Cada petición lleva la clave de la integración en la cabecera Authorization. Solo HTTPS; no envíes nunca la clave en la URL ni la incluyas en código que se ejecute en el navegador.

Authorization: Bearer fvd_live_<id-de-la-clave>_<secreto>

La empresa siempre es la de la credencial: ningún campo de la petición (NIF, identificadores) cambia de empresa. Si pierdes una clave no se puede recuperar: pide una nueva o su rotación. Todo lo que tu credencial no puede ver responde 404.

Endpoints

Crear un DeCA

El cuerpo describe el transporte: fechas, vehículo, cargador contractual (shipper), transportista efectivo (carrier) y de 1 a 20 envíos. Los países van siempre en código ISO de dos letras (ES, FR, PT…). Los campos desconocidos se rechazan.

curl -X POST https://decaprofesional.es/api/v1/decas \
  -H "Authorization: Bearer $DECA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @deca.json

{
  "externalId": "TR-45882",
  "reference": "Pedido 88231",
  "loadDate": "2026-10-06",
  "unloadDate": "2026-10-07",
  "vehicle": {
    "tractorPlate": "1234 KLM",
    "trailerPlate": "R-5678-BBC"
  },
  "shipper": {
    "name": "CERÁMICAS DEL MEDITERRÁNEO S.A.",
    "taxId": "A12345674",
    "country": "ES",
    "address": "Carretera de Alcora km 3",
    "postalCode": "12006",
    "city": "Castellón de la Plana"
  },
  "carrier": "self",
  "shipments": [
    {
      "loadLocation": {
        "name": "Planta 1",
        "address": "Carretera de Alcora km 3",
        "postalCode": "12006",
        "city": "Castellón de la Plana",
        "province": "Castellón",
        "country": "ES"
      },
      "unloadLocation": {
        "name": "Entrepôt Lyon Sud",
        "address": "12 Rue du Port",
        "postalCode": "69007",
        "city": "Lyon",
        "country": "FR"
      },
      "goods": "Azulejo cerámico en palés",
      "weight": 18400,
      "recipient": "Céramique Rhône SARL"
    }
  ]
}

Respuesta 201 Created con la cabecera Location: /api/v1/decas/{id}:

{
  "id": "cmg4x2k9a0001l508h3n7q2rz",
  "reference": "DECA-Q3VJ9KXA",
  "externalId": "TR-45882",
  "status": "active",
  "availability": "public",
  "version": 1,
  "createdAt": "2026-10-05T07:41:12.384Z",
  "updatedAt": "2026-10-05T07:41:12.384Z",
  "annulledAt": null,
  "serviceType": "goods",
  "servicePeriod": {
    "start": "2026-10-06",
    "end": "2026-10-07",
    "publicUntil": "2026-10-14"
  },
  "verification": {
    "url": "https://decaprofesional.es/d/q3vj9kxa7Rm2…",
    "note": "La URL cambia con cada corrección: imprime o envía siempre la última."
  },
  "pdf": {
    "href": "/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/pdf",
    "sha256": "9f2c4e…",
    "contentType": "application/pdf"
  },
  "data": {
    "reference": "Pedido 88231",
    "notes": null,
    "loadDate": "2026-10-06",
    "unloadDate": "2026-10-07",
    "vehicle": {
      "tractorPlate": "1234KLM",
      "trailerPlate": "R5678BBC"
    },
    "shipper": {
      "name": "CERÁMICAS DEL MEDITERRÁNEO S.A.",
      "taxId": "A12345674",
      "country": "ES",
      "address": "Carretera de Alcora km 3",
      "postalCode": "12006",
      "city": "Castellón de la Plana"
    },
    "carrier": {
      "name": "TRANSPORTES EJEMPLO S.L.",
      "taxId": "B12345674",
      "country": null,
      "address": "Polígono Industrial 5",
      "postalCode": "46540",
      "city": "El Puig"
    },
    "shipments": [
      {
        "loadLocation": {
          "name": "Planta 1",
          "address": "Carretera de Alcora km 3",
          "postalCode": "12006",
          "city": "Castellón de la Plana",
          "province": "Castellón",
          "country": "ES",
          "countryName": "España"
        },
        "unloadLocation": {
          "name": "Entrepôt Lyon Sud",
          "address": "12 Rue du Port",
          "postalCode": "69007",
          "city": "Lyon",
          "province": null,
          "country": "FR",
          "countryName": "Francia"
        },
        "goods": "Azulejo cerámico en palés",
        "weight": "18.400 kg",
        "recipient": "Céramique Rhône SARL",
        "loadDate": "2026-10-06",
        "unloadDate": "2026-10-07"
      }
    ],
    "totalWeight": "18.400 kg"
  },
  "warnings": [],
  "links": {
    "self": "/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz",
    "status": "/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/status",
    "versions": "/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/versions",
    "pdf": "/api/v1/decas/cmg4x2k9a0001l508h3n7q2rz/pdf"
  }
}

warnings recoge avisos que no impiden crear el DeCA (por ejemplo, un NIF con un formato poco habitual). availability indica si la URL pública está disponible (public), ya caducó (expired) o el DeCA está anulado (annulled).

Idempotency-Key y externalId

Idempotency-Key (cabecera, obligatoria al crear y corregir): una cadena única por operación, por ejemplo un UUID (8–255 caracteres). Si repites la misma llamada con la misma clave y el mismo cuerpo —por un corte de red o un reintento—, recibes el mismo DeCA con 200 y la cabecera Idempotent-Replayed: true; nunca se crea un segundo documento. La misma clave con un cuerpo distinto responde 409 idempotency_conflict.

externalId (cuerpo): el identificador de tu objeto de negocio. Si ya existe un DeCA activo con ese externalId, la API responde 409 duplicate_external_id con el existingId. Puedes buscarlo con GET /api/v1/decas?externalId=…. Un DeCA anulado libera su externalId.

Validar sin crear

POST /api/v1/decas/validate acepta el mismo cuerpo que la creación y aplica exactamente las mismas reglas, pero no crea ningún DeCA, no genera PDF y no consume el cupo del plan. Úsalo para probar tu integración y para comprobar los datos antes de emitir.

{
  "valid": true,
  "warnings": []
}

“self”: tu propia empresa

En shipper o carrier puedes enviar el texto "self" en lugar de los datos de la empresa: se usan los datos de la empresa de la credencial tal como figuran en su ficha de DeCA Profesional. Si la ficha está incompleta, la respuesta es 422 con el detalle self_company_incomplete.

PDF, QR y URL de verificación

Cada DeCA tiene una URL pública de verificación (verification.url): es la que codifica el QR impreso en el PDF y la que se muestra en una inspección, sin necesidad de cuenta. El PDF se descarga con tu credencial en GET /api/v1/decas/{id}/pdf (o ?version=N); la cabecera X-Pdf-Sha256 permite comprobar su integridad. La URL pública está disponible durante el servicio y los 7 días siguientes (servicePeriod.publicUntil).

curl https://decaprofesional.es/api/v1/decas/<id>/pdf \
  -H "Authorization: Bearer $DECA_API_KEY" -o deca.pdf

Correcciones

Una corrección sustituye todos los datos del DeCA y crea una nueva versión con nueva URL de verificación, nuevo QR y nuevo PDF. Las versiones anteriores se conservan (GET /versions). Imprime o envía siempre la última URL. El externalId no se puede cambiar y un DeCA anulado no se puede corregir. Responde 201 con el DeCA en su nueva versión (200 si es un reintento con la misma Idempotency-Key).

{
  "changeReason": "Cambio de matrícula del remolque",
  "deca": "…el mismo cuerpo completo que al crear…"
}

Anulación

La anulación es definitiva: la URL pública pasa a mostrar que el documento está anulado y el QR sigue resolviendo a ese aviso. Repetir la llamada devuelve 200 sin cambios. El motivo es obligatorio (3–500 caracteres).

{
  "reason": "Pedido cancelado por el cliente"
}

Permisos (scopes)

Cada credencial tiene solo los permisos que necesita su integración.

Límites

• 60 peticiones por minuto por credencial (cabeceras X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset).
• Un techo técnico diario de creación por credencial (5000 DeCA) y un bloqueo temporal tras varios intentos de autenticación fallidos.
• Cuerpo de hasta 256 KB y hasta 20 envíos por DeCA.
• El cupo mensual de DeCA es el de tu plan; GET /api/v1/me indica el uso y lo que queda.
• Al superar un límite recibes 429 con Retry-After: espera y reintenta.

Errores

Todos los errores tienen el mismo formato. code es estable y es lo que debe leer tu integración; message es informativo. Si contactas con soporte, indica el requestId.

{
  "error": {
    "code": "validation",
    "message": "El DeCA no cumple los requisitos obligatorios.",
    "requestId": "req_7f3a9c…",
    "details": [
      {
        "path": "/shipments/0/unloadLocation/country",
        "code": "invalid_country",
        "message": "Usa un código de país ISO 3166-1 alfa-2 (p. ej. ES, FR, PT)"
      }
    ]
  }
}

Preguntas frecuentes

Soporte para integraciones