Transport Documents

List all transport documents

List the transport control documents (DeCA) of your company with cursor-based pagination.

  • Filters: status, transport_date[gte]/[lte], company_role, carrier_tax_id, delivery_note_id, q.
  • Sort with sort (default -transport_date). Any other query parameter returns 400.
get/companies/{company}/transport-documents

Request

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

Path parameters

companystring uuid required

Public identifier (UUID v7) of the company. Get it from GET /v1/me (data.scope[].id).

Query parameters

limitinteger

Number of objects to return, between 1 and 100 (default 25).

starting_afterstring uuid

Cursor for forward pagination: pass the id of the last object on the previous page (the next_cursor of the previous response).

ending_beforestring uuid

Cursor for backward pagination: pass the id of the first object on the current page.

status'draft' | 'issued' | 'closed' | 'cancelled' | 'superseded'

Transport document status: draft, issued, closed, cancelled or superseded. Exact match on status.

status[in]string

Comma-separated list of values (CSV).

Transport document status: draft, issued, closed, cancelled or superseded. Comma-separated list. Any of the values matches.

transport_date[gte]string date

Transport date period (YYYY-MM-DD). A document matches when the date range of its shipments overlaps the period. Greater than or equal to the given value.

transport_date[lte]string date

Transport date period (YYYY-MM-DD). A document matches when the date range of its shipments overlaps the period. Less than or equal to the given value.

company_role'shipper' | 'carrier'

Role of your company in the document: shipper (contractual shipper) or carrier (effective carrier). Exact match on company_role.

carrier_tax_idstring

Tax ID of the effective carrier. Exact match on carrier_tax_id.

delivery_note_idstring uuid

Delivery note ID (UUID v7): documents with at least one shipment from that delivery note. Exact match on delivery_note_id.

qstring

Free-text search over the number, the parties (name and tax ID) and the vehicle plates (1-255 characters). Exact match on q.

sort'transport_date' | '-transport_date' | 'number' | '-number' | 'created' | '-created' | 'updated' | '-updated'

Sort order: transport_date, number, created, updated ascending, or with a - prefix for descending (default: documents are ordered by transport date, newest first).

Headers

Factuarea-Versionstring date
Example:2026-06-01

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.

Response

has_moreboolean required

Whether more pages are available after this one.

next_cursorstring nullable required

Opaque cursor for the next page, or null when has_more is false. The example below shows the shape used by most listings; others return a different one, so pass the value back verbatim instead of validating it.

Example response

{
  "data": [
    {
      "number": "DC-2026-007",
      "status": "issued",
      "shipper": {
        "name": "Transportes Pérez SL",
        "tax_id": "B12345674",
        "tax_id_country": "ES",
        "address": {
          "line": "Calle de la Industria 14",
          "postal_code": "28901",
          "city": "Getafe",
          "province": "Madrid",
          "country": "ES",
          "name": "Nave Getafe"
        }
      },
      "carrier": {
        "name": "Transportes Pérez SL",
        "tax_id": "B12345674",
        "tax_id_country": "ES",
        "address": {
          "line": "Calle de la Industria 14",
          "postal_code": "28901",
          "city": "Getafe",
          "province": "Madrid",
          "country": "ES",
          "name": "Nave Getafe"
        }
      },
      "vehicle": {
        "tractor_plate": "1234BCD",
        "tractor_plate_country": "ES",
        "trailer_plate": "R1234BCD",
        "trailer_plate_country": "ES"
      },
      "shipments": [
        {
          "origin": {
            "line": "Calle de la Industria 14",
            "postal_code": "28901",
            "city": "Getafe",
            "province": "Madrid",
            "country": "ES",
            "name": "Nave Getafe"
          },
          "destination": {
            "line": "Calle de la Industria 14",
            "postal_code": "28901",
            "city": "Getafe",
            "province": "Madrid",
            "country": "ES",
            "name": "Nave Getafe"
          },
          "goods": [
            {
              "description": "Aceite de oliva virgen extra 5 L",
              "quantity": "12.0000",
              "unit": "garrafa",
              "gross_weight_kg": "4.8500"
            }
          ],
          "declared_measure": {
            "weight_kg": "1250.5000"
          },
          "source_changes": [
            {
              "field": "vehicle.tractor_plate",
              "previous": "1234BCD",
              "current": "5678FGH"
            }
          ]
        }
      ],
      "versions": [
        {
          "number": 2,
          "reason": "Avería de la tractora",
          "changes": [
            {
              "field": "vehicle.tractor_plate",
              "previous": "1234BCD",
              "current": "5678FGH"
            }
          ]
        }
      ]
    }
  ],
  "has_more": true,
  "next_cursor": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a0c"
}

Changes

No recorded changes to this operation across all 1 revision of this API.