---
title: "Send a transport document by email"
method: POST
path: "/companies/{company}/transport-documents/{transport_document}/send"
tags: ["Transport Documents"]
---

# Send a transport document by email

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

## Request

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

Email the stored PDF of the current version, with the public link, to up to 5 recipients across `to`, `cc` and `bcc`.
- Only `issued` or `closed` documents; without `to`, the carrier contact's email is used, else 422 `transport_document_not_sendable`.
- Irreversible: requires `Idempotency-Key`. A 500 `send_failed` records nothing; retry with a new key.

## Path parameters

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

## Headers

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

## Request body

- SendTransportDocumentRequest: Email the current PDF of the transport document. Optional `to`, `cc` and `bcc` (lists of emails, up to 5 distinct addresses in total; an address repeated within or across the lists, ignoring letter case, counts and is sent once) plus `subject` and `message`. Without `to`, the email of the carrier contact is used.
  - `subject` string, nullable
  - `message` string, nullable
  - `to` string[]
  - `cc` string[]
  - `bcc` string[]

## 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.
- `410`: The files of this transport document were purged when its retention period ended (one year after it was closed, cancelled or superseded, and only once the account was closed). The document and its data are kept, but its PDF can no longer be served or sent. Code `transport_document_file_unavailable`, `error.type: not_found_error`. Retrying returns the same error.
- `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)