Create a transport document

Create a transport document (DeCA) in draft.

company_role says whether your company acts as contractual shipper (shipper) or effective carrier (carrier); your party is filled with your company data and the other one from contact_id or from the fields you send.
Pass delivery_note_ids (1 to 50 of your delivery notes) to pre-fill one shipment per delivery note with its destination, date and goods (services excluded, frozen weights); a cancelled delivery note is rejected with 422 delivery_note_cancelled.
A shipment that omits origin gets your default loading place or, if you have none, your registered address (an explicit origin: null leaves it without origin).
The id is generated by the server; shipments[].id is optional and an identifier already in use returns 422 on shipments.N.id.
A goods line whose quantity × gross_weight_kg exceeds 9,999,999,999.9999 kg or rounds to 0 returns 422 invalid_gross_weight on shipments.N.goods.M.gross_weight_kg.
A draft admits incomplete data; the minimum data is only required to issue.
A concurrent write that collides on an identifier returns 409 resource_conflict: nothing was saved and the request can be retried.
Returns 201 with the resource and a Location header.

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.

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.

company_role*string

Value in"shipper" | "carrier"

special_authorization?|

Lengthlength <= 100

transport_date?|

Formatdate

observations?|

Lengthlength <= 5000

vehicle?

shipments?array<>|

Itemsitems <= 50

shipper?

carrier?

delivery_note_ids?array<>

Items1 <= items <= 50

Response Body

`application/json`

Request example

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", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-transport_documents-create"} },  body: JSON.stringify({  "company_role": "shipper",  "carrier": {    "contact_id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a10"  },  "vehicle": {    "tractor_plate": "1234BCD",    "trailer_plate": "R1234BCD"  },  "transport_date": "2026-10-06",  "observations": "Carga en muelle 3.",  "delivery_note_ids": [    "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a11",    "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a12"  ]}),});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Response example

{
  "data": {
    "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f9a01",
    "object": "transport_document",
    "number": null,
    "status": "draft",
    "company_role": "shipper",
    "public_url": null,
    "current_version": null,
    "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": "R1234BCD",
      "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": false,
        "source_changes": [],
        "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": [],
    "issued_at": null,
    "last_modified_at": null,
    "closed_at": null,
    "close_mode": null,
    "reopen_deadline": null,
    "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"
  }
}

{
  "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_497f8793c2d2261a089521ba79"
  }
}

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

{
  "error": {
    "type": "not_found_error",
    "code": "delivery_note_not_found",
    "message": "Albarán no encontrado.",
    "param": "delivery_note_ids",
    "doc_url": "https://docs.factuarea.com/guides/errors#delivery_note_not_found",
    "request_id": "req_3d0683bf1d078020be1817c657"
  }
}

POST /v1/transport_documents · 409 idempotency_key_reused

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_key_reused",
    "message": "Esa `Idempotency-Key` ya se usó con un payload distinto. La clave identifica una operación concreta, así que reutilizarla para otra vaciaría de sentido el replay.",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_reused",
    "request_id": "req_dea73f135a6d8026a5a1cc91cc"
  }
}

POST /v1/transport_documents · 409 resource_conflict

{
  "error": {
    "type": "conflict_error",
    "code": "resource_conflict",
    "message": "Se ha detectado otra escritura concurrente sobre los mismos datos. Vuelve a intentarlo dentro de unos segundos: la operación es reintentable y no ha dejado nada a medias.",
    "doc_url": "https://docs.factuarea.com/guides/errors#resource_conflict",
    "request_id": "req_330bfeb5147b0ef1ce78f03540"
  }
}

POST /v1/transport_documents · 422 invalid_param_value

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "Los lugares de carga no se exponen en esta superficie: indica el origen del envío con su dirección.",
    "param": "shipments.0.loading_place_id",
    "errors": [
      {
        "param": "shipments.0.loading_place_id",
        "code": "parameter_invalid_value",
        "message": "Los lugares de carga no se exponen en esta superficie: indica el origen del envío con su dirección."
      }
    ],
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_906c1b5db5b1fe12e80ae11feb"
  }
}

POST /v1/transport_documents · 422 delivery_note_cancelled

{
  "error": {
    "type": "invalid_request_error",
    "code": "delivery_note_cancelled",
    "message": "El albarán ALB-2026-00231 está anulado y no puede ser origen de un envío del DeCA.",
    "param": "delivery_note_ids",
    "doc_url": "https://docs.factuarea.com/guides/errors#delivery_note_cancelled",
    "request_id": "req_7987270f6403b8ee7a30c390a4"
  }
}

POST /v1/transport_documents · 422 invalid_transport_tax_id

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_transport_tax_id",
    "message": "La identificación fiscal 12345678A no es válida.",
    "param": "tax_id",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_transport_tax_id",
    "request_id": "req_0934e15d9ab58c670cfa148c04"
  }
}

POST /v1/transport_documents · 422 invalid_vehicle_plate

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_vehicle_plate",
    "message": "La matrícula 1234ABC no es válida: las matrículas españolas no llevan vocales. Revisa las letras o, si es extranjera, elige su país.",
    "param": "vehicle",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_vehicle_plate",
    "request_id": "req_1d8d0baa2ddcf8deec0ea9d9a3"
  }
}

POST /v1/transport_documents · 422 invalid_cargo_measure

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_cargo_measure",
    "message": "El tipo de magnitud «volume» no es válido: usa weight (peso en kg) u other (otra magnitud con su unidad).",
    "param": "declared_measure",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_cargo_measure",
    "request_id": "req_1cd1c08aae483f33bf41255dd6"
  }
}

POST /v1/transport_documents · 422 invalid_gross_weight

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_gross_weight",
    "message": "El peso de la línea 1 del envío 1 no es válido: 2000000 unidades de 5000000 kg dan un peso de línea que debe ser mayor que 0 kg y no superar 9999999999.9999 kg. Revisa la cantidad o el peso por unidad.",
    "param": "shipments.0.goods.0.gross_weight_kg",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_gross_weight",
    "request_id": "req_13bb61fd4a50a88be21c8661fc"
  }
}

POST /v1/transport_documents · 422 invalid_param_value

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "Este identificador de envío ya está en uso.",
    "param": "shipments.0.id",
    "errors": [
      {
        "param": "shipments.0.id",
        "code": "parameter_invalid_value",
        "message": "Este identificador de envío ya está en uso."
      }
    ],
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_d3a5f0a9d3f2d56cdf4f7833b6"
  }
}

{
  "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_33b639ba7f4c25224e20120e90"
  }
}

{
  "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_49bcca7b66b382b49580ae8801"
  }
}

Create a transport document

Authorization

Headers

Request Body

Response Body

201application/json

401application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`