Account tax regime

The Account Tax Regime resource exposes mutable configuration and compliance state for one account. This is separate from the public Tax Regime catalog, 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.

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'

{
  "object": "account_tax_regime",
  "account": "acct_14Vxtqg7NhKs3Rb9CmY2Pd",
  "key": "global"
}

curl --request POST \
  'https://api.fiscalrail.com/v1/account/tax-regime/es/representation/verify' \
  --header "Authorization: Bearer fra_live_..."

{
  "object": "account_tax_regime",
  "account": "acct_14Vxtqg7NhKs3Rb9CmY2Pd",
  "key": "global"
}

curl --request POST \
  'https://api.fiscalrail.com/v1/account/tax-regime/es/submission/verify' \
  --header "Authorization: Bearer fra_live_..."

{
  "object": "account_tax_regime",
  "account": "acct_14Vxtqg7NhKs3Rb9CmY2Pd",
  "key": "global"
}

curl --request DELETE \
  'https://api.fiscalrail.com/v1/account/tax-regime/es/submission/pending' \
  --header "Authorization: Bearer fra_live_..."

{
  "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.

{
  "object": "account_tax_regime",
  "account": "acct_14Vxtqg7NhKs3Rb9CmY2Pd",
  "key": "global"
}

{
  "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"
    }
  }
}

import os

from fiscalrail import FiscalRail

client = FiscalRail(os.environ["FISCALRAIL_API_KEY"])

tax_regime = client.account_tax_regimes.retrieve()

require "fiscalrail"

client = FiscalRail::Client.new(api_key: ENV.fetch("FISCALRAIL_API_KEY"))

tax_regime = client.account_tax_regimes.retrieve

curl --request GET \
  'https://api.fiscalrail.com/v1/account/tax-regime' \
  --header "Authorization: Bearer fra_test_..."

{
  "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"
    }
  }
}