# 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](/verifactu/testing-in-sandbox).

## The path in Live

<Steps>

<Step>

### 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](/multi-nif/companies#switching-a-nif-on-in-test-or-live). Without it, issuing in Live is blocked (`ENV_MISMATCH`, see [below](#what-blocks-issuing)).

</Step>

<Step>

### 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](/multi-nif/companies#signing-the-verifactu-representation).

If you provisioned the account, you receive a <a href="/webhook-events/onRepresentationSigned">`representation.signed`</a> webhook when the holder signs, so you don't need to poll.

</Step>

<Step>

> **Rules that apply here:** [REC-011 · The NIF holder signs the AEAT representation first](/rules/records#rec-011)

### Put the NIF under the regime

```bash
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.

</Step>

<Step>

### Check the NIF can issue

```bash
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](/companies/getCompanyIssuingReadiness).

</Step>

</Steps>

## Reading the configuration

`GET /v1/companies/{company_id}/verifactu-configuration` ([reference](/verifactu/getCompanyVeriFactuConfiguration)) 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](/verifactu/testing-in-sandbox#the-nif-registers-itself).

## When enabling fails

| Error | When | What to do |
|---|---|---|
| `422` [`VERIFACTU_REPRESENTATION_REQUIRED`](/errors/VERIFACTU_REPRESENTATION_REQUIRED) | Enabling in Live without a signed representation for the NIF | Complete step 2, then retry |
| `402` [`CHECKOUT_REQUIRED`](/errors/CHECKOUT_REQUIRED), [`PAYMENT_REQUIRED`](/errors/PAYMENT_REQUIRED) or [`PLAN_ACTIVATION_REQUIRED`](/errors/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`](/errors/ALREADY_ENABLED) | The NIF is already under the regime in this environment | Nothing — it is on |
| `422` [`VERIFACTU_ALWAYS_ON_IN_SANDBOX`](/errors/VERIFACTU_ALWAYS_ON_IN_SANDBOX) | Sending `enabled: false` in sandbox | Nothing to do: sandbox is always on, and nothing there reaches the real AEAT |

<Callout type="warn" title="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](/verifactu/compliance-and-responsibilities#verifactu-modality-only).
</Callout>

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`](/errors/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](#switch-the-nif-on-in-live)), or call with the key for the environment where it is active |
| [`NIF_NOT_REGISTERED`](/errors/NIF_NOT_REGISTERED) | Switched on, but the NIF is not registered for submission in this environment | Enable VeriFactu for the NIF ([step 3](#put-the-nif-under-the-regime)); if it is already enabled, contact support |
| [`NIF_REPRESENTATION_REQUIRED`](/errors/NIF_REPRESENTATION_REQUIRED) | Registered, but the signed representation is missing. Live only | Sign the representation ([step 2](#sign-the-aeat-representation)) |

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?](/multi-nif#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.

> **Rules that apply here:** [REC-003 · VERI*FACTU is kept until the end of the year](/rules/records#rec-003)

## Related

<Related>

- [Auto-submit policy](/verifactu/auto-submit) — why the NIF, not the invoice, decides
- [Testing VeriFactu in sandbox](/verifactu/testing-in-sandbox) — the same flow without the representation
- [Companies](/multi-nif/companies) — creating NIFs, activations and the representation flow
- [Handling AEAT rejections](/verifactu/handling-rejections) — issuer codes such as `4104` point back here

</Related>

---

Full OpenAPI spec: https://docs.beel.es/api/openapi