# Account tax regime Inspect account-specific tax-regime configuration and compliance state. The Account Tax Regime resource exposes mutable configuration and compliance state for one account. This is separate from the public [Tax Regime catalog](/en/api/tax-regimes), which describes supported taxes and rules, and from the immutable tax-regime state attached to an issued Invoice. The `key` field discriminates the response shape. A Spanish account includes an `es` object; a Global account omits regime-specific details until Global has account-level configuration to expose. For Live Spanish accounts, `es.submission` reports the active method (`direct` or `represented`), its `ready` state and the direct certificate's expiry date. No credential material is exposed. `es.pending_submission` reports the replacement's `kind`, verification `status`, `error_code`, `last_checked_at` and certificate expiry. The active method remains unchanged until the replacement passes verification. After activation or cancellation, `pending_submission` becomes null. `es.representation` reports the AEAT `IZ860` registered-power state when represented submission is active. It is null for direct submission. All submission and representation fields are null for Test accounts, which use the simulator without AEAT credentials. Live issuance checks submission readiness at the operation boundary. ## Configure AEAT submission These operations live under `/v1/account/tax-regime/es` and require a Live Spanish account's API key. Read the setup using `GET /v1/account/tax-regime`. Upload a `.p12` or `.pfx` file as `multipart/form-data`, with `certificate_file` and the optional `certificate_password`. The maximum file size is 128 KiB. The certificate must identify the account's issuer NIF and include its private key. FiscalRail stores the credential encrypted and discards the password after parsing. An upload returns `202 Accepted` and starts verification with AEAT. Poll this resource to observe the pending result. A failed or unavailable check retains the pending certificate; retry verification or cancel the pending change. A new upload replaces the pending change. A working active setup is preserved throughout verification. Invalid uploads leave existing configurations untouched. To use FiscalRail's representative certificate, grant the AEAT power first, then request representation verification. When direct submission is active, this stages a represented replacement and only switches after successful verification. For an active configuration, `status` describes submission verification and `error_code` reports the latest failure. Always use `ready` for issuance readiness: a previously verified configuration stays usable during an unavailable recheck. These new operations currently use HTTP directly; SDK convenience methods are not yet available. Use a Live key in the examples below. ## Upload an issuer certificate `POST /v1/account/tax-regime/es/certificate` Uploads a PKCS#12 certificate and queues AEAT verification. Only Live Spanish accounts are supported. A working setup remains active until verification succeeds. A new upload replaces any pending change. ### Request body #### `certificate_file` Type: `string` — required A .p12 or .pfx file, at most 128 KiB. Must include the private key and identify the account issuer NIF. #### `certificate_password` Type: `string` PKCS#12 password. Omit for an unprotected bundle. Discarded after parsing. ### Responses - `202` — [Current account configuration. Poll GET /account/tax-regime to observe verification results.](#the-account-tax-regime-object) Formats: JSON. ### Example request ```bash curl --request POST \ 'https://api.fiscalrail.com/v1/account/tax-regime/es/certificate' \ --header "Authorization: Bearer fra_live_..." \ --form 'certificate_file=@issuer.p12' \ --form-string 'certificate_password=YOUR_CERTIFICATE_PASSWORD' ``` ### Example response — 202 ```json { "object": "account_tax_regime", "account": "acct_14Vxtqg7NhKs3Rb9CmY2Pd", "key": "global" } ``` ## Verify AEAT representation `POST /v1/account/tax-regime/es/representation/verify` Queues verification of FiscalRail representation for a Live Spanish account. If direct submission is active, it remains active until the represented replacement verifies. Any pending change is replaced. ### Responses - `202` — [Current account configuration. Poll GET /account/tax-regime to observe verification results.](#the-account-tax-regime-object) Formats: JSON. ### Example request ```bash curl --request POST \ 'https://api.fiscalrail.com/v1/account/tax-regime/es/representation/verify' \ --header "Authorization: Bearer fra_live_..." ``` ### Example response — 202 ```json { "object": "account_tax_regime", "account": "acct_14Vxtqg7NhKs3Rb9CmY2Pd", "key": "global" } ``` ## Retry submission verification `POST /v1/account/tax-regime/es/submission/verify` Queues another check of the pending configuration, or the active configuration if there is no pending change. Only Live Spanish accounts are supported. ### Responses - `202` — [Current account configuration. Poll GET /account/tax-regime to observe verification results.](#the-account-tax-regime-object) Formats: JSON. ### Example request ```bash curl --request POST \ 'https://api.fiscalrail.com/v1/account/tax-regime/es/submission/verify' \ --header "Authorization: Bearer fra_live_..." ``` ### Example response — 202 ```json { "object": "account_tax_regime", "account": "acct_14Vxtqg7NhKs3Rb9CmY2Pd", "key": "global" } ``` ## Cancel a pending submission change `DELETE /v1/account/tax-regime/es/submission/pending` Deletes the pending change and its stored certificate, preserving the active setup. Succeeds even when there is no pending change. Only Live Spanish accounts are supported. ### Responses - `200` — [Current account configuration. Poll GET /account/tax-regime to observe verification results.](#the-account-tax-regime-object) Formats: JSON. ### Example request ```bash curl --request DELETE \ 'https://api.fiscalrail.com/v1/account/tax-regime/es/submission/pending' \ --header "Authorization: Bearer fra_live_..." ``` ### Example response — 200 ```json { "object": "account_tax_regime", "account": "acct_14Vxtqg7NhKs3Rb9CmY2Pd", "key": "global" } ``` ## The Account Tax Regime object The response is one of the following concrete shapes, selected by `key`. ## Global Account Tax Regime ### Properties #### `object` Type: `string` String identifying this as an Account Tax Regime object. Always `account_tax_regime`. #### `account` Type: `string` Opaque identifier for an account. #### `key` Type: `string` Identifies the Global tax regime. Always `global`. ### Example ```json { "object": "account_tax_regime", "account": "acct_14Vxtqg7NhKs3Rb9CmY2Pd", "key": "global" } ``` ## Spanish Account Tax Regime ### Properties #### `object` Type: `string` String identifying this as an Account Tax Regime object. Always `account_tax_regime`. #### `account` Type: `string` Opaque identifier for an account. #### `key` Type: `string` Identifies the Spanish tax regime. Always `es`. #### `es` Type: `object` Spanish account-specific configuration and compliance state. ##### `es.pending_submission` Type: `object or null` Replacement being verified. Null when absent, after activation or cancellation, and for Test accounts. Failed checks retain the replacement for retry. ###### `es.pending_submission.kind` Type: `enum` Submission method requested by the pending replacement. Possible values: - `direct` — - `represented` — ###### `es.pending_submission.status` Type: `enum` Latest submission verification status. A ready active configuration stays verified during a recheck; use ready to decide whether issuance is permitted. Possible values: - `not_started` — - `pending_verification` — - `verified` — - `invalid` — - `unavailable` — ###### `es.pending_submission.error_code` Type: `string or null` Machine-readable reason for the latest failed check, such as unauthorized, unavailable, expired, nif_mismatch, not_yet_valid or duplicate_nif. Null before a check or after success. ###### `es.pending_submission.last_checked_at` Type: `string or null` When the latest verification attempt finished. ###### `es.pending_submission.certificate_expires_at` Type: `string or null` Expiry of the pending direct certificate, or null for represented submission. ##### `es.submission` Type: `object or null` Active AEAT submission method and readiness, or null for a Test account. ###### `es.submission.kind` Type: `enum` Submit using the issuer's uploaded certificate or FiscalRail's authorized representative certificate. Possible values: - `direct` — - `represented` — ###### `es.submission.ready` Type: `boolean` Whether the active configuration permits live invoice issuance and submission. ###### `es.submission.status` Type: `enum` Latest submission verification status. A ready active configuration stays verified during a recheck; use ready to decide whether issuance is permitted. Possible values: - `not_started` — - `pending_verification` — - `verified` — - `invalid` — - `unavailable` — ###### `es.submission.error_code` Type: `string or null` Machine-readable reason for the latest failed check, such as unauthorized, unavailable, expired, nif_mismatch, not_yet_valid or duplicate_nif. Null before a check or after success. ###### `es.submission.last_checked_at` Type: `string or null` When the latest verification attempt finished. ###### `es.submission.certificate_expires_at` Type: `string or null` Expiry of the issuer's certificate for direct submission; null for represented submission. ##### `es.representation` Type: `object or null` Current AEAT representation state, or null for a Test account or direct submission. ###### `es.representation.kind` Type: `string` Representation method used for the account. Always `aeat_registered_power`. ###### `es.representation.power_code` Type: `string` AEAT power for submitting and consulting invoice-registration records through web services. Always `IZ860`. ###### `es.representation.status` Type: `enum` Current result of FiscalRail's live AEAT representation check. Possible values: - `not_started` — Verification has not been requested. - `pending_verification` — A live verification check is queued or running. - `verified` — The latest live check confirmed the registered power. - `revoked` — A previously verified power failed the latest live check. - `invalid` — No successful live check has confirmed the registered power. ###### `es.representation.verified_at` Type: `string or null` When the power was last successfully verified, or null when never verified. ###### `es.representation.last_checked_at` Type: `string or null` When the latest live verification attempt finished, or null before the first completed check. ### Example ```json { "object": "account_tax_regime", "account": "acct_14Vxtqg2nwvPR75TpsGH8N", "key": "es", "es": { "submission": { "kind": "represented", "ready": true, "status": "verified", "error_code": null, "last_checked_at": "2026-08-25T14:30:00Z", "certificate_expires_at": null }, "pending_submission": null, "representation": { "kind": "aeat_registered_power", "power_code": "IZ860", "status": "verified", "verified_at": "2026-08-25T14:30:00Z", "last_checked_at": "2026-08-25T14:30:00Z" } } } ``` ## Retrieve the account tax regime `GET /v1/account/tax-regime` Returns the selected account's regime configuration and compliance state. ### Responses - `200` — [An Account Tax Regime object.](#the-account-tax-regime-object) Formats: JSON. ### Example requests #### Python ```python import os from fiscalrail import FiscalRail client = FiscalRail(os.environ["FISCALRAIL_API_KEY"]) tax_regime = client.account_tax_regimes.retrieve() ``` #### Ruby ```ruby require "fiscalrail" client = FiscalRail::Client.new(api_key: ENV.fetch("FISCALRAIL_API_KEY")) tax_regime = client.account_tax_regimes.retrieve ``` #### cURL ```bash curl --request GET \ 'https://api.fiscalrail.com/v1/account/tax-regime' \ --header "Authorization: Bearer fra_test_..." ``` ### Example response — 200 ```json { "object": "account_tax_regime", "account": "acct_14Vxtqg2nwvPR75TpsGH8N", "key": "es", "es": { "submission": { "kind": "represented", "ready": true, "status": "verified", "error_code": null, "last_checked_at": "2026-08-25T14:30:00Z", "certificate_expires_at": null }, "pending_submission": null, "representation": { "kind": "aeat_registered_power", "power_code": "IZ860", "status": "verified", "verified_at": "2026-08-25T14:30:00Z", "last_checked_at": "2026-08-25T14:30:00Z" } } } ```