---
title: "Mark a transport document as superseded"
method: POST
path: "/companies/{company}/transport-documents/{transport_document}/supersede"
tags: ["Transport Documents"]
---

# Mark a transport document as superseded

`POST /companies/{company}/transport-documents/{transport_document}/supersede`

## Request

- Base URL: `https://api.factuarea.com/v1`
- URL: `https://api.factuarea.com/v1/companies/{company}/transport-documents/{transport_document}/supersede`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Mark an `issued` transport document as superseded by the carrier's own document; it becomes terminal (`superseded`).
- Send `reference` (1-300 characters) and `reason`. A PDF over 5 MB returns 422 `transport_document_pdf_too_large`.
- Irreversible: requires `Idempotency-Key`.

## Path parameters

- `company` string, uuid, required
- `transport_document` string, uuid, required

## Headers

- `Idempotency-Key` string, required
- `Factuarea-Version` string, date

## Request body

- SupersedeTransportDocumentRequest: Mark an issued transport document as superseded by the carrier document. Required: `reference` (1-300 characters, e.g. its number or URL) and `reason` (3-500 characters).
  - `reference` string, required
  - `reason` string, required

## Response `200`

- object
  - `data` TransportDocument, required: A transport control document (DeCA, Spanish electronic administrative control document for road freight transport, Orden FOM/2861/2012). Each issued version is an immutable PDF served from a permanent public URL whose QR code travels with the driver.
    - `id` string, uuid, required: Transport document ID (UUID v7).
    - `object` 'transport_document', required
    - `number` string, nullable, required: Number of the `DC` series, assigned when issuing with the numbering format of the series (by default code, year and a 3-digit sequence); `null` in `draft`.
    - `status` 'draft' | 'issued' | 'closed' | 'cancelled' | 'superseded', required
    - `company_role` 'shipper' | 'carrier', required: Role of your company: contractual shipper or effective carrier.
    - `public_url` string, uri, nullable, required: Permanent public URL encoded in the QR code; it serves the current version PDF directly to the inspection. `null` in `draft`.
    - `current_version` integer, nullable, required: Number of the current version; `null` in `draft`.
    - `shipper` TransportDocumentParty, required: Contractual shipper or effective carrier of a transport control document.
      - `name` string, required
      - `tax_id` string, nullable, required: Tax ID: a Spanish NIF, NIE or CIF (checked with its control character) or a foreign identifier of 2 to 20 alphanumeric characters (`tax_id_country` other than `ES`, e.g. cabotage).
      - `tax_id_country` string, nullable, required: ISO 3166-1 alpha-2 country of the tax ID.
      - `address` TransportAddress, required: Address of a party, origin or destination of a transport control document.
        - `line` string, required: Street and number.
        - `postal_code` string, required: Postal code (5 digits in Spain).
        - `city` string, required
        - `province` string, nullable, required
        - `country` string, required: ISO 3166-1 alpha-2 country code. Origin and destination must be `ES` to issue.
        - `name` string, nullable, required: Who is at that address (loading place or consignee), printed on the PDF. `null` on the addresses of the parties.
      - `contact_id` string, uuid, nullable, required: Contact (UUID v7) the party was copied from, or `null` when it was typed by hand or is your own company.
    - `carrier` TransportDocumentParty, required: Contractual shipper or effective carrier of a transport control document.
      - `name` string, required
      - `tax_id` string, nullable, required: Tax ID: a Spanish NIF, NIE or CIF (checked with its control character) or a foreign identifier of 2 to 20 alphanumeric characters (`tax_id_country` other than `ES`, e.g. cabotage).
      - `tax_id_country` string, nullable, required: ISO 3166-1 alpha-2 country of the tax ID.
      - `address` TransportAddress, required: Address of a party, origin or destination of a transport control document.
        - `line` string, required: Street and number.
        - `postal_code` string, required: Postal code (5 digits in Spain).
        - `city` string, required
        - `province` string, nullable, required
        - `country` string, required: ISO 3166-1 alpha-2 country code. Origin and destination must be `ES` to issue.
        - `name` string, nullable, required: Who is at that address (loading place or consignee), printed on the PDF. `null` on the addresses of the parties.
      - `contact_id` string, uuid, nullable, required: Contact (UUID v7) the party was copied from, or `null` when it was typed by hand or is your own company.
    - `vehicle` object, required
      - `tractor_plate` string, nullable, required: Plate of the tractor or rigid vehicle (required to issue).
      - `tractor_plate_country` string, nullable, required
      - `trailer_plate` string, nullable, required: Plate of the trailer or semi-trailer.
      - `trailer_plate_country` string, nullable, required
    - `special_authorization` string, nullable, required: Special traffic authorization, when there is one.
    - `transport_date` string, date, nullable, required: Transport date of the document, inherited by the shipments without their own date. It must be today or later (Europe/Madrid) to issue.
    - `observations` string, nullable, required
    - `shipments` TransportDocumentShipment[], required
      - `id` string, uuid, required: Shipment ID (UUID v7).
      - `origin` TransportAddress, required: Address of a party, origin or destination of a transport control document.
        - `line` string, required: Street and number.
        - `postal_code` string, required: Postal code (5 digits in Spain).
        - `city` string, required
        - `province` string, nullable, required
        - `country` string, required: ISO 3166-1 alpha-2 country code. Origin and destination must be `ES` to issue.
        - `name` string, nullable, required: Who is at that address (loading place or consignee), printed on the PDF. `null` on the addresses of the parties.
      - `destination` TransportAddress, required: Address of a party, origin or destination of a transport control document.
        - `line` string, required: Street and number.
        - `postal_code` string, required: Postal code (5 digits in Spain).
        - `city` string, required
        - `province` string, nullable, required
        - `country` string, required: ISO 3166-1 alpha-2 country code. Origin and destination must be `ES` to issue.
        - `name` string, nullable, required: Who is at that address (loading place or consignee), printed on the PDF. `null` on the addresses of the parties.
      - `transport_date` string, date, nullable, required: Own transport date; `null` inherits the document `transport_date`.
      - `goods` object[], required: Goods lines, without prices.
        - `description` string, required: Concept of the goods.
        - `additional_description` string, nullable, required: Optional secondary description printed below the concept.
        - `quantity` string, nullable, required: Visible quantity (decimal string).
        - `unit` string, nullable, required
        - `gross_weight_kg` string, nullable, required: Gross weight in kg PER UNIT (decimal string, scale 4), or `null` when unknown.
      - `declared_measure` object, nullable, required: Declared measure of the shipment: a weight in kg or another measure (a value and a free unit such as `palets` or `m³`). Required to issue.
        - `type` 'weight' | 'other', required
        - `weight_kg` string, nullable, required: Weight in kg when `type` is `weight`.
        - `value` string, nullable, required: Value when `type` is `other`.
        - `unit` string, nullable, required: Free unit when `type` is `other`.
      - `delivery_note_id` string, uuid, nullable, required: Delivery note (UUID v7) the shipment was built from, or `null`.
      - `source_changed` boolean, required: `true` when the delivery note changed (lines, quantities, delivery address or date) after the current version. Delivering or invoicing the delivery note does not count.
      - `source_changes` TransportDocumentChange[], required: What changed in the delivery note compared with the shipment; empty when `source_changed` is `false`.
        - `field` string, required: Changed datum, e.g. `vehicle.tractor_plate`, `shipments.2.destination` or `shipments.1.goods.3.quantity`.
        - `previous` string, required: Value before the change, or `null`.
        - `current` string, required: Value after the change, or `null`.
      - `source_missing` boolean, required: `true` when the delivery note was cancelled or deleted.
      - `observations` string, nullable, required
    - `versions` TransportDocumentVersion[], required: Stored PDF versions, oldest first. At most 50: the last one is reserved for cancelling or superseding, so modifications stop at 49 (422 `transport_document_version_limit_reached`).
      - `number` integer, required
      - `kind` 'issue' | 'modification' | 'cancellation' | 'supersession', required
      - `reason` string, nullable, required: Reason of the modification, cancellation or supersession; `null` on the issue.
      - `data_origin` 'company' | 'carrier_reported', required: Who reported the data: your company or the carrier.
      - `created_at` string, date-time, required
      - `created_by` string, nullable, required: Name of the actor (user, API key or MCP client) that created the version, or `null` when it cannot be attributed.
      - `changes` TransportDocumentChange[], required: Data changed compared with the previous version; the previous values are printed as «no longer valid».
        - `field` string, required: Changed datum, e.g. `vehicle.tractor_plate`, `shipments.2.destination` or `shipments.1.goods.3.quantity`.
        - `previous` string, required: Value before the change, or `null`.
        - `current` string, required: Value after the change, or `null`.
      - `sha256` string, required: sha256 of the stored PDF: recompute it over the downloaded file to verify it.
      - `size_bytes` integer, required: Size of the stored PDF in bytes; a version never exceeds 5 MB (5,000,000 bytes): a larger render is rejected with 422 `transport_document_pdf_too_large` and nothing is saved.
    - `issued_at` string, date-time, nullable, required
    - `last_modified_at` string, date-time, nullable, required
    - `closed_at` string, date-time, nullable, required
    - `close_mode` 'manual' | 'automatic' | 'null', nullable, required
    - `reopen_deadline` string, date-time, nullable, required: Instant of the automatic close (end of the last transport date + 7 days, Europe/Madrid): a manually closed document can be reopened until then.
    - `cancelled_at` string, date-time, nullable, required
    - `cancel_reason` string, nullable, required
    - `superseded_at` string, date-time, nullable, required
    - `superseding_reference` string, nullable, required: Reference of the carrier document that supersedes this one.
    - `retention_until` string, date-time, nullable, required: End of the legal retention period (one year after closing, cancelling or superseding).
    - `files_purged_at` string, date-time, nullable, required: When the PDF files were purged (only for closed accounts after the retention period); the public URL then returns 410.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required

## Other responses

- `400`: `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version.
- `401`: Missing or invalid API key.
- `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).
- `404`: The requested resource does not exist or belongs to another company.
- `422`: Validation failed, or the transport document breaks a rule of the Spanish control document (DeCA): missing data to issue it (`transport_document_not_issuable`, with the list in `error.details.missing`), a transport date in the past, a shipment outside Spain, parties changed after issuing, a modification that changes nothing, or a lifecycle transition that its status does not allow. The `error.param` field identifies which input is invalid, if any.
- `429`: Rate limit exceeded. Retry after the duration in `Retry-After`.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)