Quick integration guide for the Verifacti APIs

This guide explains step by step how to integrate your software with the Verifactu API, the TicketBAI API or the SII API, from the free account to production. The account, the NIFs, the representation form and the move to production are common to all of them; in the steps that change by API (sending, status and corrections) choose yours and the guide shows only what applies to you.

1. Create a free account

Create a free account in 30 seconds:

  1. Click the sign up free button.
  2. Enter your email and password.
  3. Verify your email by clicking the link in the email we send you.

Once inside you will see the companies panel, with a test NIF already set up to send invoices to the AEAT test environment with Verifactu, from our interface or through the API. The whole basic integration can be done with the free account.

companies panel
Companies panel with the test NIF

The test NIF is a Verifactu one. To test TicketBAI or the SII you need a test NIF for that treasury: ask soporte@verifacti.com, stating which one (Álava, Bizkaia, Gipuzkoa or SII), and we will activate it.

See what the free account includes and whether I can test TicketBAI with the free account.

2. Send a test invoice

When you open the test NIF you will see an integrated terminal to send invoices to the AEAT. It offers a simple interface to load all kinds of invoice examples and send them with one click to the AEAT test environment.

integrated terminal
Integrated terminal to send invoices to the AEAT

The response contains the QR code (as a base 64 string) of the generated invoicing record, for you to paste on your invoice. The QR holds the AEAT URL that shows whether the invoice is already registered in its systems.

API - Create invoices

To generate an invoicing record and send it to the AEAT, call POST /verifactu/create with the API key of the test NIF (B75777847, the same in every account), found in its API key tab. More in the documentation.

POST /verifactu/create

Factura normal
{
  "serie": "Ejemplos",
  "numero": "1",
  "fecha_expedicion": "19-11-2026",
  "tipo_factura": "F1",
  "descripcion": "Factura normal",
  "nif": "A15022510",
  "nombre": "Nombre destinatario",
  "lineas": [
    {
      "base_imponible": "200",
      "tipo_impositivo": "21",
      "cuota_repercutida": "42"
    }
  ],
  "importe_total": "242"
}

More cases in the Verifactu invoice examples.

3. Confirm the status

In every API, the recommended way to get the result is webhooks, which notify you of each status change. You can also check it with each API's status endpoint, or see it in the dashboard's records table.

Records table - Correct
Records table with a successfully sent record

When you send the invoice, the API returns the status Pendiente (pending): the record has been generated and queued to be sent to the AEAT, usually within one or two minutes. Because of how Verifactu works, records are not sent immediately. Check the status with GET /verifactu/status and the uuid returned on creation, and list the submitted invoices with POST /verifactu/list. See the Verifactu API documentation.

4. Correct or cancel invoices

If the invoice does not require a corrective invoice, fix it with PUT /verifactu/modify and the corrected record. If it does, create it with POST /verifactu/create and the matching tipo_factura (R1 to R5). To cancel, POST /verifactu/cancel with series, number and issue date; a cancelled invoice cannot be created again with the same data. Cases in the Verifactu corrective invoices.

POST /verifactu/cancel

/verifactu/cancel
{
  "serie": "A",
  "numero": "1",
  "fecha_expedicion": "25-02-2025"
}

PUT /verifactu/modify

Descripcion modificada
{
  "rechazo_previo": "N",
  "serie": "Ejemplos",
  "numero": "1",
  "fecha_expedicion": "19-11-2026",
  "tipo_factura": "F1",
  "nif": "A15022510",
  "nombre": "Nombre destinatario",
  "descripcion": "Descripcion modificada",
  "lineas": [
    {
      "base_imponible": "200",
      "tipo_impositivo": "21",
      "cuota_repercutida": "42"
    }
  ],
  "importe_total": "242"
}

5. Activate the paid subscription

To prepare the move to production, activate your paid subscription:

  1. Go to the pricing page.
  2. Click the "Buy first NIF" button. You will be redirected to the payment page.
  3. Check the "I'm purchasing as a business" box to enter your tax ID, which will appear on the invoices.
Stripe Checkout
Subscription activation page

The SII is custom-priced and not on the pricing page: ask for a quote via contact. See when I start paying.

6. Register your NIFs

With an active subscription you can create as many test issuing NIFs as you want, at no additional cost. Go to the companies panel and click "+ Add company".

Add company
Page to add a company

Choose the environment and the treasury carefully. Test NIFs send to the test environment and production NIFs to the real one; only the latter count for the monthly bill. The treasury sets the destination: verifactu, alava, vizcaya, guipuzcoa or sii. Each combination of NIF, environment and treasury is a separate NIF with its own API key, and the same NIF can be in several treasuries at once.

API - Add invoice-issuing NIFs

To send invoices for hundreds or thousands of companies or self-employed people, create them with POST /nifs and your account API key, found in the account settings (API key tab). How to add, modify or deactivate NIFs, in the NIF management API documentation.

