Factuarea APIDevelopers
Support
Open app

Modify an issued transport document

Modify an issued transport document during the service (method 1 of the Resolution of 5 June 2026): same number, same URL and same QR.

  • Send the changed data plus reason (3–500 characters) and data_origin (company or carrier_reported).
  • The parties cannot change (422 transport_document_parties_immutable: cancel and issue a new one) and a request that changes nothing returns 422 transport_document_no_changes.
  • A document has at most 50 versions and the last one is reserved for cancelling or superseding, so the 49th modification returns 422 transport_document_version_limit_reached (issue a new document and mark this one as superseded); a PDF over 5 MB returns 422 transport_document_pdf_too_large; a goods line with an impossible weight, 422 invalid_gross_weight; a shipments[].id of another document, 422 on shipments.N.id; and a concurrent write that collides on an identifier, 409 resource_conflict (retryable, nothing saved).
  • If the result lacks minimum data it returns 422 transport_document_cannot_be_modified with error.details.missing (same vocabulary as issuing).
  • It stores a new full PDF version that keeps the original creation date and lists the data that is no longer valid.
  • Irreversible: requires Idempotency-Key.
  • Send the modified PDF to the driver.
POST
/transport_documents/{transport_document}/modify

Authorization

AuthorizationBearer <token>

In: header

Path Parameters

transport_document*string

Headers

Idempotency-Key*string

Client-generated opaque key (up to 255 characters; UUID v7 recommended) that makes retries safe: the first response is cached and replayed for repeats without re-executing the mutation. Reusing a key with a different body returns 409 idempotency_key_reused. See the Idempotency guide. Required on this operation: repeating it delivers an effect that cannot be taken back (an email sent, a file generated, a third-party call, a charge), so a request without this header is rejected with 422 idempotency_key_required before any business logic runs.

Length1 <= length <= 255
Factuarea-Version?string

Pin the API version (YYYY-MM-DD, Stripe-style date versioning) for this request; omit to use the key's pinned version, or the latest if none. Unsupported version → 400 unsupported_api_version; malformed → 400 parameter_invalid_format. The effective version is echoed in the Factuarea-Version response header. See the Versioning guide.

Formatdate
X-Active-Profile?string

Operate on behalf of a child company (gestoría master key): pass its public id (UUID v7) and the request runs against that child's data without changing the key's scope, tier or environment (omit to use the key's own company). Invalid UUID → 400 parameter_invalid_uuid; unknown or non-owned id → 404 profile_not_found. See the Acting on behalf guide.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

Previous/v1/transport_documents/{transport_document}/issue
POST

Issue a transport document

Issue a draft transport document. It checks the minimum data (shipper name, tax ID and full address; carrier name and tax ID; at least one shipment with origin, destination, goods and declared measure; tractor plate; transport date), that every origin and destination is in Spain and that every transport date is today or later (Europe/Madrid). In a single atomic operation it assigns the next number of the DC series and the permanent public URL, renders and stores version 1 of the PDF with its sha256, and moves the document to issued. Missing data returns 422 transport_document_not_issuable…

Next/v1/transport_documents/{transport_document}/reopen
POST

Reopen a transport document

Reopen a manually closed transport document with a reason (3–500 characters). It returns to issued without creating a version. Allowed only before the automatic-close deadline and never after an automatic close; otherwise 422 transport_document_cannot_be_reopened.