Invopop Integration

Invopop is the third-party e-invoicing platform that handles GOBL validation, Verifactu XML generation, and submission to the Spanish Tax Authority (AEAT). This page documents the Invopop API as it relates to our integration, the GOBL document format, and common error scenarios.

For general context on what e-invoicing is and how it fits into Lavanda, see the E-Invoicing.

External documentation:

• Invopop API Reference

• GOBL Documentation

• Verifactu Addon (GOBL)

• Invopop Console

API Endpoints

Service	Base URL	Purpose
Silo	https://api.invopop.com/silo/v1	Document storage
Transform	https://api.invopop.com/transform/v1	Workflow processing

All requests require a Bearer token:

Authorization: Bearer <api_token>

Each workspace that uses e-invoicing has its own Invopop API token, stored encrypted in the workspace configuration.

Core Flow

The submission process has two steps, both using idempotent PUT requests with client-generated UUID v7 identifiers.

1. PUT /silo/v1/entries/{uuid}     -> Store GOBL document
2. PUT /transform/v1/jobs/{uuid}   -> Submit to Verifactu workflow
3. Webhook                         -> Receive result (accepted/rejected)

Step 1: Store the Document

Upload a GOBL invoice to Invopop's Silo:

curl -X PUT "https://api.invopop.com/silo/v1/entries/${ENTRY_UUID}" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"data": { ...GOBL document... }}'

The entry UUID must be a UUID v7 (timestamp-based). Invopop rejects standard v4 UUIDs for the invoices folder.

Step 2: Trigger the Workflow

Submit the stored document to a Verifactu workflow:

curl -X PUT "https://api.invopop.com/transform/v1/jobs/${JOB_UUID}?wait=30" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "<workflow_id>",
    "silo_entry_id": "<entry_uuid>"
  }'

The ?wait=30 parameter makes the call synchronous (up to 30 seconds), returning the result inline instead of requiring a separate poll.

Step 3: Receive Results

After a successful submission, the Silo entry is updated with stamps and metadata:

Field	Location in response	Description
QR code URL	data.head.stamps[] where prv == "verifactu-qr"	A link customers can use to verify the invoice on AEAT's website
Verifactu hash	data.head.stamps[] where prv == "verifactu-hash"	Cryptographic proof of submission
Submission status	meta[] where src == "verifactu"	e.g. "Correcto"

Fetch the updated entry to read these fields:

curl "https://api.invopop.com/silo/v1/entries/${ENTRY_UUID}" \
  -H "Authorization: Bearer ${API_TOKEN}"

Idempotency and Entry Updates

PUT is create-only. Once a Silo entry exists, a subsequent PUT returns 409 Conflict with the message "entry already exists with same id". This makes PUT safe to retry on network failures.

To update an existing entry's data (e.g. to fix an error before resubmission), use PATCH:

curl -X PATCH "https://api.invopop.com/silo/v1/entries/${ENTRY_UUID}" \
  -H "Authorization: Bearer ${API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"data": { ...updated GOBL document... }}'

Method	Entry exists?	Result
PUT	No	Creates entry
PUT	Yes	409 Conflict
PATCH	Yes	Updates entry data (even if signed or in error state)
DELETE	--	Not supported (returns 404)

Webhooks

Invopop sends webhook notifications when a workflow job completes. The payload contains:

{
  "id": "webhook-id",
  "event": "success",
  "transform_job_id": "job-uuid",
  "silo_entry_id": "entry-uuid"
}

The webhook only contains the silo_entry_id, not the full document. To get the result details (QR code, hash, status), fetch the entry from the Silo API using the silo_entry_id.

GOBL Document Format

GOBL (Go Business Language) is an open-source standard for structured financial documents. All invoices submitted through Invopop must be in GOBL JSON format.

Regular Invoice (F1)

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$regime": "ES",
  "$addons": ["es-verifactu-v1"],
  "code": "INV-001",
  "issue_date": "2025-01-15",
  "currency": "EUR",
  "supplier": {
    "name": "Supplier SL",
    "tax_id": { "country": "ES", "code": "B86854189" }
  },
  "customer": {
    "name": "Customer SL",
    "tax_id": { "country": "ES", "code": "B98602642" }
  },
  "lines": [{
    "i": 1,
    "quantity": "1",
    "item": { "name": "Accommodation", "price": "100.00" },
    "sum": "100.00",
    "taxes": [{
      "cat": "VAT",
      "percent": "21%",
      "ext": { "es-verifactu-op-class": "S1", "es-verifactu-regime": "01" }
    }],
    "total": "100.00"
  }],
  "totals": {
    "sum": "100.00",
    "total": "100.00",
    "taxes": {
      "categories": [{
        "code": "VAT",
        "rates": [{
          "base": "100.00",
          "percent": "21%",
          "amount": "21.00",
          "ext": { "es-verifactu-op-class": "S1", "es-verifactu-regime": "01" }
        }],
        "amount": "21.00"
      }],
      "sum": "21.00"
    },
    "tax": "21.00",
    "total_with_tax": "121.00",
    "payable": "121.00"
  }
}

