Les operacions recents passen a l'eix

5 d'octubre de 2026 — les operacions que han arribat a l'API des del 21 de setembre es van publicar en rutes planes, abans que existís l'eix d'empresa. Ara viuen on viu qualsevol altre recurs d'empresa, sota /v1/companies/{company}/…: les operacions de les taules de sota. És la mateixa migració que la finestra de l'eix, aplicada al que ha vingut després, i no necessita un segon pas.

• Sense àlies pla. Una crida a la ruta antiga respon el 404 estàndard d'una ruta que no existeix. Fes servir la ruta de la columna Ara.
• Res més canvia per defecte. Els noms de ruta (public-api.v1.*), els scopes, els cossos i les respostes continuen com es van publicar, tret del que indiquen les seccions següents: vuit verbs, unes poques rutes que canvien més que el prefix, un grapat d'estats d'error i una versió de payload de webhook.
• L'empresa surt de la credencial. El segment {company} es valida contra l'àmbit de la credencial: 403 company_inactive si el NIF està inactiu i 404 profile_not_found si queda fora de l'àmbit, no existeix o és de l'altre entorn. Els tres 404 són iguals a propòsit.
• Location porta l'eix. Les altes de POST …/tasks, …/tasks/{task}/duplicate, …/projects, …/task-labels i POST …/verifactu/representation responen /v1/companies/{company}/<recurs>/<id>.

Verbs: PUT passa a PATCH

Les actualitzacions parcials de les famílies noves segueixen la convenció de la resta de l'API: PATCH canvia només els camps que envies. PUT es queda on el recurs sencer es reemplaça per disseny.

Continuen en PUT, perquè reemplacen el recurs sencer: projects.columns.reorder, tasks.comments.update i tasks.custom_fields.set. Un PUT a una de les vuit rutes migrades respon 405.

Editar una sèrie conserva el mateix cos parcial i les mateixes guardes fiscals (BR-SER-020, BR-SER-021, 422 amb el seu subcode). A …/series/{series}, el 405 series_immutable porta ara Allow: GET, PATCH i el seu missatge remet a PATCH /v1/companies/{company}/series/{id} i a POST …/archive; PUT i DELETE responen 405. La tool MCP update_series és la mateixa tool, descrita com un PATCH parcial; els seus arguments no canvien.

Rutes que canvien més que el prefix

Dues conseqüències visibles: el source_url de les respostes de l'escàner i l'error_report_url de les importacions de contactes porten ara l'eix. El límit de pujada de 101 MB de l'escàner s'aplica a POST /v1/companies/<uuid>/purchase-scans.

Codis i estats d'error

El 409 idempotency_key_in_use (la clau és en curs) no canvia.

Les operacions planes /v1/clients i /v1/suppliers i les tools MCP *_client i *_supplier continuen retirades; els contactes les substitueixen sota /v1/companies/{company}/contacts. Els noms de tool search_clients, find_client_by_tax_id, create_client i bulk_create_clients continuen resolent a les tools de contactes fins al 15 de novembre de 2026, marcats amb _meta["io.factuarea/deprecation"].

Versió de payload dels webhooks

Les versions de payload són ara 2026-05-22, 2026-10-01 i 2026-10-05 (la més recent). 2026-10-01 és la que va introduir el vocabulari issued de les factures; 2026-10-05 afegeix imports com a cadena decimal i paid_recorded_at i paid_date. Un endpoint fixat a 2026-10-01 o 2026-05-22 no canvia: continua rebent imports numèrics, paid_at i paid_on. Un endpoint creat sense api_version explícit queda a 2026-05-22, tret que la petició que el crea faci servir la versió REST 2026-10-01: llavors pren la més recent (2026-10-05). Pots moure un endpoint existent amb PATCH i api_version. La versió de petició Factuarea-Version: 2026-10-01 manté la seva data i el seu efecte. Consulta Versions de payload dels webhooks.

MCP

Les tools no porten argument d'empresa: l'empresa surt del token o de la sessió. Les tools de projectes i tasques, notificacions, usuaris, agenda, l'escàner, la representació VeriFactu, issue_invoice, list_purchase_invoice_expense_categories i les importacions de contactes (get_contact_import, download_contact_import_errors) emmirallen una a una les rutes de les taules de sota. Un error de domini de tools/call és ara un resultat amb isError: true, el missatge del domini i _meta["com.factuarea/error"] (code, subcode, param, amb el mateix estat que la REST API).

Altres canvis de contracte

• Plantilles d'importació de contactes. GET /v1/companies/{company}/contacts/import/template accepta format: csv (per defecte, separat per ;) o xlsx, un llibre amb els fulls Dades, Instruccions, Exemples i Valors permesos. Tots dos surten dels mateixos descriptors de columna que l'importador.
• Informes d'importació. El recurs d'importació (GET …/contacts/imports/{id} i la resposta de POST …/contacts/import) afegeix updated_count, warnings_count, outcome_kind, skip_reasons, first_diagnostics i outcomes_truncated, i cada fila d'outcomes porta un reason. outcome_kind: nothing_changed vol dir que la importació ha acabat sense crear ni actualitzar res: no la presentis com un èxit. El codi nou mapping_header_not_found el retornen contacts.import i contacts.preview_import.
• Documents de venda. Les factures (i els seus esdeveniments) publiquen origin (native o historical_import); els pressupostos i les proformes publiquen reference i operation_regime.
• Importació de tasques. POST …/projects/{project}/tasks/import i la tool MCP import_project_tasks accepten un idempotency_key opcional i informen warnings_total i warnings_truncated.
• Escriptures de l'escàner sense accés. En les escriptures de l'escàner de despeses (POST …/purchase-scans, …/retry, PATCH …/review, …/duplicate-resolution, …/convert, DELETE …/{purchase_scan}, …/restore), una clau el creador de la qual no té accés a l'empresa respon ara 404 profile_not_found en lloc de 403 api_key_creator_not_member. El 403 es manté a la descàrrega de l'original (GET …/source) i a les tools MCP d'escriptura.
• Imports de cobrament a l'activitat. A GET …/invoices/{invoice}/activities (i la tool get_invoice_activities), metadata.amount dels esdeveniments payment.payment_created i payment.payment_reversed és ara una cadena de dos decimals ("50.50"), no un nombre en euros.

Totes les operacions, per família

Projectes i tasques

Tasques, projectes, etiquetes, temporitzadors i l'agenda (75).

Escàner de despeses

L'escàner de despeses i la seva bústia (12). Els segments van en kebab-case.

Notificacions

Les notificacions de qui posseeix la credencial (3).

VeriFactu: representació i registres bloquejats

Representació i reintent dels registres bloquejats (4).

Factures, importacions de contactes, usuaris, categories de despesa i sèries

(7)