Account contract adjustments
Fixes to the v1 contract after the review of 6 October, durable purchases moved to the company axis, and the final shape of managed accounts, additional tax IDs and the user cap.
7 October 2026
We reviewed the new account model line by line before it reaches you, and we have adjusted a few things. Most of them make the contract stricter where it was too generous, so read this page if your integration issues credentials, retries writes or buys seats.
What the review corrected
idempotency_key_reused now always answers 422, whatever operation reuses the key. The idempotency fingerprint no longer exposes secrets: a replay of a write that returned a secret keeps the original answer but never leaves the secret readable in what we keep.
The * scope does not cover account administration (account:owner, members:*, invitations:* and nif_transfers:*), and api_keys:* is reserved: ask for them by name. A credential can no longer create, rotate, revoke or change the tax ID scope of another one that holds more power than itself; the answer is 403 insufficient_scope, or 403 live_credential_required when a test key tries to touch a live one.
The v1 contact operations now respect the Factuarea-Version header like the rest of the contract. Account webhooks also check, event by event, that each endpoint may still see what it is about to receive.
Durable purchases belong to the company axis
All the operations of employee batches (employee-batches), employee-seat offer redemptions (employee-seat-offer-redemptions) and additional tax ID offer redemptions (gestoria-seat-offer-redemptions) now live under /v1/companies/{company}/…, with no flat alias. It is the same retirement of flat routes that the rest of the account model went through. Operation names and MCP tool names do not change, so if you call them through an SDK, the CLI or MCP you only need to update the version you use; if you call them by URL, add the company to the path.
Adding, activating and previewing tax IDs
Registering, activating and batch-activating tax IDs, and the charge preview, can now answer 409 customer_offer_phase_incompatible when the conditions you already hold cannot be kept, and 503 gestoria_seat_preview_unavailable when we cannot compute the preview right now. Nothing is created, activated or charged in either case, so you can retry safely.
The preview also says why an amount is zero, in zero_reason: trial, covered, enterprise_contract, negotiated_free_price or no_immediate_charge. An unknown reason never means an Enterprise contract.
The seat, employee, batch and company operations that can run into a pending operation or a conditions change now declare their 409 with an example, and the 409 external_id_already_exists of employee batches adds row_ids, the stable row_id of every row whose external_id was already taken, so you can fix those rows and send the batch again.
Managed accounts, additional tax IDs and the user cap
As a provider you can now assign Avanzado (integral) as well as Esencial and Profesional to a managed account, at the normal price of the plan. managed_accounts_by_plan always includes the integral key. Enterprise is still agreed with us by contract.
An additional tax ID costs 15 € per month, VAT excluded. On a Profesional or Avanzado account, every additional tax ID has the Profesional plan; only the titular tax ID has the plan of the account.
The user cap is counted in seats of the account, not of each tax ID. Accepting an invitation when the cap is full answers 422 business_rule_violation, with the same message you see in the app, and not a 402.