Emitir un documento de control

Emite un documento de control en borrador.

Comprueba los datos mínimos (nombre, NIF y domicilio completo del cargador; nombre y NIF del transportista; al menos un envío con origen, destino, mercancía y magnitud declarada; matrícula de la tractora; fecha de transporte), que cada origen y destino esté en España y que cada fecha de transporte sea hoy o posterior (Europe/Madrid).
En una sola operación atómica asigna el siguiente número de la serie DC y la URL pública permanente, renderiza y guarda la versión 1 del PDF con su sha256, y pasa el documento a issued.
Si faltan datos devuelve 422 transport_document_not_issuable con la lista en error.details.missing, con este vocabulario cerrado: shipper.name, shipper.tax_id, shipper.address, carrier.name, carrier.tax_id, vehicle.tractor_plate, transport_date, shipments (ningún envío) y shipments.N.origin|destination|goods|measure, con N contando desde 1. Un PDF de más de 5 MB devuelve 422 transport_document_pdf_too_large y no se emite nada.
Irreversible: exige Idempotency-Key.
Entrega el PDF, el enlace o el QR al conductor antes de que empiece el transporte.

Clave opaca generada por el cliente (hasta 255 caracteres; se recomienda UUID v7) que permite reintentos seguros: la primera respuesta se almacena y se reproduce en las repeticiones sin volver a ejecutar la mutación. Reutilizar una clave con un cuerpo distinto devuelve 409 idempotency_key_reused. Consulta la guía de idempotencia. Obligatoria en esta operación: repetirla produce un efecto irreversible (un email enviado, un archivo generado, una llamada a un tercero o un cargo), por lo que una petición sin esta cabecera se rechaza con 422 idempotency_key_required antes de ejecutar lógica de negocio.

Longitud1 <= length <= 255

Factuarea-Version?string

Fija la versión de la API (YYYY-MM-DD, versionado por fecha estilo Stripe) para esta petición; omítelo para usar la versión fijada de la clave, o la última si no hay ninguna. Versión no soportada → 400 unsupported_api_version; malformada → 400 parameter_invalid_format. La versión efectiva se refleja en la cabecera de respuesta Factuarea-Version. Consulta la guía de Versioning.

Formatodate

X-Active-Profile?string

Opera en nombre de una empresa hija (API key maestra de gestoría): pasa su id público (UUID v7) y la petición se ejecuta contra los datos de esa hija sin cambiar el scope, el tier ni el environment de la clave (omítelo para usar la propia empresa de la clave). UUID inválido → 400 parameter_invalid_uuid; id desconocido o no propio → 404 profile_not_found. Consulta la guía de Acting on behalf.

Formatouuid

Cuerpo de la respuesta

`application/json`

Ejemplo de petición

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/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/issue", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Idempotency-Key":"erp-2026-public-api-v1-transport_documents-issue"} },});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Ejemplo de respuesta

{
  "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": 1,
    "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": 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
      }
    ],
    "issued_at": "2026-10-05T16:20:00+00:00",
    "last_modified_at": null,
    "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"
  }
}

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

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

{
  "error": {
    "type": "not_found_error",
    "code": "transport_document_not_found",
    "message": "DeCA no encontrado.",
    "doc_url": "https://docs.factuarea.com/guides/errors#transport_document_not_found",
    "request_id": "req_ded21c21420c0d22c2d6b201c5"
  }
}

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

POST /v1/transport_documents/{transport_document}/issue · 422 transport_document_not_issuable

{
  "error": {
    "type": "invalid_request_error",
    "code": "transport_document_not_issuable",
    "message": "No se puede emitir el DeCA. Faltan 3 datos: el NIF del transportista efectivo; la matrícula de la tractora o del vehículo rígido; la magnitud declarada del envío 1 (peso u otra).",
    "details": {
      "missing": [
        "carrier.tax_id",
        "vehicle.tractor_plate",
        "shipments.1.measure"
      ]
    },
    "doc_url": "https://docs.factuarea.com/guides/errors#transport_document_not_issuable",
    "request_id": "req_71c9ec690b488dd5238b07c4fb"
  }
}

POST /v1/transport_documents/{transport_document}/issue · 422 transport_date_in_past

{
  "error": {
    "type": "invalid_request_error",
    "code": "transport_date_in_past",
    "message": "El DeCA debe emitirse antes de iniciar el transporte: la fecha 04/10/2026 ya ha pasado.",
    "param": "transport_date",
    "doc_url": "https://docs.factuarea.com/guides/errors#transport_date_in_past",
    "request_id": "req_cddfdf26039421b55a8eb0b9ec"
  }
}

POST /v1/transport_documents/{transport_document}/issue · 422 transport_outside_spain

{
  "error": {
    "type": "invalid_request_error",
    "code": "transport_outside_spain",
    "message": "El envío 2 va a Portugal. El DeCA solo documenta transporte interior; el internacional se documenta con la carta de porte CMR.",
    "param": "shipments",
    "doc_url": "https://docs.factuarea.com/guides/errors#transport_outside_spain",
    "request_id": "req_7e2bbb919ba6fbf8179abe1f83"
  }
}

POST /v1/transport_documents/{transport_document}/issue · 422 idempotency_key_required

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_required",
    "message": "La operación «public-api.v1.transport_documents.issue» exige la cabecera Idempotency-Key desde el 2026-12-01. Envía una clave única por operación (un UUID sirve) y, si reintenta, repite exactamente la misma clave para que la operación no se ejecute dos veces.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.factuarea.com/guides/errors#idempotency_key_required",
    "request_id": "req_be8d8eacddff6e255487a26494"
  }
}

POST /v1/transport_documents/{transport_document}/issue · 422 transport_document_pdf_too_large

{
  "error": {
    "type": "invalid_request_error",
    "code": "transport_document_pdf_too_large",
    "message": "El PDF del DeCA ocuparía 5,31 MB y el máximo permitido es 5 MB. No se ha guardado ningún cambio. Reduce el contenido del documento (menos envíos o líneas de mercancía, descripciones u observaciones más cortas) o reparte los envíos en varios DeCA.",
    "doc_url": "https://docs.factuarea.com/guides/errors#transport_document_pdf_too_large",
    "request_id": "req_0dc1e50a622ffa8a0488efade6"
  }
}

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

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

Emitir un documento de control

Authorization

Parámetros de ruta

Headers

Cuerpo de la respuesta

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Emitir un documento de control

Authorization

Parámetros de ruta

Headers

Cuerpo de la respuesta

200application/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`