One breaking window: axis and payload

30 September 2026 — the v1 contract breaks in five places at once, and this entry announces all five together because they are one migration: the code you touch for any of them is the code you touch for the other four. No second window follows.

• The axis travels in the URL. A company resource now lives under /v1/companies/{company}/… and an account resource under /v1/accounts/{account}/…. The effective company stops being deduced from the credential and rides in the path, where it is visible, logged and auditable.
• Amounts travel as decimal strings. Every monetary field of a published payload is a string, no longer a JSON number.
• The collection date changed name. paid_at and paid_on are gone from the published payload. An invoice and a purchase invoice publish paid_recorded_at and paid_date.
• X-Active-Profile is retired. A request that still carries the header is rejected with 400 parameter_unknown, subcode retired_active_profile_header, before it reaches the controller.
• The account becomes the customer. A tax ID changes hands with a transfer (nif-transfers), the people of an account are members with grants per tax ID, an extra tax ID is an additional tax ID (paid_until replaces seat_paid_until, and three error codes change name), and the API keys issued per company and the writes of the tax catalog are retired.

This page lists every operation the window touches, resource by resource: 519 rows in all — 49 new, 294 moved to the axis with only their route changed, 161 moved with additional changes, 11 retired and 4 untouched. A route is its verb and its path, so the thirty-three operations of the verb table count as moved even when nothing else about them changed. The contract that comes out of it, together with the operations that joined the axis later, publishes 664 live operations across 51 resources, and every count on this page is derived from that contract, not from a summary of it.

Where the company id comes from

The company segment takes the opaque id of the company, never its tax id. GET /v1/me publishes one entry per tax ID your credential reaches, and its id is exactly what goes in the path:

{
  "data": {
    "object": "me",
    "account": {
      "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a00",
      "name": "Asesoría Martínez",
      "environment": "live",
      "is_provider": true,
      "privileged_scopes": [
        "accounts:read",
        "accounts:write"
      ]
    },
    "api_key": {
      "id": "019e81ef-e1d4-7208-a51d-94c2c2a54a84",
      "name": "Producción",
      "prefix": "fact_live_1OSf9KdP",
      "scopes": [
        "account:read",
        "series:read",
        "series:write"
      ],
      "tier": "scale",
      "environment": "live",
      "created_at": "2026-01-15T09:30:00Z",
      "last_used_at": "2026-05-25T18:00:00Z",
      "expires_at": null
    },
    "scope": [
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a01",
        "tax_id": "B12345674",
        "name": "Acme Corporation"
      },
      {
        "id": "01931b3e-7c4a-7f2e-9a8b-3c5d6e7f8a02",
        "tax_id": "B87654323",
        "name": "Acme Logística S.L."
      }
    ],
    "client_accounts": [
      {
        "id": "0199a1f0-1c22-7a10-b111-5a5b5c5d5e5f",
        "name": "Construcciones Ruiz",
        "origin": "granted",
        "access_level": "view",
        "status": "active",
        "paid_by_provider": false,
        "environment": "live"
      },
      {
        "id": "0199a1f0-1c22-7a10-b111-6a6b6c6d6e6f",
        "name": "Talleres García",
        "origin": "provisioned",
        "access_level": "operate",
        "status": "provisioned",
        "paid_by_provider": true,
        "environment": "live"
      }
    ],
    "client_accounts_visible": true,
    "client_accounts_has_more": false
  }
}

GET /v1/me is itself the replacement of GET /v1/account, which no longer exists, and it needs no scope: any valid credential can introspect itself. data.account.id is what goes in the account segment; each data.scope[].id is what goes in the company segment. When your account provisions managed accounts, or other accounts granted it access, data.client_accounts[] lists the client accounts it reaches, with their origin, access_level and status and whether your account pays them. It is filled only when the key carries the privileged accounts:read scope: without it the list is empty and client_accounts_visible is false. Call it once at startup and cache the mapping — it is stable.

Company axis — /v1/companies/{company}/<resource>

44 resource families, 359 routes and 432 of the window's operations hang from the company segment:

Account axis — /v1/accounts/{account}/<resource>

