Skip to main content

Verifactu

Verifactu is the standardized digital format for submitting all invoices issued in Spain to the tax administration (AEAT - Agencia Estatal de Administración Tributaria).

Quaderno is officially recognized software for Verifactu by the Spanish Tax Agency.

Thanks to our API, complying is as easy as sending your sales and refund data to Quaderno in a single API call. You will receive a JSON response with the signed PDF of the document, which contains a QR code to ease later verification.

tip

You can test the Verifactu integration in our Sandbox environment, which simulates the production environment without sending real data to the AEAT.

Connecting Verifactu​

To start using Verifactu in Quaderno, you need to upload your electronic certificate and then activate the integration. You can do both from the dashboard or through the API.

From the dashboard​

  1. Upload your electronic certificate on the Certificates page. The certificate must be issued to the same tax ID and name that appear in your Quaderno account.
  2. Connect the Verifactu integration from the Integrations page page.

Using the API​

Before activating Verifactu, make sure that:

  • Your account has a valid Spanish NIF set as registration_number.
  • Your account business_name matches the name registered with the AEAT for that NIF.
  • Your certificate is issued to the same NIF that appears in your Quaderno account.
  • Your account has no other e-invoicing integration (Verifactu or TicketBAI) connected. Only one is allowed per account.
note

Only admin or developer API keys can manage certificates.

1. Upload your certificate​

Send your PKCS#12 file to the Certificates API. The file content must be encoded in base64, and the country must be ES:

curl https://ACCOUNT_NAME.quadernoapp.com/api/certificates \
  -u YOUR_API_KEY:x \
  -H "Content-Type: application/json" \
  -H "Accept: application/json; api_version=20260309" \
  -d '{
    "country": "ES",
    "password": "secret",
    "file": {
      "filename": "certificate.p12",
      "data": "BASE64_ENCODED_CERTIFICATE"
    }
  }'

The response includes the certificate id. Quaderno extracts the subject_name and valid_until from the file, and only one active certificate per country is allowed.

warning

PKCS#12 files contain a private key. Only send them over HTTPS, and never log or store the base64 payload on the client side.

2. Activate Verifactu​

Call the Verifactu API with the certificate_id returned in the previous step:

curl https://ACCOUNT_NAME.quadernoapp.com/api/einvoicing/verifactu \
  -u YOUR_API_KEY:x \
  -H "Content-Type: application/json" \
  -H "Accept: application/json; api_version=20260309" \
  -d '{
    "certificate_id": 42
  }'

If you omit certificate_id, Quaderno assigns your account's active Spanish certificate automatically.

The API returns 201 with the integration, or 422 if a prerequisite isn't met.

Checking and updating the integration​

  • Use GET /einvoicing/verifactu to retrieve the integration. It returns 404 if Verifactu hasn't been activated yet.
  • Use PUT /einvoicing/verifactu to rotate the certificate by passing a new certificate_id.
  • To renew an expiring certificate, replace its file with PUT /certificates/{id}. Since only one active certificate per country is allowed, the integration keeps using the same certificate ID. A certificate linked to an active integration cannot be deleted.

Sending sales and refunds data​

Send your sales and refunds data to Quaderno as usual, using our Transactions API.

These guides will walk you through the process:

When the Verifactu integration is enabled, Quaderno will automatically send all invoices and credit notes to the AEAT.

Verifactu's verification_code and verification_url will be available from the API responses, and generated invoices will display their verification ID and a QR code, allowing your customers to confirm the status of the invoice with the Spanish Tax Agency.

Here's an example of a payload to POST to the /transactions endpoint:

{
  "type": "sale",
  "currency": "EUR",
  "customer": {
    "first_name": "Luis",
    "last_name": "García",
    "street_line_1": "Calle Alcalá",
    "city": "Madrid",
    "postal_code": "28014",
    "country": "ES",
    "tax_id": "00000000T"
  },
  "evidence": {
    "billing_country": "ES",
    "ip_address": "255.255.255.255",
    "bank_country": "ES"
  },
  "items": [
    {
      "description": "Suscripción mensual a contenido digital",
      "amount": 9.90,
      "product_code": "DIG_ES_001",
      "tax": {
        "country": "ES",
        "rate": 21.0,
        "tax_code": "eservice",
        "name": "IVA"
      }
    }
  ],
  "payment": {
    "method": "credit_card"
  },
  "processor": "aPaymentProcessor",
  "processor_id": "pp_0123456789"
}

Delivery events​

When an invoice or credit note is sent to the Spanish Tax Agency via Verifactu, Quaderno will generate a delivery event to notify you of the result. You can subscribe to these events using webhooks to receive real-time notifications in your application.

The available delivery events are:

  • delivery.succeeded – The document was successfully delivered to the tax authorities.
  • delivery.failed – The delivery failed due to a technical error (e.g., network issues, service unavailable).
  • delivery.rejected – The tax authorities rejected the document due to validation errors in the data.

These events allow you to automate your workflow and take appropriate action based on the delivery status, such as notifying customers, retrying failed deliveries, or correcting rejected documents.

Limitations​

Once you enable the Verifactu integration, keep these limitations in mind:

  • You won't be able to assign a custom number or issue_date to invoices or receipts. They will be assigned automatically.
  • For full invoices to Spanish customers, Quaderno will validate that the customer's name and NIF are registered with the Spanish Tax Agency. If the validation fails, the invoice will be saved as a draft, requiring you to manually correct the customer details in the account inbox before it can be sent.
  • The Verifactu integration cannot be disabled. If you need to stop sending invoices, you must contact our support team.