Las operaciones recientes pasan al eje

5 de octubre de 2026 — las operaciones que llegaron a la API desde el 21 de septiembre se publicaron en rutas planas, antes de que existiera el eje de empresa. Ahora viven donde vive cualquier otro recurso de empresa, bajo /v1/companies/{company}/…: las operaciones de las tablas de abajo. Es la misma migración que la ventana del eje, aplicada a lo que vino después, y no necesita un segundo paso.

• Sin alias plano. Una llamada a la ruta antigua responde el 404 estándar de una ruta que no existe. Usa la ruta de la columna Ahora.
• Nada más cambia por defecto. Los nombres de ruta (public-api.v1.*), los scopes, los cuerpos y las respuestas siguen como se publicaron, salvo lo que indican las secciones siguientes: ocho verbos, unas pocas rutas que cambian más que el prefijo, un puñado de estados de error y una versión de payload de webhook.
• La empresa sale de la credencial. El segmento {company} se valida contra el ámbito de la credencial: 403 company_inactive si el NIF está inactivo y 404 profile_not_found si queda fuera del ámbito, no existe o es del otro entorno. Los tres 404 son iguales a propósito.
• Location lleva el eje. Las altas de POST …/tasks, …/tasks/{task}/duplicate, …/projects, …/task-labels y POST …/verifactu/representation responden /v1/companies/{company}/<recurso>/<id>.

Verbos: PUT pasa a PATCH

Las actualizaciones parciales de las familias nuevas siguen la convención del resto de la API: PATCH cambia solo los campos que envías. PUT se queda donde el recurso entero se reemplaza por diseño.

Siguen en PUT, porque reemplazan el recurso entero: projects.columns.reorder, tasks.comments.update y tasks.custom_fields.set. Un PUT a una de las ocho rutas migradas responde 405.

Editar una serie conserva el mismo cuerpo parcial y las mismas guardas fiscales (BR-SER-020, BR-SER-021, 422 con su subcode). En …/series/{series}, el 405 series_immutable lleva ahora Allow: GET, PATCH y su mensaje remite a PATCH /v1/companies/{company}/series/{id} y a POST …/archive; PUT y DELETE responden 405. La tool MCP update_series es la misma tool, descrita como un PATCH parcial; sus argumentos no cambian.

Rutas que cambian más que el prefijo

Dos consecuencias visibles: el source_url de las respuestas del escáner y el error_report_url de las importaciones de contactos llevan ahora el eje. El límite de subida de 101 MB del escáner se aplica a POST /v1/companies/<uuid>/purchase-scans.

Códigos y estados de error

El 409 idempotency_key_in_use (la clave está en curso) no cambia.

Las operaciones planas /v1/clients y /v1/suppliers y las tools MCP *_client y *_supplier siguen retiradas; los contactos las sustituyen bajo /v1/companies/{company}/contacts. Los nombres de tool search_clients, find_client_by_tax_id, create_client y bulk_create_clients siguen resolviendo a las tools de contactos hasta el 15 de noviembre de 2026, marcados con _meta["io.factuarea/deprecation"].

Versión de payload de los webhooks

Las versiones de payload son ahora 2026-05-22, 2026-10-01 y 2026-10-05 (la más reciente). 2026-10-01 es la que introdujo el vocabulario issued de las facturas; 2026-10-05 añade importes como cadena decimal y paid_recorded_at y paid_date. Un endpoint fijado a 2026-10-01 o 2026-05-22 no cambia: sigue recibiendo importes numéricos, paid_at y paid_on. Un endpoint creado sin api_version explícito queda en 2026-05-22, salvo que la petición que lo crea use la versión REST 2026-10-01: entonces toma la más reciente (2026-10-05). Puedes mover un endpoint existente con PATCH y api_version. La versión de petición Factuarea-Version: 2026-10-01 mantiene su fecha y su efecto. Consulta Versiones de payload de los webhooks.

MCP

Las tools no llevan argumento de empresa: la empresa sale del token o de la sesión. Las tools de proyectos y tareas, notificaciones, usuarios, agenda, el escáner, la representación VeriFactu, issue_invoice, list_purchase_invoice_expense_categories y las importaciones de contactos (get_contact_import, download_contact_import_errors) espejan una a una las rutas de las tablas de abajo. Un error de dominio de tools/call es ahora un resultado con isError: true, el mensaje del dominio y _meta["com.factuarea/error"] (code, subcode, param, con el mismo estado que la REST API).

Otros cambios de contrato

• Plantillas de importación de contactos. GET /v1/companies/{company}/contacts/import/template acepta format: csv (por defecto, separado por ;) o xlsx, un libro con las hojas Datos, Instrucciones, Ejemplos y Valores permitidos. Ambos salen de los mismos descriptores de columna que el importador.
• Informes de importación. El recurso de importación (GET …/contacts/imports/{id} y la respuesta de POST …/contacts/import) añade updated_count, warnings_count, outcome_kind, skip_reasons, first_diagnostics y outcomes_truncated, y cada fila de outcomes lleva un reason. outcome_kind: nothing_changed significa que la importación terminó sin crear ni actualizar nada: no la presentes como un éxito. El código nuevo mapping_header_not_found lo devuelven contacts.import y contacts.preview_import.
• Documentos de venta. Las facturas (y sus eventos) publican origin (native o historical_import); los presupuestos y las proformas publican reference y operation_regime.
• Importación de tareas. POST …/projects/{project}/tasks/import y la tool MCP import_project_tasks aceptan un idempotency_key opcional e informan warnings_total y warnings_truncated.
• Escrituras del escáner sin acceso. En las escrituras del escáner de gastos (POST …/purchase-scans, …/retry, PATCH …/review, …/duplicate-resolution, …/convert, DELETE …/{purchase_scan}, …/restore), una clave cuyo creador no tiene acceso a la empresa responde ahora 404 profile_not_found en lugar de 403 api_key_creator_not_member. El 403 se mantiene en la descarga del original (GET …/source) y en las tools MCP de escritura.
• Importes de cobro en la actividad. En GET …/invoices/{invoice}/activities (y la tool get_invoice_activities), metadata.amount de los eventos payment.payment_created y payment.payment_reversed es ahora una cadena de dos decimales ("50.50"), no un número en euros.

Todas las operaciones, por familia

Proyectos y tareas

Tareas, proyectos, etiquetas, temporizadores y la agenda (75).

Escáner de gastos

El escáner de gastos y su buzón (12). Los segmentos van en kebab-case.

Notificaciones

Las notificaciones de quien posee la credencial (3).

VeriFactu: representación y registros bloqueados

Representación y reintento de los registros bloqueados (4).

Facturas, importaciones de contactos, usuarios, categorías de gasto y series

(7)