The account segment takes the id of your own account, data.account.id of GET /v1/me; on a closed list of routes it also takes the id of a managed account of yours. 16 resource families, 49 routes and 65 of the window's operations hang from it:

claim-tokens keeps its place in the table, but it is no longer the tax ID transfer: POST /v1/accounts/{account}/claim-tokens reissues the claim voucher of a managed account. The transfer is nif-transfers, and its scopes and codes are renamed the same way: nif_transfers:read, nif_transfers:write, nif_transfer_expired and nif_transfer_invalid. The claim-tokens transfer routes, the claim_tokens:* scopes and the claim_token_* codes of pre-release builds of this contract do not exist in the final one.

Root — no axis at all

Ten routes belong neither to a company nor to the axis of your own account, and together they carry eleven operations. Five of them are introspection and catalogs, and only one moved: GET /v1/me replaces GET /v1/account. The other five are the provisioning root, new in this window: there the resource is a managed account or a bulk import, so it hangs from no axis.

The contract itself, /v1/openapi.json, also stays where it is.

Five traps worth reading before you rewrite a URL

1. Underscore becomes hyphen. Five resources change their separator as they move: tax_reports, purchase_invoices, recurring_invoices, delivery_notes and webhook_endpoints are now tax-reports, purchase-invoices, recurring-invoices, delivery-notes and webhook-endpoints. Four action segments follow them: dry_run, mark_paid, rotate_secret and test_event are now dry-run, mark-paid, rotate-secret and test-event. No path segment of the contract keeps an underscore.
2. Families you would expect at the root are on the company axis. Holidays, the automations catalog and its per-trigger fields, billing, census verification, personalization, email deliveries, events, request logs and the four document status listings (invoices, quotes, proformas and delivery-notes each publish their own statuses) read like global catalogs and are not: what they answer depends on the company.
3. {company} is not always the axis, and {account} is not always the account. In /v1/accounts/{account}/companies/{company}/… —the tax IDs of a portfolio— and in /v1/accounts/{account}/members/{member}/grants/{company} —the grant of a member on one tax ID—, {company} is the resource being addressed, so you write it even when your credential reaches a single company. And in /v1/companies/{company}/connected-accounts/{account}, {account} is a Stripe connected account. Fourteen operations carry both parameters; tell them apart by the path, never by the name of the parameter.
4. Company webhooks, events, emails, request logs and billing are company resources, not account ones. On the account axis sit API keys, members (with their grants and module access), invitations, tax ID transfers, employee seats, the portfolio of tax IDs, its usage, its owner, the provisioning routes of a managed account and, new in this window, the webhooks and request logs of the account itself: /v1/accounts/{account}/webhooks is not /v1/companies/{company}/webhook-endpoints, and their operations differ. See the account webhooks guide.
5. Under /v1/accounts/{account}/…, {account} is your own account. Only a closed list of routes also accepts the id of a managed account of yours —the provisioning routes and the data of its tax IDs—; any other account id, real or not, answers the same 404 account_not_found. The provisioning root is different: in /v1/accounts and GET /v1/accounts/{account} the account is the resource itself. See the managed accounts guide.

Sixteen operations the window adds

They open the account axis, which had no public surface of its own beyond API keys: the tax ID transfer, the team with its invitations, the ownership, the usage and, under the portfolio, the issuing readiness of a tax ID. They are new routes, so nothing that exists today breaks because of them.

They are not the only new operations. The window publishes 49 in all, and the other thirty-three belong to the account model — provisioning and managed accounts, bulk import, account webhooks and request logs, the grants of a member on each tax ID and the revocation of a transfer, among others. The account model release note describes them, and their rows are in the inventory at the end of this page.

The codes invitation_expired, invitation_not_found, member_is_last_owner, nif_transfer_expired and nif_transfer_invalid are part of the thirty-seven new error codes listed further down.

Eleven operations the window retires

Five of them are the API keys issued per company, which disappear. A key is a credential of the account, not of one of its companies, and the surviving operations say so in the path and in the scope: api_keys:read / api_keys:write give way to account:read / account:write, which is what the account axis already used.

