Documento de control (DeCA) y peso de transporte

Desde el 5 de octubre de 2026 el documento de control administrativo del transporte público de mercancías por carretera tiene que ser digital. La API pública ya lo emite: un PDF por versión, servido desde una URL pública permanente cuyo código QR viaja con el conductor, con el historial que necesita la inspección. Todo es aditivo; ningún campo existente cambia de significado. Consulta la guía del documento de control.

Nuevo recurso transport_documents

Scopes nuevos: transport_documents:read, transport_documents:write, transport_documents:delete y transport_documents:transition, también concedibles por OAuth. El PDF de cada versión exige pdfs:read; el justificante de emisión, transport_documents:read, porque contiene el registro de emisión. El módulo transport_documents requiere delivery_notes.

MCP, eventos y errores

• 15 tools MCP, una por operación salvo el código QR y el justificante de emisión, que siguen siendo descargas binarias de la REST API. search_transport_documents admite el mismo q y el mismo sort que el listado REST, y create_transport_document no admite id. Consulta el catálogo de tools.
• 10 eventos: transport_document.created, .updated, .issued, .modified, .closed (con close_mode manual o automático), .reopened, .cancelled, .superseded, .email_sent y .email_failed. Mientras un documento es un borrador, sus partes siguen los cambios del contacto enlazado y de los datos de tu empresa, y cada refresco que cambia algo publica .updated. Consulta Eventos.
• 24 códigos de error: los 22 de la nueva categoría «Transport Documents», desde transport_document_not_issuable (con error.details.missing) hasta transport_document_version_limit_reached, transport_document_pdf_too_large y transport_document_version_not_found (404 ante un ?version=N que el PDF no tiene), más invalid_gross_weight (también en las líneas de mercancía de un documento) y gross_weight_not_allowed en Productos. Consulta el catálogo de errores.

Límites e identificadores

• Un documento tiene como máximo 50 versiones, y la última se reserva para anularlo o sustituirlo; cuando ya tiene 49, modify devuelve 422 transport_document_version_limit_reached.
• Cada versión es un PDF de hasta 5 MB (5.000.000 bytes). Emitir, modificar, anular y sustituir devuelven 422 transport_document_pdf_too_large sin guardar nada cuando el PDF sería mayor.
• El id de un documento lo genera el servidor. shipments[].id es opcional: al crear, uno que ya está en uso devuelve 422 en shipments.N.id; al actualizar y modificar, solo identifica un envío de ese documento. Una escritura simultánea que choca en un identificador devuelve 409 resource_conflict y se puede reintentar. Los UUID se normalizan a minúsculas.
• Al crear, un envío que omite origin toma tu lugar de carga por defecto o tu domicilio fiscal; un "origin": null explícito lo deja sin origen.
• La URL pública se limita por token y prefijo de red (60 por minuto por defecto) y por token (600 por minuto por defecto), nunca solo por IP; los tokens desconocidos cuentan por prefijo de red. El PDF público no muestra quién hizo cada versión.

Peso bruto de transporte en el catálogo y en los albaranes

• Los productos, las variantes y las presentaciones fijas aceptan gross_weight_kg al crear y actualizar, y lo publican al leer: kg por unidad base en productos y variantes y por unidad comercial en presentaciones. Omitirlo al actualizar conserva el valor actual y null lo borra. Los servicios, las unidades base de masa (KGM, GRM) y las presentaciones variable_measure lo rechazan con gross_weight_not_allowed.
• Las líneas de albarán congelan su peso al crearse o editarse en borrador y lo publican como gross_weight_kg; el albarán añade total_gross_weight_kg y lines_without_weight_count.
• Las series aceptan el nuevo tipo transport_document (código por defecto DC), cuya serie se crea en la primera emisión. GET /v1/series/stats lo cuenta.