Credit Note (R4)

Credit notes reference the original invoice via the preceding field. They use "type": "credit-note" and do not include the $addons field.

{
  "$schema": "https://gobl.org/draft-0/bill/invoice",
  "$regime": "ES",
  "type": "credit-note",
  "code": "CN-001",
  "issue_date": "2025-01-20",
  "currency": "EUR",
  "preceding": [{
    "uuid": "original-invoice-uuid",
    "type": "standard",
    "issue_date": "2025-01-15",
    "code": "INV-001"
  }],
  "supplier": {
    "name": "Supplier SL",
    "tax_id": { "country": "ES", "code": "B86854189" }
  },
  "customer": {
    "name": "Customer SL",
    "tax_id": { "country": "ES", "code": "B98602642" }
  },
  "lines": [{
    "quantity": "1",
    "item": { "name": "Refund", "price": "100.00" },
    "taxes": [{ "cat": "VAT", "rate": "standard" }]
  }]
}

Multi-line Invoice with Mixed VAT Rates

When an invoice contains line items at different VAT rates, each rate appears as a separate entry in totals.taxes.categories[].rates[]:

{
  "$regime": "ES",
  "$addons": ["es-verifactu-v1"],
  "lines": [
    {
      "i": 1,
      "quantity": "2",
      "item": { "name": "Standard service", "price": "50.00" },
      "sum": "100.00",
      "taxes": [{
        "cat": "VAT",
        "percent": "21%",
        "ext": { "es-verifactu-op-class": "S1", "es-verifactu-regime": "01" }
      }],
      "total": "100.00"
    },
    {
      "i": 2,
      "quantity": "1",
      "item": { "name": "Reduced rate item", "price": "50.00" },
      "sum": "50.00",
      "taxes": [{
        "cat": "VAT",
        "percent": "10%",
        "ext": { "es-verifactu-op-class": "S1", "es-verifactu-regime": "01" }
      }],
      "total": "50.00"
    }
  ],
  "totals": {
    "sum": "150.00",
    "total": "150.00",
    "taxes": {
      "categories": [{
        "code": "VAT",
        "rates": [
          {
            "base": "100.00",
            "percent": "21%",
            "amount": "21.00",
            "ext": { "es-verifactu-op-class": "S1", "es-verifactu-regime": "01" }
          },
          {
            "base": "50.00",
            "percent": "10%",
            "amount": "5.00",
            "ext": { "es-verifactu-op-class": "S1", "es-verifactu-regime": "01" }
          }
        ],
        "amount": "26.00"
      }],
      "sum": "26.00"
    },
    "tax": "26.00",
    "total_with_tax": "176.00",
    "payable": "176.00"
  }
}

Customer Identity Mapping

How a customer is represented in GOBL depends on their ID type and country.

Spanish Customers

Spanish customers with a tax ID (CIF for companies, NIF/DNI for individuals) use the tax_id field:

"customer": {
  "name": "Spanish Customer SL",
  "tax_id": { "country": "ES", "code": "B98602642" }
}

Foreign Customers

Foreign customers without a Spanish tax ID use the identities field with a Verifactu identity type extension:

Passport:

"customer": {
  "name": "Italian Customer",
  "identities": [{
    "type": "passport",
    "code": "YB1962154",
    "country": "IT",
    "ext": { "es-verifactu-identity-type": "03" }
  }]
}

EU VAT number:

"customer": {
  "name": "German Company GmbH",
  "identities": [{
    "type": "tax-id",
    "code": "DE123456789",
    "country": "DE",
    "ext": { "es-verifactu-identity-type": "02" }
  }]
}

Verifactu Identity Type Codes