scoped_company_ids is a new body field of POST /v1/accounts/{account}/api-keys: it is where a key is restricted to a subset of the portfolio, which is the job the per-company route used to do.

The tax catalog becomes read-only

The other six retired operations are the writes of the tax catalog. The catalog is shared by the whole platform, so a company credential that edited it edited it for every company; only platform administration writes it now.

They have no replacement. The reads stay: GET /v1/companies/{company}/taxes and its siblings on the company axis, and GET /v1/tax-catalog at the root. A call to a retired write answers 405 method_not_allowed where its path still serves a read, and 404 route_not_found where it does not. The scopes taxes:write and taxes:delete stay in the scope catalog, but no operation requires them any more: granting them gives access to nothing.

Clients and suppliers stay retired

/v1/clients and /v1/suppliers were removed before this window, when canonical contacts landed, and they do not come back on the axis. One tax id is one contact, and the customer and supplier roles accumulate on it:

• Customers: GET /v1/companies/{company}/contacts?roles[]=customer
• Suppliers: GET /v1/companies/{company}/contacts?roles[]=supplier

The clients:* and suppliers:* scope families are replaced by contacts:read, contacts:write and contacts:delete.

Thirty-three operations change verb

Thirty-two of them move from PUT to PATCH: they accepted a partial body already, so the verb was lying. The body does not change; only the method does. The recurring invoice update is one of them — every field is optional and an omitted one is kept. The thirty-third, contacts.restore, becomes POST: it is an action without a body, like archive and unarchive, not a partial update. After this window the only PUT of the contract is a new operation, PUT /v1/accounts/{account}/members/{member}/grants/{company}, which creates or replaces the grant of one member on one tax ID.

Thirty-seven new error codes

The catalog grows from 376 to 410 codes: thirty-seven arrive and three are retired (next section). Thirty of the new ones belong to the account surface, four to the additional tax ID gate, two to the access that the person who issued a key holds on a tax ID, and one to account webhooks.

nif_transfer_expired and nif_transfer_invalid take the place of claim_token_expired and claim_token_invalid, the codes of the claim-tokens transfer of pre-release builds, which no longer exist.

Separately, 190 of the operations that already existed now document a 404 they did not document before: an axis segment that names a company or an account your credential cannot reach answers 404, not 403, so the API never confirms that a company you cannot see exists. Every company-axis operation documents 404 profile_not_found for it; an account you cannot reach answers 404 account_not_found.

Three error codes the window retires

The additional tax ID replaces the per-company seat charge and its plan and module gates, so three codes leave the catalog. Branch on the replacement: the status and the error.type are the same in each pair.

Payload: amounts, dates and coverage

Every amount is a decimal string

123 monetary properties across 40 published schemas changed from JSON number to string: totals, line subtotals, taxes, retentions, surcharges, unit prices and costs, paid and pending amounts, statistics, payout figures, charge previews and the thresholds of the simplified invoice. The string carries two decimals, a point as separator, no thousands separator and no currency symbol; the currency keeps its own currency field. The one exception is the unit_price of a document line, which keeps the four-decimal scale it is stored with ("100.0000"), so that reading a line and sending it back never changes its price; the derived amounts of the line (subtotal, taxes and total) keep two.

{
  "object": "invoice",
  "subtotal": "1000.00",
  "total_vat": "210.00",
  "total": "1210.00",
  "paid_amount": "1210.00",
  "pending_amount": "0.00",
  "currency": "EUR"
}

