Enabling VeriFactu for a NIF

Put a NIF under the VeriFactu regime in Live — the steps, the configuration fields that tell you where you are, the errors you can hit, and the blockers that stop issuing.

VeriFactu applies to a NIF in an environment, not to an invoice. Once a NIF is under the regime in Live, every invoice it issues there is registered with AEAT; until then, none is. This page is the path from "NIF created" to "invoices reach AEAT".

In sandbox there is nothing to enable — VeriFactu is always on there. See Testing VeriFactu in sandbox.

The path in Live

Switch the NIF on in Live

A NIF only operates in Live once it is activated there, which puts it on a paid plan. That is done with the activations endpoint, described in Switching a NIF on in Test or Live. Without it, issuing in Live is blocked (ENV_MISMATCH, see below).

Sign the AEAT representation

In Live, submitting to AEAT on the taxpayer's behalf requires a representation form signed by the NIF's holder. Generate it, have the holder sign it, and submit the signed copy — the flow is in Signing the VeriFactu representation.

If you provisioned the account, you receive a representation.signed webhook when the holder signs, so you don't need to poll.

Put the NIF under the regime

curl -X PUT "https://app.beel.es/api/v1/companies/{company_id}/verifactu-configuration" \
  -H "Authorization: Bearer beel_sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true }'

enabled is the only writable field and has no default. Turning it on registers the NIF in the same call: either the call succeeds and the NIF is registered, or it returns the reason and nothing changes. There is no half-enabled state to poll for.

Check the NIF can issue

curl "https://app.beel.es/api/v1/companies/{company_id}/issuing-readiness" \
  -H "Authorization: Bearer beel_sk_live_xxx"

ready: true with an empty blockers list means the next invoice goes out and reaches AEAT. See Get issuing readiness.

Reading the configuration

GET /v1/companies/{company_id}/verifactu-configuration (reference) returns the NIF's state for the environment of the request. Read status first — it is the one field that summarises the others.

`status`

The steps above map to a ladder. Each value names the next thing missing:

`status`	Meaning	Next step
`DISABLED`	VeriFactu is not enabled for this NIF	Enable it (step 3) — after steps 1 and 2
`UNSIGNED`	Enabled, but there is no signed representation for the NIF. Live only	Sign the representation (step 2)
`NOT_ACTIVATED`	Signed, but the NIF is not switched on in this environment	Switch it on (step 1)
`ACTIVE`	Ready: invoices are registered with AEAT	Nothing
`ERROR`	Historical — no configuration reaches it any more. Kept so older clients still parse stored values	Treat as `DISABLED`
`null`	VeriFactu was never configured for this NIF	Start at step 1

signed, activated and pdf_generated are the facts behind status — useful for a setup wizard, but decide on status.

`nif_status`

Whether the NIF is registered for submission in this environment: ACTIVATED, DEACTIVATED (not registered, or deregistered), or null if VeriFactu was never enabled. In Live, enabled: true always comes with ACTIVATED, because enabling is registering. In sandbox the two can drift for a moment — see Testing in sandbox.

When enabling fails

Error	When	What to do
`422` `VERIFACTU_REPRESENTATION_REQUIRED`	Enabling in Live without a signed representation for the NIF	Complete step 2, then retry
`402` `CHECKOUT_REQUIRED`, `PAYMENT_REQUIRED` or `PLAN_ACTIVATION_REQUIRED`	Enabling in Live on an account that is not entitled to production — no card on file, an unpaid invoice, or a plan still to activate	Resolve the billing side (step 1), then retry
`422` `ALREADY_ENABLED`	The NIF is already under the regime in this environment	Nothing — it is on
`422` `VERIFACTU_ALWAYS_ON_IN_SANDBOX`	Sending `enabled: false` in sandbox	Nothing to do: sandbox is always on, and nothing there reaches the real AEAT

Turning VeriFactu off in Live

PUT … { "enabled": false } in Live stops the submission of the NIF's invoices, which then generate no billing record. Under article 16.5 of the RD 1007/2023, a taxpayer that starts submitting in VERI*FACTU stays in it at least until the end of that calendar year. Check with the taxpayer's advisor before turning it off — see VERI*FACTU modality.

If the registration itself is refused, the call fails, nothing is persisted, and the response says why. Fix the cause (usually the company's fiscal data) and send the same PUT again.

What blocks issuing

GET /v1/companies/{company_id}/issuing-readiness answers "can this NIF issue right now, here?". When ready is false, blockers says why. Three of the reasons belong to the VeriFactu chain and are reported one at a time, in this order:

Blocker	Meaning	Fix
`ENV_MISMATCH`	The NIF is under VeriFactu but not switched on in the environment you are calling — for example a NIF active only in Live, called with a test key	Switch the NIF on in that environment (step 1), or call with the key for the environment where it is active
`NIF_NOT_REGISTERED`	Switched on, but the NIF is not registered for submission in this environment	Enable VeriFactu for the NIF (step 3); if it is already enabled, contact support
`NIF_REPRESENTATION_REQUIRED`	Registered, but the signed representation is missing. Live only	Sign the representation (step 2)

The other blockers — COMPANY_HAS_NO_NIF, SERIES_DEFAULT_NOT_FOUND, PROFILE_INCOMPLETE, COMPANY_NOT_ACTIVATED — are not VeriFactu-specific: every blocker, with its fix, is in Is a NIF ready to invoice?.

The response also has a verifactu sub-block (verifactu.ready, verifactu.blockers) that answers the compliance question on its own: would this NIF pass a VeriFactu emission right now? It is useful before enabling, to see what is still missing.

Enabling VeriFactu for a NIF

On this page