Importar tasques a un projecte

Importa tasques a un projecte des d'un document JSON (factuarea.tasks.v1, o una exportació d'altres eines de tasques en un format admès).

La importació és només síncrona i accepta fins a 200 tasques per crida: més de 200 retorna 422, així que divideix el fitxer.
L'informe llista, per tasca, el seu index al document, l'id i la key creats o l'error que ho va impedir; no té mode ni run_id perquè l'API no crea importacions en segon pla.
Requereix només projects:write: crea tasques i comentaris encara que la clau no tingui tasks:write.
Requereix una Idempotency-Key.

Clau opaca generada pel client (fins a 255 caràcters; es recomana UUID v7) que permet reintents segurs: la primera resposta s'emmagatzema i es reprodueix en les repeticions sense tornar a executar la mutació. Reutilitzar una clau amb un cos diferent retorna 409 idempotency_key_reused. Consulta la guia d'idempotència. Obligatòria en aquesta operació: repetir-la produeix un efecte irreversible (un correu enviat, un fitxer generat, una crida a un tercer o un càrrec), per la qual cosa una petició sense aquesta capçalera es rebutja amb 422 idempotency_key_required abans d'executar lògica de negoci.

Longitud1 <= length <= 255

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

application/json

Definicions de TypeScript

Usa el tipus request body a TypeScript.

format?string

Format del document: factuarea.tasks.v1, el format que produeix GET /v1/projects/{project}/tasks/export. Es pot ometre quan el document és un fitxer JSON {project, tasks} exportat des d'un altre gestor de tasques, que també s'accepta.

project?

Dades del projecte d'origen (key, name, description i columns), tal com apareixen al document exportat.

tasks*array<>

Tasques que cal importar: entre 1 i 200 per petició. Cada element és un objecte que descriu una tasca. Els problemes dins d'una tasca mai rebutgen la petició: s'informen per tasca, com a avisos o com a una entrada fallida, a la resposta.

Elements1 <= items <= 200

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

Exemple de resposta

{
  "data": {
    "object": "project_tasks_import",
    "project_id": "0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01",
    "total": 3,
    "created": 2,
    "failed": 1,
    "warnings": [
      {
        "index": null,
        "message": "El color de la columna «QA» no es válido: se crea sin color."
      },
      {
        "index": 1,
        "message": "La prioridad «critical» no existe: se usa «none»."
      }
    ],
    "tasks": [
      {
        "index": 0,
        "id": "0193a4f2-8f53-7d44-8e85-7a9b1c3d5f17",
        "key": "DEV-17",
        "error": null
      },
      {
        "index": 1,
        "id": "0193a4f2-8f53-7d44-8e85-7a9b1c3d5f18",
        "key": "DEV-18",
        "error": null
      },
      {
        "index": 2,
        "id": null,
        "key": null,
        "error": "El título de la tarea no puede estar vacío."
      }
    ]
  }
}

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

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

{
  "error": {
    "type": "not_found_error",
    "code": "project_not_found",
    "message": "Proyecto no encontrado.",
    "doc_url": "https://docs.factuarea.com/guides/errors#project_not_found",
    "request_id": "req_cf4a0708f559ffafcda771265b"
  }
}

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

POST /v1/projects/{project}/tasks/import · 422 project_archived

{
  "error": {
    "type": "invalid_request_error",
    "code": "project_archived",
    "message": "El proyecto está archivado: no admite tareas nuevas ni movimientos hacia él.",
    "param": "project_id",
    "doc_url": "https://docs.factuarea.com/guides/errors#project_archived",
    "request_id": "req_5b1340e23cef581e9a15e9d274"
  }
}

POST /v1/projects/{project}/tasks/import · 422 project_has_no_columns

{
  "error": {
    "type": "invalid_request_error",
    "code": "project_has_no_columns",
    "message": "El proyecto no tiene columnas; crea una o usa el estado «planned» o «archived».",
    "param": "status",
    "doc_url": "https://docs.factuarea.com/guides/errors#project_has_no_columns",
    "request_id": "req_7ab1b814cc921e19de355eda1c"
  }
}

POST /v1/projects/{project}/tasks/import · 422 invalid_task_import_payload

{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid_value",
    "subcode": "invalid_task_import_payload",
    "message": "El fichero supera el máximo de 200 tareas; usa la importación en segundo plano desde Importaciones.",
    "param": "file",
    "doc_url": "https://docs.factuarea.com/guides/errors#parameter_invalid_value",
    "request_id": "req_daa3f9f87e8e1cf2610f4e1770"
  }
}

POST /v1/projects/{project}/tasks/import · 422 idempotency_key_required

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

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

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

Importar tasques a un projecte

Authorization

Paràmetres de ruta

Headers

Cos de la petició

Cos de la resposta

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Importar tasques a un projecte

Authorization

Paràmetres de ruta

Headers

Cos de la petició

Cos de la resposta

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`