A JSON number carries no declared scale: 1210 comes back as 1210, 1210.0 or 1209.9999999999998 depending on who parses it. Read every money field into a fixed-decimal type — Decimal in Python, a big decimal or minor units in JavaScript — and never into a binary float. The schemas affected are BusinessContactActivity, CompanySeatChargePreview, DeliveryNote, DeliveryNoteLine, DeliveryNoteStats, EmployeeSeatBillingStatus, EmployeeSeatChargePreview, EventDataInvoicePaid, Invoice, InvoiceCorrective, InvoiceLine, InvoicePaymentDetail, InvoiceReminderPreview, InvoiceStats, ProductSalesAnalytics, ProductVariant, Proforma, ProformaLine, ProformaStats, PurchaseInvoice, PurchaseInvoiceLine, PurchaseInvoicePayment, PurchaseInvoiceStats, Quote, QuoteLine, QuoteStats, RecurringInvoice, RecurringInvoiceLine, RecurringInvoicePreviewDate, RecurringInvoiceStats, SimplifiedInvoiceEligibility, Store, StripeAutoinvoicedCorrective, StripeAutoinvoicedPayment, StripePayout, SupplierProductOffer, TaxCalculation, TaxTotals, TaxTotalsLine and VeriFactuRecord.

The collection date changed name

paid_at and paid_on are gone from the published payload. They are not emitted in parallel and they are not kept as aliases: the _at suffix marks an instant, and each canonical name now says which date it is.

The request body does not change: mark-paid and the payment registration still take paid_on, a YYYY-MM-DD date, and the invoice list filters by paid_on[gte], paid_on[lte], paid_on[gt] and paid_on[lt]. You send paid_on and you read paid_date and paid_recorded_at.

The paid coverage of a tax ID changed name

The Company resource drops seat_paid_until and publishes paid_until: the date up to which the tax ID is covered as an additional tax ID of the account (ISO 8601). It is null when the tax ID was never charged or its coverage expired, and reactivating it before that date is free. The resource also gains readiness, the same verdict and blockers as issuing-readiness, and suspension_reason: payer_blocked when the account that pays for a managed account has its billing blocked, management_ended when the management ended before anyone took over the payment, and null otherwise.

Creation responses declare Location

Forty-one operations answer 201 Created with a Location header: the canonical URL, relative to the server, of the resource the request created, with the axis segment in it — for an invoice, /v1/companies/{company}/invoices/{invoice} with both ids filled in. The header is not new on the wire: twenty-two of those operations already sent it without declaring it, and the contract now says so. Four of the forty-one are new operations. Follow Location instead of rebuilding the URL from the response.

The header that no longer exists

X-Active-Profile is rejected on presence, never on its value: a well-formed id, an id of a company you cannot reach, a malformed value and an empty string all get the same error.

Ignoring the header would have been the dangerous "compatible" option: the call would succeed and issue the document under the tax id of the credential holder instead of the one you meant, with no signal at all.

# Before
curl https://api.factuarea.com/v1/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY" \
  -H "X-Active-Profile: $COMPANY_ID"

# Now
curl https://api.factuarea.com/v1/companies/$COMPANY_ID/invoices \
  -H "Authorization: Bearer $FACTUAREA_API_KEY"

Every public identifier is a UUID v7

Every id the API returns, and every identifier in a path, is a UUID v7: time-ordered, so sorting by id follows creation order. There is a single format, whatever the resource.

• New records always get a UUID v7, including invoices issued automatically from Stripe payments.
• Identifiers you create yourself — the id of a new configuration, option group or option value in products.create and products.update — must be a UUID v7. Any other version is rejected with 422; an existing item keeps its identifier.
• A few older records — some documents, product configurations and VeriFactu certificates created before UUID v7 was the rule — receive a new UUID v7 in this window. The old id no longer answers in the API, so read those records again from their list endpoints if you stored their ids. Public document links you already sent keep working and open the document under its new identifier.

Idempotency after the move

Replay is unchanged in mechanics and grows with the surface. All 287 writes publish Idempotent-Replayed and replay a repeated key, and 130 of them declare Idempotency-Key as required — thirteen more than before the window, because the account axis and the provisioning surface add irreversible writes (issuing, accepting and revoking a tax ID transfer, removing a member, transferring ownership, creating a managed account, ending its management, changing its plan, reissuing its voucher, applying an import, rotating the secret of an account webhook and deleting one) and a few more that are not irreversible but deserve the same guard (sending and resending an invitation, retrying an account webhook delivery and testing an endpoint). 69 of them are flagged irreversible, nine more than before.