Remember that each NIF has its own API key to send its invoices. See how API keys, environments and NIF management work.

7. Manage the representation form

For Verifacti to send invoices on a company's behalf, a document authorising us must be signed. It is the same for the AEAT (Verifactu and SII) and for the three foral treasuries. Test NIFs do not need it, but you can fill it in from the test NIF and it will be valid when you create the NIF in production.

Download the pre-filled form from the NIF page, which explains how to fill it in, sign it and send it. It can also be signed online, with video identity verification and no digital certificate (€2.90 + VAT per signature, individuals only): online signing.

Fill in the representation form
Page to fill in the representation form

API - Representation form

Forms can be filled in and sent through the API with your account API key (account settings, API key tab). Details in the documentation.

See how certificate and representation-form management works.

8. Move to production

With the integration done and the representation form signed, create the same NIF in the production environment, with its treasury, and swap the test API key for the production one. Production NIFs are the ones that count for the subscription; the same NIF registered with two treasuries counts as two NIFs.

API - Create NIFs in production

To move your test NIFs to production through the API, chain the list NIFs, get each one and create-in-production endpoints, with your account API key. Details in the NIF management API documentation.

  • TicketBAI in Bizkaia: the API sends each issued invoice to the Batuz LROE (form 140 or 240). More in TicketBAI in Bizkaia.
  • SII: keep the deadline in mind, four calendar days from the issue of each invoice, excluding Saturdays, Sundays and national holidays (eight for invoices issued by the recipient or a third party). Details in SII deadlines.

9. Publish the statement of conformity (Verifactu only)

Verifactu has no external certification or AEAT verification: each invoicing software must include a document that self-certifies it meets the requirements. TicketBAI and the SII do not ask for it.

With an API like ours, both your software and Verifacti must have their statement of conformity (declaración responsable). You can download Verifacti's (PDF) and use our template to prepare yours. See how to publish the statement of conformity.

Keep integrating

You now have the whole flow. To keep going, read your API documentation and copy the invoice examples.

Frequently asked questions

More frequently asked questions

How long does the integration take?

In most cases, the integration is completed by a single developer in one to three full-time days, plus a few additional part-time days afterwards.

Are the endpoint URLs different for test and production environments?

The endpoint URLs do not change—they are the same for both test and production environments. What determines which environment is used is the API key being used.
Each API key has an associated environment: test or production.
  • In the test environment, the company API key starts with vf_test_
  • In the production environment, the company API key starts with vf_prod_

Do I need a separate integration for TicketBAI or is it the same integration for both TicketBAI and Verifactu?

Why are there two different APIs to integrate with Verifactu and TicketBAI?
We decided to design two differentiated APIs, one for Verifactu and another for TicketBAI, largely following the structure of the official tax authority APIs.
This provides several advantages:
  • Consistency: the endpoints, fields, and error messages we present to our users are practically the same as those in the tax authority APIs.
  • Easier tax consultations: this similarity eliminates interpretations or biases stemming from an intermediary API, which streamlines communication with advisors and with the tax authorities themselves.
What does this mean for integration?
It is necessary to integrate with two different APIs.
However, in practice, after integrating with Verifactu, the subsequent TicketBAI integration usually requires only 10%-20% additional effort. This is because several calls coincide, and when they don't, they maintain a very similar structure.
For example, when creating an invoice, you will need two different JSONs, using one or the other depending on the target API.
What is shared is the NIF management API (NIF registration, representation form and webhooks): you integrate it once and it works for both APIs.

Can I test TicketBAI with the free account?

Yes. The free account includes the TicketBAI test environment, so you can do the integration at no cost. For the foral treasury test NIF, write to soporte@verifacti.com. To send invoices of real NIFs to the foral treasury you need a paid subscription.

When do I start paying? Do I have to pay now if Verifactu is not mandatory yet?

No. You can complete the whole integration with the free account and you only start paying when you activate your subscription to register NIFs in production.
You decide when: you can wait until the mandatory date that applies to you, or start sending invoices to the AEAT voluntarily before then.

How do I create my responsible declaration (declaración responsable)?

The AEAT has published an example of a responsible declaration in PDF.
We have adapted this example for our users. You can download it here:
  • We provide an editable Word document.
  • We include informational notes for the more complex sections.
  • We add a section to explain the role of the Verifacti API.
Key information for filling out the document:
  1. Section titles are in bold and larger font.
  2. Replace the example responses with your own data.
  3. Delete the informational notes when completing the document.
It is mandatory to mention Verifacti as an external component. We have included a specific section for mixed architectures with an external component. You must state our current software version, which can change: GET /verifactu/declaracion returns it along with our statement.
👉 Watch short video: Responsible declaration part 2: guide to easily completing the responsible declaration
More about the statement of conformity.

Start with the free account

The first step of the guide: test environment and test NIF included.

Test environment and test NIF includedRead the documentation