Code	Description	When to use
02	NIF-IVA	EU VAT number (non-Spanish)
03	Passport	Passport number
04	Official ID	National ID card from country of residence
05	Residence certificate	Spanish residence certificate
06	Other document	Other supporting identification (e.g. driver's license)
07	Not registered	Customer has no identification

Spain / Verifactu Reference

Document Types

Verifactu Code	Type	GOBL representation
F1	Regular invoice	Default (no type field)
R4	Credit note	"type": "credit-note"

Tax Extensions

Both line-level taxes and totals-level rates must include these extensions:

Extension	Values
es-verifactu-op-class	S1 (standard taxable), S2 (exempt)
es-verifactu-regime	01 (general regime), 02 (simplified regime)

Bypass Mode

Bypass mode tells GOBL to preserve pre-calculated totals instead of recalculating them. It is activated by adding "$tags": ["bypass"] to the document.

Without bypass mode, GOBL recalculates VAT by grouping line items by rate, summing their net amounts, and applying the tax percentage to the aggregated total. This can cause small rounding differences (typically plus or minus one cent) compared to per-line-item calculations.

Note: We are planning to remove bypass mode from our integration by aligning our internal VAT calculations with GOBL's aggregation method. See the Reference for details on the rounding issue.

Known Issue: Bypass Mode Fails for Credit Notes

Document Type	Bypass Mode	Result
Regular invoice (F1)	Yes	Works
Credit note (R4)	Yes	Fails with verifactu.generate error
Credit note (R4)	No	Works

This is a known Invopop bug reported in January 2026. Credit notes submitted with $tags: ["bypass"] fail at the verifactu.generate step with an "unexpected data error". The workaround is to submit credit notes without bypass mode.

Error Recovery

When a workflow fails (e.g. rejected at verifactu.generate or verifactu.send), entries can be corrected and resubmitted:

1. PUT  /silo/v1/entries/{uuid}       -> Store entry (data has an error)
2. PUT  /transform/v1/jobs/{job1}     -> Workflow fails
3. PATCH /silo/v1/entries/{uuid}      -> Fix the data
4. PUT  /transform/v1/jobs/{job2}     -> New job UUID, resubmit

Each resubmission requires a new job UUID. The entry UUID stays the same.

Constraint: Hash Chain Integrity

Once Verifactu has accepted a record, it becomes part of a cryptographic hash chain. Changing the invoice code and resubmitting fails with error 3002 ("No existe el registro de facturacion"). To correct an accepted invoice, issue a credit note instead.

Scenario	Can change code?	Can change other fields?
Failed at verifactu.generate	Yes	Yes
Rejected by verifactu.send	Yes (likely)	Yes (likely)
Accepted by verifactu.send	No (error 3002)	Not tested

PATCH Behaviour on Signed Entries

PATCH updates the GOBL document and digest even on signed or error-state entries. The original signature in sigs is retained but stale. On resubmission, Invopop skips the "Sign Envelope" step ("already signed"), which does not block Verifactu processing.

Verifactu Cancellation

• Rejected invoices are not counted as reported to Verifactu, so no cancellation is needed

• To cancel an accepted invoice, a credit note must be issued (there is no "cancel" API)

• Invopop workflows can be configured to auto-cancel rejected invoices in Verifactu

Supplier Registration

New suppliers must be registered with Invopop before submitting invoices:

1. Create the supplier as a Silo entry with the org/party GOBL schema

2. Run a registration workflow to register the supplier with the tax authority

This is typically a one-time setup step per workspace.

Common Errors

Error	Cause	Solution
invalid check digit	Invalid Spanish CIF/NIF	Use a valid tax ID
invalid format	Malformed tax ID	Use the correct CIF/NIF format
request duplicated	Same supplier + invoice code combination	Use unique invoice codes per supplier
party is not registered	Supplier not registered with Invopop	Complete the supplier registration flow
unexpected data error	Bypass mode used with a credit note	Remove the bypass tag for credit notes
schema validation	Missing required fields in bypass mode	Include all ext fields on lines and totals rates
No existe el registro de facturacion (3002)	Resubmitting with a changed code after Verifactu accepted the original	Cannot change the code after acceptance; issue a credit note instead
entry already exists with same id	PUT on an existing Silo entry	Use PATCH to update, or use a new UUID

Best Practices

1. Generate UUID v7 identifiers client-side for idempotent retries (Invopop rejects v4 UUIDs)

2. Use ?wait=30 on job creation to get the result synchronously

3. Check the faults array in the job response even when the top-level status is "OK"

4. Use unique invoice codes per supplier (Verifactu rejects duplicates)

5. Include tax extensions on both line-level taxes and totals-level rates

6. Use PATCH for corrections, not PUT (PUT cannot update existing entries)

7. Generate a new job UUID per retry while reusing the same entry UUID