idempotency_key_reused is the one that moved: before this window it answered 409, and it answers 422 now. The fingerprint a key is bound to includes the path, so the same key sent to /v1/invoices and to /v1/companies/{company}/invoices is not a replay. While you migrate, mint a fresh key per call rather than reusing the ones your queue already holds. Read the idempotency guide.

CLI, PHP SDK and Node SDK

All three are generated from this contract and are regenerated against it: the CLI resource paths, the PHP SDK operation methods and the Node SDK operation methods all take the axis segment as their first argument, amounts come back as strings, and the retired header has no option left in any of them. Their release notes point at this page instead of describing a break of their own.

Migration checklist

1. Call GET /v1/me and keep data.account.id and every data.scope[].id. If you work for client accounts, read data.client_accounts[] too: it lists the accounts that granted your account access and the managed accounts you provisioned, with the level you hold on each.
2. Rewrite your base paths: company resources under /v1/companies/{company}/…, account resources under /v1/accounts/{account}/…, the provisioning root and the five catalog and introspection routes at the root. Watch the five underscore-to-hyphen renames and the four action segments that lose their underscore.
3. Swap PUT for PATCH on the thirty-two operations of the verb table, and call contacts.restore with POST.
4. Remove X-Active-Profile from your client. If you used it to act on several companies, the company segment now does it per request, without a header.
5. Parse every money field as a string into a fixed-decimal type, with the four-decimal unit_price of a line; read paid_recorded_at and paid_date where you read paid_at and paid_on, and keep sending paid_on; read paid_until where you read seat_paid_until.
6. Move any call to the API keys of one company to /v1/accounts/{account}/api-keys, restrict the key with scoped_company_ids, and swap api_keys:* for account:read / account:write on your keys.
7. Change claim-tokens for nif-transfers if you integrated the tax ID transfer against a pre-release build: scopes nif_transfers:read and nif_transfers:write, codes nif_transfer_expired and nif_transfer_invalid.
8. Treat the codes of the additional tax ID gate: additional_nif_charge_failed where you handled seat_charge_failed, additional_nif_plan_required where you handled gestoria_plan_required, additional_nif_not_in_plan where you handled gestoria_module_required, and billing_managed_by_provider for an account whose billing another account pays.
9. Treat the 403 codes of the account model: privileged_scope_required, live_credential_required, company_read_only, emitter_capability_restricted, owner_transfer_forbidden, additional_nif_not_in_plan and billing_managed_by_provider. Branch on code, not on message.
10. Stop calling the writes of the tax catalog: read it with GET /v1/companies/{company}/taxes or GET /v1/tax-catalog.
11. Add the thirty-seven new codes and parameter_unknown to your error handling, read idempotency_key_reused as a 422, and treat a 404 on an axis segment as "out of reach", not as a transient failure.
12. Replay your integration with a fact_test_ key before you move live traffic.
13. If you stored ids of records created before the window, re-read them from the list endpoints: the few that still had an older UUID version now have a UUID v7.

Read Amounts and dates, Reach a tax ID through the company segment, Accounts and tax IDs, Additional tax IDs and Errors.

Every operation, resource by resource

Operations: 519 — 49 new, 294 moved to the axis, 161 moved with other changes, 11 removed, 4 unchanged.

Changes that hit 50 or more operations at once are not repeated in the rows below: they are documented here once, with the number of operations each one touches. Everything else that changed in an operation is in its row.

Absence balances

Operations: 2 — 0 new, 2 moved to the axis, 0 moved with other changes, 0 removed, 0 unchanged.

Absence calendar

Operations: 1 — 0 new, 1 moved to the axis, 0 moved with other changes, 0 removed, 0 unchanged.

Absence policies

Operations: 10 — 0 new, 7 moved to the axis, 3 moved with other changes, 0 removed, 0 unchanged.

Absence requests

Operations: 6 — 0 new, 4 moved to the axis, 2 moved with other changes, 0 removed, 0 unchanged.

Absence types

Operations: 6 — 0 new, 3 moved to the axis, 3 moved with other changes, 0 removed, 0 unchanged.

Account

Operations: 57 — 47 new, 4 moved to the axis, 6 moved with other changes, 0 removed, 0 unchanged.

