Projectes i tasques

Factuarea inclou un mòdul de tasques natiu: projectes amb un tauler de columnes i tasques que es poden vincular a les factures, els pressupostos, els contactes i la resta de documents de la teva empresa. L'API l'exposa sota /v1/projects, /v1/tasks, /v1/task-labels, /v1/task-timers, /v1/users, /v1/notifications i /v1/agenda. Cada operació és també una tool MCP i una comanda del CLI.

Projectes i claus

Un projecte agrupa tasques i és propietari del tauler on viuen. La seva clau del projecte —una lletra majúscula seguida de fins a nou lletres majúscules o dígits, com DEV— prefixa la clau de cada tasca: DEV-1, DEV-2… Les claus són úniques a la teva empresa, sense distingir majúscules i comptant els projectes arxivats. Una clau que ja és en ús retorna 409 project_key_in_use.

curl -X POST https://api.factuarea.com/v1/projects \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Web redesign",
    "key": "WEB",
    "icon": "rocket",
    "description": "Storefront redesign and follow-up fixes."
  }'

El projecte es crea amb les seves columnes de tauler per defecte i es retorna amb les seves estadístiques de tasques (total_tasks, completed_tasks, completion_percentage i next_due_on).

• GET /v1/projects llista els projectes en l'ordre en què els mostra l'app. Els projectes arxivats queden fora tret que passis include_archived=true.
• POST /v1/projects/find-by-key resol un projecte a partir de la seva clau (WEB), sense distingir majúscules i sigui arxivat o no. És una lectura: no necessita Idempotency-Key.
• PUT /v1/projects/{project} és parcial. Canviar la key conserva l'anterior com a àlies, de manera que les tasques continuen responent a les seves claus antigues. Aquí també viuen els valors de facturació per defecte per facturar el temps imputat: consulta Temps imputat a tasques.
• POST /v1/projects/{project}/archive i .../unarchive són reversibles: un projecte arxivat surt dels llistats per defecte i deixa d'acceptar tasques noves (422 project_archived), però tot continua sent consultable.
• DELETE /v1/projects/{project} és permanent i s'endú les tasques, els comentaris, els adjunts i el temps imputat del projecte.

Columnes i estat del tauler

Una tasca sempre és en un de tres estats de tauler:

planned i archived són estats virtuals, no columnes, i els seus noms estan reservats: una columna no els pot fer servir com a slug (422 column_slug_reserved).

Un projecte nou rep quatre columnes —per fer, en curs, en revisió i fet— amb el nom en l'idioma de qui el crea i els slugs canònics to-do, in-progress, in-review i done. Només l'última és una columna final (is_final: true): moure una tasca a una columna final la completa (es fixa completed_at) i treure-la'n la reobre.

• POST /v1/projects/{project}/columns afegeix una columna al final del tauler. El seu slug es deriva del nom i és únic al projecte (409 column_slug_in_use). color és una clau de la paleta (gray, red, orange, amber, green, teal, blue, cyan, violet o pink) o un codi hexadecimal.
• PUT .../columns/{column} és parcial. Convertir una columna en final completa les tasques que conté; tornar-li-ho a treure les reobre.
• PUT .../columns/reorder rep column_ids amb totes les columnes del projecte exactament una vegada, en l'ordre nou.
• Les columnes es retornen com una llista simple, sense paginació.

Esborrar una columna amb tasques

Esborrar una columna és permanent, i una columna amb tasques necessita un destí per a elles. Indica la columna de destinació del mateix projecte al paràmetre de query move_to_column_id:

curl -X DELETE \
  "https://api.factuarea.com/v1/projects/$PROJECT_ID/columns/$COLUMN_ID?move_to_column_id=$OTHER_COLUMN_ID" \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

En una sola transacció les tasques passen al final de la columna de destinació, en el seu ordre, cadascuna emet el seu esdeveniment task.status_changed i la columna s'esborra. Sense move_to_column_id, una columna que encara té tasques retorna 409 column_has_tasks i no canvia res; una destinació que no existeix, que és d'un altre projecte o que és la mateixa columna que s'esborra retorna 422 invalid_move_target_column. Una columna buida no necessita destinació. L'operació és irreversible, així que Idempotency-Key és obligatòria.

Tasques, claus i tauler

project_id i title són els únics camps obligatoris de POST /v1/tasks. Una tasca neix a la primera columna del seu projecte tret que enviïs un column_id o un status virtual. Els camps opcionals són description (Markdown), priority (none, low, medium, high o urgent; none per defecte), start_on i due_on (YYYY-MM-DD; un start_on posterior a due_on retorna 422 invalid_task_schedule), assignee_id (un membre de la teva empresa), label_ids, custom_fields i entity_link.

