Integración por API
Integra el DeCA en tu ERP o TMS con nuestra API
Si los portes ya nacen en tu ERP o tu TMS, no hace falta teclearlos otra vez. Con la API REST de Porte al Día creas el envío, emites el DeCA y te llevas el PDF con su QR sin salir de tu sistema. Aquí tienes lo que hace hoy, cómo se usa y lo que todavía no hace.
Última revisión:
Qué puedes automatizar
La API cubre el ciclo completo del documento, del borrador al archivo. Todo vive bajo /v1:
- Envíos: crear y actualizar borradores, validarlos, clasificar el ámbito del transporte, declarar una exención, asignar conductor, registrar el inicio y el fin del servicio, cancelarlo, repetir un porte y ver una vista previa del PDF antes de emitir.
- Emisión: emitir el DeCA y recibir en la respuesta la URL de inspección, la huella SHA-256 del PDF y su tamaño.
- Documentos: listarlos, consultarlos con su cadena de versiones, descargar el PDF vigente o el de cualquier versión anterior, ver su auditoría, modificarlos (versión nueva con PDF, dirección y QR nuevos) y anularlos con motivo.
- Entregas: ver a quién se envió cada versión, por qué canal y si falló, reintentar una entrega y compartir el documento con la otra parte.
- Datos maestros y control: cargadores y transportistas, vehículos, incidencias, el resumen del día y el registro de auditoría.
Cada clave actúa con un rol: tráfico, que crea, emite, modifica y entrega, o consulta, que solo lee. Los detalles de cada llamada están en la referencia de la API, en formato OpenAPI.
Sin duplicados aunque tu ERP reintente
Las redes fallan y los ERP reintentan. La API está pensada para que repetir una llamada nunca te deje dos DeCA del mismo porte:
- Referencia de tu ERP. Si mandas el número de pedido en
externalId, crear el mismo envío otra vez devuelve el que ya existe: código 200 y"created": false, en lugar de 201. -
Cabecera
Idempotency-Key. La creación y la emisión la aceptan. Repetir la misma petición con la misma clave devuelve la misma respuesta, con la cabeceraIdempotent-Replayed: true. Reutilizar la clave con otro contenido da un error 422. - Una sola emisión por envío. Si vuelves a emitir un envío ya emitido, recibes un 409 y ningún documento nuevo. Y un envío solo cuenta como emitido cuando su PDF está generado, guardado y verificado: si algo falla por el camino, sigue en borrador y el reintento lo emite una vez.
- Sin pisarse. Cada actualización lleva en
expectedVersionla versión que leíste. Si alguien cambió el envío entretanto, la API responde 409 en lugar de sobrescribirlo.
Cómo funciona en 3 llamadas
Necesitas una clave de API, que un propietario o administrador crea en los ajustes de la
aplicación. En los ejemplos va en la variable $PORTE_API_KEY. Los datos son
ficticios y las respuestas están recortadas.
Antes de nada, da de alta una vez al cargador contractual y al transportista efectivo. Guarda
sus partyId y reutilízalos en cada envío:
curl -X POST https://api.portealdia.es/v1/parties \
-H "Authorization: Bearer $PORTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Distribuciones Ejemplo S.L.",
"taxId": {
"country": "ES",
"value": "B12345674"
},
"address": {
"street": "Calle Mayor 1",
"postalCode": "28013",
"locality": "Madrid",
"province": "Madrid",
"country": "ES"
}
}' HTTP/1.1 201 Created
{
"partyId": "0199b8a2-41c6-7a3e-9d10-6f2b8c4e1a07",
"needsReview": false
} 1. Crea el envío con la referencia de tu ERP
curl -X POST https://api.portealdia.es/v1/shipments \
-H "Authorization: Bearer $PORTE_API_KEY" \
-H "Idempotency-Key: crear-PED-2026-004512" \
-H "Content-Type: application/json" \
-d '{
"externalId": "PED-2026-004512",
"data": {
"contractualShipperId": "0199b8a2-41c6-7a3e-9d10-6f2b8c4e1a07",
"effectiveCarrierId": "0199b8a2-4a90-7f15-8c2d-3e7a1b9d5c42",
"origin": {
"street": "Polígono Industrial Norte, nave 7",
"postalCode": "46100",
"locality": "Burjassot",
"province": "Valencia",
"country": "ES"
},
"destination": {
"street": "Avenida de la Industria 12",
"postalCode": "28108",
"locality": "Alcobendas",
"province": "Madrid",
"country": "ES"
},
"goods": {
"description": "Palés de agua mineral embotellada",
"packages": {
"count": 24,
"kind": "pallets"
}
},
"weight": {
"value": 12500,
"unit": "kg",
"determination": "exact"
},
"specialAuthorization": {
"applies": false
},
"transportDate": "2026-10-07",
"vehicles": {
"configuration": "articulated",
"tractorPlate": {
"value": "1234BCD"
},
"trailerPlate": {
"value": "R5678BBC"
}
}
}
}' HTTP/1.1 201 Created
{
"shipmentId": "0199b8a3-0b7e-7c41-a5f3-9d2e6c8b1f30",
"version": 1,
"created": true
} 2. Indica el ámbito del transporte
Antes de emitir hay que dejar constancia de que el porte es nacional (o cabotaje), con su motivo y la versión del envío que acabas de recibir. Sin este paso, la emisión responde con un error que te lo pide.
curl -X POST https://api.portealdia.es/v1/shipments/0199b8a3-0b7e-7c41-a5f3-9d2e6c8b1f30/classify \
-H "Authorization: Bearer $PORTE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"expectedVersion": 1,
"decision": {
"kind": "manual",
"scope": "domestic",
"reason": "Origen y destino en España"
}
}' HTTP/1.1 200 OK
{
"shipmentId": "0199b8a3-0b7e-7c41-a5f3-9d2e6c8b1f30",
"version": 2,
"scope": "domestic",
"source": "manual"
}
Si quieres comprobarlo todo antes de emitir, validate te devuelve lo que falta o no
cuadra, campo a campo:
curl -X POST https://api.portealdia.es/v1/shipments/0199b8a3-0b7e-7c41-a5f3-9d2e6c8b1f30/validate \
-H "Authorization: Bearer $PORTE_API_KEY" HTTP/1.1 200 OK
{
"valid": true,
"violations": [],
"warnings": [],
"coverage": {
"covered": true
}
} 3. Emite el DeCA
curl -X POST https://api.portealdia.es/v1/shipments/0199b8a3-0b7e-7c41-a5f3-9d2e6c8b1f30/issue \
-H "Authorization: Bearer $PORTE_API_KEY" \
-H "Idempotency-Key: emitir-PED-2026-004512" HTTP/1.1 201 Created
{
"documentId": "0199b8a3-2d14-7e88-b0c6-1a5f9e3d7b62",
"versionId": "0199b8a3-2d15-7a02-9e4b-8c3f6d1a2e95",
"versionNumber": 1,
"inspectionUrl": "https://v.portealdia.es/d/q7Zr2xW9bT4mK8vN1cP5sJ3hL6yF0dA2eG7uR9iO4wX",
"sha256": "5c1e9a7b3f0d84e2c6a9b1d7f3e05a8c2b4d6e9f1a3c5b7d9e0f2a4c6b8d0e1f",
"bytes": 33871,
"warnings": [],
"replayed": false
} inspectionUrl es la dirección que lleva el QR: la que abre la inspección para
descargar el PDF. Y para llevarte el PDF a tu sistema:
curl https://api.portealdia.es/v1/documents/0199b8a3-2d14-7e88-b0c6-1a5f9e3d7b62/pdf \
-H "Authorization: Bearer $PORTE_API_KEY" \
-o DeCA-PED-2026-004512.pdf
La respuesta lleva la cabecera ETag con la misma huella SHA-256 que te dio la
emisión, así que puedes comprobar que el archivo es el original. Para ver cómo es, mira el ejemplo de DeCA en PDF.
Seguridad
- Cada clave pertenece a una empresa y solo ve los datos de esa empresa. Los de cada cliente están separados de los de los demás.
- Solo un propietario o un administrador con verificación en dos pasos puede crear o revocar claves. La clave completa se muestra una sola vez, al crearla: nosotros guardamos solo su huella SHA-256.
- Una clave nunca puede hacer tareas de administración: no gestiona el equipo, la facturación, las exportaciones, las retenciones legales ni otras claves.
-
Va en la cabecera
Authorization: Bearer(o enx-api-key), siempre por HTTPS, y no se escribe en nuestros registros. - Si la suscripción deja de estar activa, las claves quedan en pausa. Tus documentos, sus QR y el archivo siguen disponibles en la aplicación web.
Errores claros en español
Los errores siguen el formato estándar RFC 9457 (application/problem+json). Cada
uno trae un código estable para tu programa y un mensaje en español para quien lo lea. Si faltan
datos, la lista te dice qué campo es y qué le pasa, como en este intento de emitir un borrador
incompleto:
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/problem+json; charset=utf-8
{
"type": "urn:deca:problem:validation.failed",
"title": "Datos no válidos",
"status": 422,
"detail": "Revisa los datos: hay campos obligatorios ausentes o no válidos.",
"code": "validation.failed",
"instance": "/v1/shipments/0199b8a3-0b7e-7c41-a5f3-9d2e6c8b1f30/issue",
"errors": [
{
"code": "party.required",
"path": "effectiveCarrier",
"message": "Transportista efectivo: selecciona la parte con nombre, NIF y domicilio completos."
},
{
"code": "field.required",
"path": "goods.description",
"message": "Naturaleza de la mercancía: dato obligatorio."
},
{
"code": "field.required",
"path": "transportDate",
"message": "Fecha de realización del transporte: dato obligatorio."
}
]
} Los mismos mensajes que ve tráfico en la aplicación los recibe tu ERP, así que puedes enseñárselos tal cual a quien tenga que corregir el pedido.
Lo que todavía no hace
Antes de planificar la integración, conviene que sepas dónde están los límites:
- No hay webhooks. La API no avisa a tu sistema cuando algo cambia: tu ERP consulta el estado de cada envío o documento cuando lo necesita.
- No hay entorno de pruebas ni claves de test. Puedes probarla en el periodo gratuito, pero lo que emitas allí es un documento real.
- No hay SDK ni conectores listos para ningún ERP o TMS. Conectarla requiere desarrollo, tuyo o de tu proveedor.
- Las claves no caducan ni rotan solas. Si quieres cambiar una, creas otra y revocas la anterior a mano.
- Los permisos van por rol (tráfico o consulta), no por operación.
- No hay un acuerdo de nivel de servicio (SLA) firmado para la API.
- Los cambios en ruta se hacen siempre con una versión nueva del documento, con dirección y QR nuevos. Te lo contamos en cómo modificar el DeCA.
Plan Business y límites
- Precio: 249 €/mes + IVA, sin permanencia.
- Documentos nuevos al mes: hasta 10.000. Las modificaciones no cuentan y nunca se bloquean.
- Usuarios: hasta 100.
- Peticiones: 300 por minuto y clave.
Las cabeceras
x-ratelimit-limit,x-ratelimit-remainingyx-ratelimit-resette dicen cuánto te queda; si te pasas, recibes un 429. - Listados: paginados por cursor, hasta 200 elementos por página.
IVA (21 %) no incluido; se añade en la factura. Si llegas al límite del mes, lo que se para es la emisión de documentos nuevos; los
ya emitidos, sus QR y el archivo siguen funcionando. Puedes consultar tu consumo en GET /v1/billing. ¿Más de 10.000 documentos al
mes? Escríbenos a hola@portealdia.es.
Si te das de alta hasta el 15 de diciembre de 2026, usas Porte al Día gratis hasta el 1 de enero de 2027 con las funciones del plan Business, API incluida, y hasta 200 DeCA nuevos al mes. Sin tarjeta. Condiciones completas en precios.
Preguntas frecuentes
¿Qué plan incluye la API?
El plan Business, con hasta 10.000 documentos nuevos al mes. Starter y Pro no la incluyen: si eliges uno de ellos, tus claves se conservan, pero quedan en pausa hasta que pases a Business. El periodo gratuito también incluye la API, así que puedes probar la integración antes de pagar.
¿Qué pasa si mi ERP envía el mismo porte dos veces?
No se duplica. Si el envío lleva la referencia de tu ERP en externalId, la segunda llamada devuelve el envío que ya existe (código 200 en lugar de 201). Con la cabecera Idempotency-Key, repetir la misma petición devuelve la misma respuesta. Y un envío emitido no se puede volver a emitir: nunca se genera un segundo documento.
¿Hay webhooks o un entorno de pruebas?
Todavía no. La API no avisa a tu sistema cuando algo cambia: es tu ERP el que consulta el estado cuando lo necesita. Tampoco hay sandbox ni claves de prueba; para probar la integración usa el periodo gratuito, sabiendo que lo que emitas allí es un documento real.
¿Tengo que enviar algo al Ministerio?
No. El DeCA no se envía al Ministerio ni a ningún registro: el PDF queda guardado en Porte al Día y la inspección lo descarga con el QR. La API tampoco transmite nada a la Administración.