Automations

Operations: 18 — 0 new, 0 moved to the axis, 18 moved with other changes, 0 removed, 0 unchanged.

Companies

Operations: 19 — 2 new, 0 moved to the axis, 12 moved with other changes, 5 removed, 0 unchanged.

Contacts

Operations: 27 — 0 new, 2 moved to the axis, 25 moved with other changes, 0 removed, 0 unchanged.

Delivery notes

Operations: 22 — 0 new, 19 moved to the axis, 3 moved with other changes, 0 removed, 0 unchanged.

Request logs

Operations: 2 — 0 new, 2 moved to the axis, 0 moved with other changes, 0 removed, 0 unchanged.

Email deliveries

Operations: 3 — 0 new, 3 moved to the axis, 0 moved with other changes, 0 removed, 0 unchanged.

Employees

Operations: 17 — 0 new, 8 moved to the axis, 9 moved with other changes, 0 removed, 0 unchanged.

Events

Operations: 3 — 0 new, 0 moved to the axis, 2 moved with other changes, 0 removed, 1 unchanged.

FacturaE / FACe

Operations: 5 — 0 new, 4 moved to the axis, 1 moved with other changes, 0 removed, 0 unchanged.

Holidays

Operations: 3 — 0 new, 3 moved to the axis, 0 moved with other changes, 0 removed, 0 unchanged.

Integration events

Operations: 3 — 0 new, 3 moved to the axis, 0 moved with other changes, 0 removed, 0 unchanged.

Invoices

Operations: 48 — 0 new, 25 moved to the axis, 22 moved with other changes, 0 removed, 1 unchanged.

VeriFactu

Operations: 27 — 0 new, 24 moved to the axis, 3 moved with other changes, 0 removed, 0 unchanged.

Monthly closes

Operations: 8 — 0 new, 5 moved to the axis, 3 moved with other changes, 0 removed, 0 unchanged.

Payroll exports

Operations: 2 — 0 new, 1 moved to the axis, 0 moved with other changes, 0 removed, 1 unchanged.

Stripe

Operations: 10 — 0 new, 9 moved to the axis, 1 moved with other changes, 0 removed, 0 unchanged.

Presence

Operations: 3 — 0 new, 3 moved to the axis, 0 moved with other changes, 0 removed, 0 unchanged.

Price lists

Operations: 13 — 0 new, 12 moved to the axis, 1 moved with other changes, 0 removed, 0 unchanged.

Products

Operations: 41 — 0 new, 37 moved to the axis, 4 moved with other changes, 0 removed, 0 unchanged.

Proformas

Operations: 20 — 0 new, 17 moved to the axis, 3 moved with other changes, 0 removed, 0 unchanged.

Purchase invoices

Operations: 18 — 0 new, 6 moved to the axis, 12 moved with other changes, 0 removed, 0 unchanged.

Quotes

Operations: 20 — 0 new, 17 moved to the axis, 3 moved with other changes, 0 removed, 0 unchanged.

Recurring invoices

Operations: 18 — 0 new, 15 moved to the axis, 3 moved with other changes, 0 removed, 0 unchanged.

Series

Operations: 12 — 0 new, 8 moved to the axis, 4 moved with other changes, 0 removed, 0 unchanged.

Shopify

Operations: 1 — 0 new, 1 moved to the axis, 0 moved with other changes, 0 removed, 0 unchanged.

Stores

Operations: 5 — 0 new, 4 moved to the axis, 1 moved with other changes, 0 removed, 0 unchanged.

Taxes

Operations: 18 — 0 new, 11 moved to the axis, 0 moved with other changes, 6 removed, 1 unchanged.

Tax reports

Operations: 9 — 0 new, 8 moved to the axis, 1 moved with other changes, 0 removed, 0 unchanged.

Time balances

Operations: 3 — 0 new, 3 moved to the axis, 0 moved with other changes, 0 removed, 0 unchanged.

Time corrections

Operations: 5 — 0 new, 4 moved to the axis, 1 moved with other changes, 0 removed, 0 unchanged.