curl -X POST https://api.factuarea.com/v1/tasks \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "0193a4f2-7c20-7a11-8b52-4d6e8f0a2c01",
    "title": "Call the customer about the checkout demo",
    "priority": "high",
    "due_on": "2026-10-15",
    "assignee_id": "0193a4f2-6b1c-7d3e-8a41-2c5e7f9a1b02",
    "label_ids": ["0193a4f2-9a64-7e55-8f96-8b0c2d4e6a02"],
    "custom_fields": { "0193a4f2-7e42-7c33-8d74-6f8a0b2c4e01": 4 },
    "entity_link": { "type": "quote", "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a4d" }
  }'

La tasca es retorna amb la seva clau (DEV-16), el seu number al projecte, el seu status de tauler i el seu column_id, les seves etiquetes, els valors dels seus camps personalitzats i comptadors de subtasques, comentaris i adjunts. El número només creix: una tasca esborrada mai no allibera el seu número per reutilitzar-lo.

Resoldre una tasca per la seva clau

La gent parla de DEV-12, no d'un UUID. POST /v1/tasks/find-by-key rep { "key": "DEV-12" }, sense distingir majúscules, i retorna la tasca. Les claus anteriors continuen funcionant: una tasca moguda de DEV-12 a un altre projecte, o el projecte de la qual ha canviat de clau, continua trobant-se amb la clau antiga. Una clau mal formada retorna 422 invalid_task_key i una de desconeguda 404 task_not_found. El filtre q de la cerca també accepta una clau.

Cercar

GET /v1/tasks cerca en tots els projectes:

curl "https://api.factuarea.com/v1/tasks?project_id=$PROJECT_ID&status=active&assignee_id=me&sort=due_on&limit=50" \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Els filtres són q, project_id, status, column_id, priority, assignee_id (l'UUID d'un membre o me), label_id, due_before, due_after i completed. sort admet created_at, updated_at, due_on, priority o number, amb el prefix - per a l'ordre descendent.

Estat, posició i moviment

• POST /v1/tasks/{task}/status mou una tasca a un column_id del seu projecte o a un status virtual, al final de la destinació.
• POST /v1/tasks/{task}/reposition la col·loca en una posició exacta: un index (0 és el primer) o una veïna, before_task_id o after_task_id, i opcionalment una altra columna a la mateixa crida.
• POST /v1/tasks/{task}/move l'envia a un altre projecte. La tasca hi rep una clau nova i continua responent a l'anterior; els valors de camps personalitzats que la destinació no defineix es descarten.
• POST /v1/tasks/{task}/duplicate la copia al final de la mateixa columna. La còpia conserva descripció, prioritat, dates, etiquetes, valors de camps personalitzats i persona assignada; els comentaris, l'activitat, les imputacions de temps i els vincles no es copien.
• POST /v1/tasks/{task}/assign i .../unassign fixen i treuen la persona assignada. Consulta els ids dels membres amb GET /v1/users; un usuari que no és membre retorna 422 task_assignee_not_member.

Editar i esborrar

PUT /v1/tasks/{task} és parcial: només canvien els camps que envies, i un null explícit buida description, start_on, due_on i assignee_id. priority i title no poden ser null.

DELETE /v1/tasks/{task} és permanent. S'endú els comentaris, els adjunts, les relacions i les imputacions de temps de la tasca, i és irreversible: Idempotency-Key és obligatòria.

Operacions massives

Tres operacions actuen sobre fins a 200 tasques alhora, tot o res: POST /v1/tasks/bulk-status, POST /v1/tasks/bulk-update (prioritat, persona assignada, data de venciment i una etiqueta que afegir o treure) i POST /v1/tasks/bulk-delete. Les tres exigeixen una Idempotency-Key. Una selecció més gran retorna 422 bulk_task_selection_too_large; les tasques que ja no existeixen s'ometen i el resultat indica quantes han canviat. Consulta Operacions en lot.

Etiquetes, comentaris, relacions i camps personalitzats

Les etiquetes de tasca viuen en un catàleg per empresa i no tenen relació amb les etiquetes dels documents: consulta Etiquetes i camps personalitzats per a aquestes últimes. Una etiqueta té un name, únic a la teva empresa sense distingir majúscules (409 task_label_name_in_use), i un color de la paleta o un codi hexadecimal. El catàleg llista cada etiqueta amb el seu tasks_count: quantes tasques la porten, incloses les arxivades. POST /v1/tasks/{task}/labels afegeix una etiqueta a una tasca i DELETE .../labels/{label} la treu; esborrar una etiqueta del catàleg la treu de totes les tasques.

Els comentaris són Markdown, d'1 a 10.000 caràcters. Les mencions a membres de l'empresa notifiquen les persones esmentades; les mencions a qualsevol altra persona s'ignoren. L'author d'un comentari té un type: user, external (sincronitzat des d'una forja de codi), imported o automation. Només qui l'ha escrit pot editar un comentari, i els sincronitzats o importats no es poden editar (422 task_comment_not_editable); poden esborrar-lo qui l'ha escrit i els rols owner i admin de l'empresa.

