Enviar un documento de control por email

Envía por email el PDF guardado de la versión vigente, con el enlace público, a hasta 5 destinatarios en total entre to, cc y bcc, con subject y message opcionales.

Sin to, se usa el email del contacto transportista; si no lo hay, 422 transport_document_not_sendable.
Solo se pueden enviar documentos issued o closed; el envío queda en el registro de emisión con sus destinatarios.
Irreversible: exige Idempotency-Key.
Devuelve 410 transport_document_file_unavailable cuando los ficheros se han purgado, y 500 send_failed si el proveedor de correo rechaza el mensaje o no puede aceptarlo (no se anota nada en el registro; reintenta con una Idempotency-Key nueva).

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 petición

application/json

Definiciones de TypeScript

Usa el tipo request body en TypeScript.

subject?|

Longitudlength <= 255

message?|

Longitudlength <= 5000

to?array<>

cc?array<>

bcc?array<>

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/send", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Content-Type":"application/json","Idempotency-Key":"erp-2026-public-api-v1-transport_documents-send"} },  body: JSON.stringify({  "to": [    "trafico@transportesperez.es"  ],  "cc": [    "logistica@empresa.es"  ],  "subject": "DeCA DC-2026-007",  "message": "Adjuntamos el documento de control del porte de mañana."}),});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": 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"
  }
}

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

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

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

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

{
  "error": {
    "type": "not_found_error",
    "code": "transport_document_file_unavailable",
    "message": "Los ficheros de este DeCA se eliminaron al terminar su plazo de conservación.",
    "doc_url": "https://docs.factuarea.com/guides/errors#transport_document_file_unavailable",
    "request_id": "req_03a14e051712b74650d1294c32"
  }
}

POST /v1/transport_documents/{transport_document}/send · 422 transport_document_not_sendable

{
  "error": {
    "type": "invalid_request_error",
    "code": "transport_document_not_sendable",
    "message": "Indica al menos un destinatario: el transportista del DeCA no tiene email.",
    "param": "to",
    "doc_url": "https://docs.factuarea.com/guides/errors#transport_document_not_sendable",
    "request_id": "req_f3d9b94e30dc948df369306fe9"
  }
}

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

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_required",
    "message": "La operación «public-api.v1.transport_documents.send» 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_801d1257847940811a6bb82cfe"
  }
}

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

POST /v1/transport_documents/{transport_document}/send · 500 internal_error

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

POST /v1/transport_documents/{transport_document}/send · 500 send_failed

{
  "error": {
    "type": "api_error",
    "code": "send_failed",
    "message": "No se pudo enviar el documento de control por email. Reintenta más tarde.",
    "doc_url": "https://docs.factuarea.com/guides/errors#send_failed",
    "request_id": "req_9c3e5a7b1d0f2e4a6c8b0d2f4e"
  }
}

Enviar un documento de control por email

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Enviar un documento de control por email

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

200application/json

401application/json

403application/json

404application/json

409application/json

410application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`