Llistar tots els documents de control

Llista els documents de control (DeCA, document electrònic de control administratiu del transport de mercaderies per carretera) de la teva empresa amb paginació per cursor.

Filtres: status (també status[in]), transport_date[gte]/transport_date[lte] (un document coincideix quan el rang de dates dels seus enviaments se solapa amb el període), company_role (shipper o carrier), carrier_tax_id, delivery_note_id (documents amb un enviament d'aquest albarà) i q (número, parts o matrícules).
Ordena amb sort (transport_date, number, created, updated; prefix - per a descendent; per defecte -transport_date).
q admet d'1 a 255 caràcters.
Qualsevol altre paràmetre de consulta retorna 400. L'eina MCP search_transport_documents accepta els mateixos sort i q.

Paràmetres de consulta

limit?integer

Nombre d'objectes a retornar. Enter entre 1 i 100. Per defecte 25.

Predeterminat25

Rang1 <= value <= 100

starting_after?string

Cursor per a paginació cap endavant. Fes servir l'uuid de l'últim objecte de la pàgina anterior.

Formatuuid

ending_before?string

Cursor per a paginació cap enrere. Fes servir l'uuid del primer objecte de la pàgina actual.

Formatuuid

status?string

Estat del document de control: draft, issued, closed, cancelled o superseded. Coincidència exacta sobre status.

Valor a"draft" | "issued" | "closed" | "cancelled" | "superseded"

status[in]?string

Estat del document de control: draft, issued, closed, cancelled o superseded. Llista separada per comes. Coincideix qualsevol dels valors.

transport_date[gte]?string

Període de dates de transport (YYYY-MM-DD). Un document coincideix quan el rang de dates dels seus enviaments se solapa amb el període. Més gran o igual que el valor indicat.

Formatdate

transport_date[lte]?string

Període de dates de transport (YYYY-MM-DD). Un document coincideix quan el rang de dates dels seus enviaments se solapa amb el període. Menor o igual que el valor indicat.

Formatdate

company_role?string

Paper de la teva empresa al document: shipper (carregador contractual) o carrier (transportista efectiu). Coincidència exacta sobre company_role.

Valor a"shipper" | "carrier"

carrier_tax_id?string

NIF del transportista efectiu. Coincidència exacta sobre carrier_tax_id.

delivery_note_id?string

ID de l'albarà (UUID v7): documents amb almenys un enviament d'aquest albarà. Coincidència exacta sobre delivery_note_id.

Formatuuid

q?string

Cerca de text lliure sobre el número, les parts (nom i NIF) i les matrícules (d'1 a 255 caràcters). Coincidència exacta sobre q.

sort?string

Ordre de classificació. Fes servir un camp per a ordre ascendent o el prefix - per a descendent (p. ex. -created). Camps permesos: transport_date, number, created, updated. Combinat amb el cursor, l'ordre continua sent determinista (un ordre secundari estable per l'id del cursor, a l'estil de Stripe). Si s'omet, els documents s'ordenen per data de transport, els més recents primer.

Headers

Factuarea-Version?string

Fixa la versió de l'API (YYYY-MM-DD, versionat per data estil Stripe) per a aquesta petició; omet-lo per usar la versió fixada de la clau, o l'última si no n'hi ha cap. Versió no suportada → 400 unsupported_api_version; mal formada → 400 parameter_invalid_format. La versió efectiva es reflecteix a la capçalera de resposta Factuarea-Version. Consulta la guia de Versioning.

Formatdate

X-Active-Profile?string

Opera en nom d'una empresa filla (API key mestra de gestoria): passa el seu id públic (UUID v7) i la petició s'executa contra les dades d'aquella filla sense canviar l'scope, el tier ni l'environment de la clau (omet-lo per usar la pròpia empresa de la clau). UUID no vàlid → 400 parameter_invalid_uuid; id desconegut o no propi → 404 profile_not_found. Consulta la guia d'Acting on behalf.

Formatuuid

Cos de la resposta

`application/json`

Exemple de petició

const apiKey = process.env.FACTUAREA_API_KEY;if (!apiKey) throw new Error("Set FACTUAREA_API_KEY");const response = await fetch("https://api.factuarea.com/v1/transport_documents?limit=25", {  method: "GET",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json"} },});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Exemple de resposta

{
  "data": [
    {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01",
      "object": "transport_document",
      "number": "DC-2026-042",
      "status": "issued",
      "company_role": "shipper",
      "public_url": "https://app.factuarea.com/api/public/deca/q3VfN2mX8yPbK1rT4wZs6LcH0dGjAe9uIoRtYvBnMkE",
      "current_version": 2,
      "shipper": {
        "name": "Distribuciones Olivar SL",
        "tax_id": "A58818501",
        "tax_id_country": "ES",
        "address": {
          "line": "Calle Industria 5",
          "postal_code": "28901",
          "city": "Getafe",
          "province": "Madrid",
          "country": "ES",
          "name": null
        },
        "contact_id": null
      },
      "carrier": {
        "name": "Transportes Pérez SL",
        "tax_id": "B12345674",
        "tax_id_country": "ES",
        "address": null,
        "contact_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01"
      },
      "vehicle": {
        "tractor_plate": "1234BCD",
        "tractor_plate_country": "ES",
        "trailer_plate": "R9876BCD",
        "trailer_plate_country": "ES"
      },
      "special_authorization": null,
      "transport_date": "2026-10-06",
      "observations": "Entrega en horario de mañana.",
      "shipments": [
        {
          "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a11",
          "origin": {
            "line": "Calle Industria 5",
            "postal_code": "28901",
            "city": "Getafe",
            "province": "Madrid",
            "country": "ES",
            "name": "Nave Getafe"
          },
          "destination": {
            "line": "Avenida de Europa 20",
            "postal_code": "45005",
            "city": "Toledo",
            "province": "Toledo",
            "country": "ES",
            "name": "Ultramarinos Toledo"
          },
          "transport_date": "2026-10-06",
          "goods": [
            {
              "description": "Aceituna gordal aliñada",
              "additional_description": "Mantener refrigerado.",
              "quantity": "10.0000",
              "unit": "cajas",
              "gross_weight_kg": "12.5000"
            }
          ],
          "declared_measure": {
            "type": "weight",
            "weight_kg": "125.0000",
            "value": null,
            "unit": null
          },
          "delivery_note_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a06",
          "source_changed": true,
          "source_changes": [
            {
              "field": "goods.1",
              "previous": {
                "description": "Aceituna gordal aliñada",
                "additional_description": "Mantener refrigerado.",
                "quantity": "10.0000",
                "unit": "cajas",
                "gross_weight_kg": "12.5000"
              },
              "current": {
                "description": "Aceituna gordal aliñada",
                "additional_description": "Mantener refrigerado.",
                "quantity": "12.0000",
                "unit": "cajas",
                "gross_weight_kg": "12.5000"
              }
            }
          ],
          "source_missing": false,
          "observations": "Albarán ALB-2026-00231"
        },
        {
          "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a12",
          "origin": {
            "line": "Calle Industria 5",
            "postal_code": "28901",
            "city": "Getafe",
            "province": "Madrid",
            "country": "ES",
            "name": "Nave Getafe"
          },
          "destination": {
            "line": "Plaza Mayor 3",
            "postal_code": "45600",
            "city": "Talavera de la Reina",
            "province": "Toledo",
            "country": "ES",
            "name": null
          },
          "transport_date": null,
          "goods": [
            {
              "description": "Palés de aceite de oliva",
              "additional_description": null,
              "quantity": "2.0000",
              "unit": "palés",
              "gross_weight_kg": null
            }
          ],
          "declared_measure": {
            "type": "other",
            "weight_kg": null,
            "value": "2.0000",
            "unit": "palés"
          },
          "delivery_note_id": null,
          "source_changed": false,
          "source_changes": [],
          "source_missing": false,
          "observations": null
        }
      ],
      "versions": [
        {
          "number": 1,
          "kind": "issue",
          "reason": null,
          "data_origin": "company",
          "created_at": "2026-10-05T16:20:00+00:00",
          "created_by": "ERP Almacén (API)",
          "changes": [],
          "sha256": "3bfadc5c0e1f2a4b6c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b68d5",
          "size_bytes": 73865
        },
        {
          "number": 2,
          "kind": "modification",
          "reason": "Cambio de semirremolque en ruta",
          "data_origin": "carrier_reported",
          "created_at": "2026-10-06T07:10:00+00:00",
          "created_by": "ERP Almacén (API)",
          "changes": [
            {
              "field": "vehicle.trailer_plate",
              "previous": "R1234BCD",
              "current": "R9876BCD"
            }
          ],
          "sha256": "9c1d7e2a4b6f8a0c2e4f6a8b0c2d4e6f8a0b2c4d6e8f0a1b3c5d7e9f1a3b5c7d",
          "size_bytes": 81234
        }
      ],
      "issued_at": "2026-10-05T16:20:00+00:00",
      "last_modified_at": "2026-10-06T07:10:00+00:00",
      "closed_at": null,
      "close_mode": null,
      "reopen_deadline": "2026-10-13T22:00:00+00:00",
      "cancelled_at": null,
      "cancel_reason": null,
      "superseded_at": null,
      "superseding_reference": null,
      "retention_until": null,
      "files_purged_at": null,
      "created_at": "2026-10-05T15:58:12+00:00",
      "updated_at": "2026-10-06T07:10:00+00:00"
    }
  ],
  "has_more": true,
  "next_cursor": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_unknown",
    "message": "El parámetro 'driver' no está permitido en este endpoint.",
    "param": "driver",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_unknown",
    "request_id": "req_f0f7adf13e4542c0449a30d83a"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "missing_api_key",
    "message": "Falta header Authorization o X-API-Key.",
    "doc_url": "https://docs.factuarea.com/guides/errors#missing_api_key",
    "request_id": "req_b5bcb825786d3782cbf1b1111f"
  }
}

{
  "error": {
    "type": "authorization_error",
    "code": "insufficient_scope",
    "message": "Esta operación requiere el scope 'transport_documents:read'. Tu API key solo tiene los scopes: transport_documents:read.",
    "doc_url": "https://docs.factuarea.com/guides/errors#insufficient_scope",
    "request_id": "req_86221bf5cf77978783cf70d319"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "Los parámetros 'starting_after' y 'ending_before' son mutuamente excluyentes.",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_847e82c71425b230d11dca2d13"
  }
}

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Has excedido el límite de requests permitido. Reintenta más tarde.",
    "doc_url": "https://docs.factuarea.com/guides/errors#rate_limit_exceeded",
    "request_id": "req_4b4366684ee6801d92ac8262a7"
  }
}

{
  "error": {
    "type": "api_error",
    "code": "internal_error",
    "message": "Algo se rompió en nuestro lado al procesar la petición. La condición no la provoca tu payload.",
    "doc_url": "https://docs.factuarea.com/guides/errors#internal_error",
    "request_id": "req_06787925cb22fc95eac4f63915"
  }
}

Llistar tots els documents de control

Authorization

Paràmetres de consulta

Headers

Cos de la resposta

200application/json

400application/json

401application/json

403application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`