Les relacions uneixen dues tasques de l'empresa com a subtask, blocks o related. Una tasca no es pot relacionar amb ella mateixa (422 task_self_relation), una relació que tancaria un cicle es rebutja (422 task_relation_cycle) i un duplicat retorna 409 task_relation_exists. El llistat mostra cada relació des del punt de vista de la tasca de la ruta, mitjançant direction: parent, child, blocks, blocked_by o related. Esborrar una relació deixa intactes les dues tasques.

Els camps personalitzats de tasca es defineixen per projecte, amb un type de text, number, date, dropdown, boolean o multiselect, i no són els camps personalitzats dels documents. Un camp obligatori necessita un valor per defecte no buit, que reben les tasques existents. Fixa els valors en crear la tasca, amb el mapa custom_fields (id del camp a valor), o més tard amb PUT /v1/tasks/{task}/custom-fields/{field}; null buida un camp opcional. Un valor que no encaixa amb el tipus retorna 422 invalid_custom_field_value, i una definició que es contradiu, o una edició que deixaria orfes valors existents, 422 invalid_custom_field_definition. Esborrar una definició n'esborra els valors a totes les tasques del projecte.

Vincles amb documents, contactes i altres eines

Una tasca pot apuntar a la resta de Factuarea. El vocabulari d'entitats vinculables és tancat: invoice, quote, proforma, delivery_note, purchase_invoice, recurring_invoice, contact, product i employee.

• En crear-la, entity_link vincula la tasca a la mateixa transacció. Si l'entitat no existeix, és d'una altra empresa o el seu mòdul no és accessible, la crida retorna 404 linked_entity_not_found i la tasca no es crea.
• Després, POST /v1/tasks/{task}/entity-links la vincula; vincular la mateixa entitat una altra vegada retorna el vincle existent. Un vincle amb una entitat que s'ha esborrat continua al llistat amb available: false.
• Des de l'entitat, GET /v1/tasks/linked?entity_type=invoice&entity_id=… llista les tasques vinculades a una factura, un pressupost o qualsevol altra entitat, amb les arxivades marcades.
• Els enllaços externs —POST /v1/tasks/{task}/external-links— adjunten una adreça http o https sense més. Els enllaços que reflecteixen una issue, una pull request o una branca d'una forja de codi (GitHub, GitLab o Gitea) els manté la integració.

Adjunts i enllaços de pujada

POST /v1/tasks/{task}/attachments puja un fitxer com a multipart/form-data. El màxim és de 10 MB per fitxer i el tipus es comprova per contingut, mai per extensió: imatges (PNG, JPEG, GIF, WebP, HEIC, AVIF), PDF, documents de Word, Excel i PowerPoint, text i fulls de càlcul OpenDocument, text pla, CSV, Markdown i ZIP. target col·loca el fitxer en un comentari nou (comment, el valor per defecte) o al final de la descripció (description), i note passa a ser el text del comentari. Els fitxers compten per a la quota d'emmagatzematge del pla (402 storage_quota_exceeded quan és plena) i la pujada necessita una Idempotency-Key.

Per rebre una foto des d'un mòbil, o un fitxer d'algú sense compte, crea un enllaç de pujada amb POST /v1/tasks/{task}/upload-links. L'enllaç és d'un sol ús, caduca als 30 minuts i la seva url es mostra només en aquesta resposta. Un cop usat o caducat respon 410 task_upload_link_expired.

Els adjunts es llisten, es consulten i es descarreguen per tasca, i DELETE .../attachments/{attachment} elimina el fitxer per sempre i n'allibera l'emmagatzematge.

Activitat

GET /v1/tasks/{task}/activities retorna el registre d'activitat, del més recent al més antic: canvis d'estat i de columna, edicions amb els camps canviats, assignacions, etiquetes, comentaris, relacions, adjunts i temps imputat, cadascun amb el seu actor (user, api_key, external o system). Les entrades no tenen id, així que el cursor és opac: retorna el next_cursor com a starting_after sense tocar-lo.

Paginació, actualitzacions parcials i errors

• Paginació per cursor. Els llistats de projectes, tasques, etiquetes, comentaris, imputacions de temps, usuaris, notificacions i activitat retornen { data, has_more, next_cursor }; passa next_cursor com a starting_after per a la pàgina següent. Les columnes, les definicions de camps personalitzats, les relacions, els vincles i els adjunts són curts i es retornen com una llista simple. Consulta Paginació.
• PUT és parcial a tot arreu: els camps omesos conserven el seu valor i un null explícit buida els opcionals.
• Idempotència. Les nou operacions irreversibles, les operacions massives, la importació i la pujada de fitxers exigeixen una Idempotency-Key; qualsevol altra escriptura l'accepta. Consulta Idempotència.
• Errors. Cada error de tasques té un codi estable, llistat a Codis d'error de Tasques.

Propers passos