Subir un adjunto de tarea

Sube un archivo a una tarea como multipart/form-data (file).

Máximo 10 MB por archivo; el tipo se comprueba por el contenido (magic bytes), no por la extensión: imágenes (PNG, JPEG, GIF, WebP, HEIC, AVIF), PDF, Word/Excel/PowerPoint (OOXML), texto y hoja de cálculo OpenDocument, texto plano, CSV, Markdown y ZIP.
target lo coloca en un comentario nuevo (por defecto) o al final de la descripción, y la note opcional (hasta 1,000 caracteres) pasa a ser el texto del comentario; una nota más larga devuelve 422 parameter_invalid_value.
El archivo cuenta para la cuota de almacenamiento de tu plan (402 storage_quota_exceeded cuando está llena).
Requiere una Idempotency-Key.

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

multipart/form-data

Definiciones de TypeScript

Usa el tipo request body en TypeScript.

file*file

Archivo adjunto (multipart). El tipo se detecta a partir del contenido, nunca de la extensión.

Formatobinary

target?string

Destino: comment (por defecto, crea un comentario con la nota y el adjunto) o description.

Valor en"description" | "comment"

note?|

Nota del comentario que acompaña al adjunto; solo se usa con target=comment.

Longitudlength <= 1000

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 form = new FormData();form.append("file", new Blob([await (await import("node:fs/promises")).readFile("./documento.pdf")]), "documento.pdf");const response = await fetch("https://api.factuarea.com/v1/tasks/01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01/attachments", {  method: "POST",  headers: { Authorization: `Bearer ${apiKey}`, ...{"Accept":"application/json","Idempotency-Key":"erp-2026-public-api-v1-tasks-attachments-create"} },  body: form,});if (!response.ok) throw new Error(await response.text());if (response.status !== 204) console.log(await response.json());

Ejemplo de respuesta

{
  "data": {
    "id": "0193a4f2-efb9-7daa-8e4b-3a5b7c9d1f02",
    "object": "task_attachment",
    "task_id": "0193a4f2-8f53-7d44-8e85-7a9b1c3d5f12",
    "comment_id": "0193a4f2-ab75-7f66-8a07-9c1d3e5f7b01",
    "surface": "comment",
    "file_name": "especificacion-pasarela.pdf",
    "mime_type": "application/pdf",
    "size_bytes": 1048576,
    "kind": "file",
    "uploaded_by_id": "0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b01",
    "created_at": "2026-09-24T12:31:09+02: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_4f3124617b5bff7df54598c964"
  }
}

{
  "error": {
    "type": "payment_required_error",
    "code": "storage_quota_exceeded",
    "message": "No queda espacio de almacenamiento en tu empresa: estás usando 4995 MB de los 5000 MB de tu plan y este archivo ocupa 8 MB. Elimina archivos que ya no necesites o amplía tu plan desde Facturación, y vuelve a subirlo.",
    "doc_url": "https://docs.factuarea.com/guides/errors#storage_quota_exceeded",
    "request_id": "req_2cd106bfd5de0e110cc9f6165d"
  }
}

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

{
  "error": {
    "type": "not_found_error",
    "code": "task_not_found",
    "message": "Tarea no encontrada.",
    "doc_url": "https://docs.factuarea.com/guides/errors#task_not_found",
    "request_id": "req_5c58349548d2534717af6874dd"
  }
}

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

{
  "error": {
    "type": "invalid_request_error",
    "code": "payload_too_large",
    "message": "El payload excede el límite de 1 MB.",
    "doc_url": "https://docs.factuarea.com/guides/errors#payload_too_large",
    "request_id": "req_daebbbfee6c4b693a2bbb79432"
  }
}

POST /v1/tasks/{task}/attachments · 422 task_attachment_rejected

{
  "error": {
    "type": "invalid_request_error",
    "code": "task_attachment_rejected",
    "message": "El tipo de fichero «application/x-msdownload» no está permitido.",
    "param": "file",
    "doc_url": "https://docs.factuarea.com/guides/errors#task_attachment_rejected",
    "request_id": "req_f4ab6a1237cb1feb30c673b38e"
  }
}

POST /v1/tasks/{task}/attachments · 422 invalid_upload_link_note

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid_value",
    "subcode": "invalid_upload_link_note",
    "message": "La nota no puede superar 1.000 caracteres.",
    "param": "note",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid_value",
    "request_id": "req_61dd7ccd5f903aaf96da6e743a"
  }
}

POST /v1/tasks/{task}/attachments · 422 invalid_param_value

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param_value",
    "message": "Adjunta un fichero en el campo file.",
    "param": "file",
    "doc_url": "https://docs.factuarea.com/guides/errors#invalid_param_value",
    "request_id": "req_1564da43ed9b63392ddc304301"
  }
}

POST /v1/tasks/{task}/attachments · 422 idempotency_key_required

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_required",
    "message": "La operación «public-api.v1.tasks.attachments.create» exige la cabecera Idempotency-Key desde el 2026-11-02. 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_ec65c9274ae7eabd9b9c66656b"
  }
}

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

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

Subir un adjunto de tarea

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`

`application/json`

Subir un adjunto de tarea

Authorization

Parámetros de ruta

Headers

Cuerpo de la petición

Cuerpo de la respuesta

201application/json

401application/json

402application/json

403application/json

404application/json

409application/json

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

`application/json`