---
name: Invopop
description: Use when building e-invoicing integrations, processing business documents across multiple countries, creating automated document workflows, managing tax compliance submissions, or integrating with government tax authorities and business networks like Peppol.
metadata:
    mintlify-proj: invopop
    version: "1.0"
---

# Invopop Skill

## Product summary

Invopop is a translation engine for business documents. It accepts invoices and other business documents in GOBL (Go Business Language)—a universal open-source format—and converts them to local formats required by tax authorities and business networks across 30+ countries. The platform provides a REST API organized into five services: **Silo** (document storage and validation), **Transform** (workflow execution), **Sequences** (sequential numbering), **Access** (workspace management), and **Utils** (testing). Key entry points: Console at https://console.invopop.com, API at https://api.invopop.com, and authentication via Bearer tokens generated in Console → Configuration → API Keys. Workflows automate document processing with sequential steps, error handling, and conditional logic. All documents are stored as GOBL envelopes with digital signatures and audit trails.

## When to use

Reach for this skill when:
- Building e-invoicing integrations that must comply with multiple country tax regimes (Spain VERI*FACTU, Italy SDI, France Chorus Pro, Poland KSeF, Mexico SAT, etc.)
- Creating automated workflows to process invoices, purchase orders, delivery notes, or payment receipts
- Integrating with Peppol network for B2B/B2G document exchange
- Uploading documents via API and need to validate, transform, or submit them to tax authorities
- Debugging failed workflow jobs or document processing errors
- Setting up sequential invoice numbering with series management
- Receiving invoices from government networks or business partners and converting them to a standard format
- Implementing white-label invoicing where end-users don't see Invopop branding

## Quick reference

### API Services and Endpoints

| Service | Purpose | Base Path |
|---------|---------|-----------|
| **Silo** | Store, validate, and version GOBL documents | `/silo/v1` |
| **Transform** | Create and execute workflows, manage jobs | `/transform/v1` |
| **Sequences** | Generate sequential invoice numbers | `/sequence/v1` |
| **Access** | Fetch/update workspace details | `/access/v1` |
| **Utils** | Test connection (ping) | `/utils/v1` |

### Document Schemas

| Schema | Use Case |
|--------|----------|
| `bill/invoice` | Sales invoices, credit notes, debit notes |
| `bill/order` | Purchase orders |
| `bill/delivery` | Delivery notes, despatch advice |
| `bill/payment` | Payment receipts, payment links |
| `bill/status` | Lifecycle events (acknowledgement, approval, rejection) |
| `org/party` | Suppliers, customers, parties (for registration) |
| `org/item` | Product/service catalog items |

### Document States

Use `Set State` workflow step to mark document progress:
- `Empty` — Initial state
- `Draft` — Requires further changes
- `Processing` — Currently being processed
- `Registered` — Party granted invoice rights
- `Sent` — Successfully transmitted to authority/customer
- `Received` — Received from network
- `Error` — Processing failed
- `Paid` — Invoice marked as paid
- `Void` — Cancelled or voided

### Common Workflow Steps

| Step | Provider | Purpose |
|------|----------|---------|
| Set State | `silo.state` | Mark document progress |
| Modify Document | `silo.modify` | Transform document with JQ expressions |
| Generate PDF | `pdf.generate` | Create tax-compliant PDF |
| Send to Tax Authority | `[country].send` | Submit to government regime (VERI*FACTU, SDI, etc.) |
| Send Webhook | `webhook.send` | POST to external endpoint with job results |
| Send Email | `email.send` | Notify via email with document details |
| Sign Envelope | `silo.close` | Digitally sign document |
| Add Sequential Code | `sequence.add` | Assign invoice number from series |
| Lookup Participant | `peppol.lookup` | Find Peppol participant ID |
| Send Peppol | `peppol.send` | Transmit via Peppol network |

### Authentication

Generate API key in Console → Configuration → API Keys. Include in all requests:
```bash
Authorization: Bearer <YOUR_TOKEN>
```

Test with:
```bash
curl -H "Authorization: Bearer $INVOPOP_TOKEN" https://api.invopop.com/utils/v1/ping
```

## Decision guidance

### When to use PUT vs POST for entry creation

| Scenario | Method | Reason |
|----------|--------|--------|
| Concurrent requests, need guaranteed idempotency | PUT `/silo/v1/entries/{id}` | UUID in path prevents duplicates |
| Sequential requests, simple retry logic | POST `/silo/v1/entries` | Simpler, use `key` field for idempotency |
| Updating existing entry | PATCH `/silo/v1/entries/{id}` | Merge changes into existing document |

### When to use Console vs API

| Task | Use Console | Use API |
|------|-------------|---------|
| Create/test workflows visually | ✓ | — |
| Debug failed jobs | ✓ | — |
| Upload single document manually | ✓ | — |
| Bulk document processing | — | ✓ |
| Integrate with external systems | — | ✓ |
| Run workflow on demand | ✓ | ✓ |

### When to handle errors with conditions vs error flow

| Situation | Approach | Example |
|-----------|----------|---------|
| Expected, recoverable error from a step | Add condition to step | Tax ID not found in registry (code 4107) |
| Unhandled error, need fallback | Error handling flow | Any step fails unexpectedly |
| Multiple error codes from same step | Multiple conditions | Different AEAT error codes |

## Workflow

### Typical document processing flow

1. **Prepare document in GOBL format**
   - Use GOBL Builder (build.gobl.org) to validate structure
   - Include required fields: supplier, customer, lines, totals, currency, regime
   - Use UUID v1 or v7 for invoices; v3/v4/v5 for parties

2. **Upload to Silo**
   - POST/PUT to `/silo/v1/entries` with GOBL data
   - Include `key` field for idempotency (prevents duplicates)
   - Invopop validates, calculates totals, normalizes fields
   - Receive `silo_entry_id` in response

3. **Create or select workflow**
   - In Console: Workflows → Create workflow → select template
   - Or fetch existing workflow ID from API
   - Workflow must match document schema (invoice, party, etc.)

4. **Execute workflow (job)**
   - POST/PUT to `/transform/v1/jobs` with `silo_entry_id` and `workflow_id`
   - Workflow steps execute sequentially
   - Each step returns status (OK/KO) and optional code
   - Conditions route based on status/code; unhandled errors trigger error flow

5. **Monitor and retrieve results**
   - Poll `/transform/v1/jobs/{job_id}` or wait for webhook
   - Webhook payload includes `transform_job_id`, `silo_entry_id`, `faults` array
   - Fetch entry with `/silo/v1/entries/{silo_entry_id}` for state and attachments
   - Check job's `faults` array (not entry's) for error details

6. **Handle outcomes**
   - Success: Document state = Sent, attachments (PDF/XML) available
   - Failure: Document state = Error, check job faults for reason
   - Retry: Use same `key` to retry; Invopop detects and returns cached result

### Creating a workflow with error handling

1. Open Console → Workflows → Create workflow
2. Select template matching document schema
3. Add steps by clicking "Add step" and selecting provider
4. Configure each step (e.g., Set State to "Processing")
5. Add conditions to steps: click `...` → Add condition → match status/code
6. Enable error handling: click "Handle Errors" at bottom
7. Add steps to error flow (e.g., Set State to "Error", Send Email)
8. Save draft, then Publish to make live

## Common gotchas

- **State is metadata, not validation**: Setting state to "Sent" does not validate the document. Use workflow steps to actually process it. State only changes when explicitly set via workflow or API.

- **Don't read entry faults for job errors**: A single entry can be processed by many jobs. Always read faults from the job (`/transform/v1/jobs/{job_id}`), not the entry. Entry faults are backwards-compatible only.

- **UUID versions matter**: Use v1 or v7 for short-lived documents (invoices); v3/v4/v5 for long-lived data (parties, items). Silo enforces this per folder.

- **Idempotency requires key or UUID**: POST with `key` field or PUT with UUID in path. Without either, duplicate requests create duplicate entries.

- **Workflow steps execute sequentially**: Next step only runs after previous completes. No parallel execution. Design for this.

- **Conditions don't prevent error flow**: If a condition has status KO and you don't handle it, error flow still runs. Use "End workflow here" in condition to stop.

- **Tax authority delays**: Some regimes (Italy SDI) take hours or days to respond. Don't block UI on job completion; use webhooks and async polling.

- **Series must exist before use**: "Add sequential code" step requires series to be pre-created via API or Console. Passing `sequence-series-id` argument overrides step config.

- **Regime determines available steps**: Not all workflow steps work with all regimes. Consult country-specific guides (e.g., Spain VERI*FACTU, France Chorus Pro).

- **Envelope signature is permanent**: Once a document is signed with a UUID, that ID cannot change. Editing removes signature and creates new unsigned version.

## Verification checklist

Before submitting a document processing task:

- [ ] Document is valid GOBL (use GOBL Builder or `/silo/v1/gobl/build` endpoint)
- [ ] Required fields present: supplier, customer, lines, totals, currency, regime
- [ ] UUID is correct version (v1/v7 for invoices, v3/v4/v5 for parties)
- [ ] API key is valid and has access to workspace
- [ ] Workflow exists and is published (not draft)
- [ ] Workflow schema matches document schema (invoice → invoice workflow)
- [ ] All required apps are enabled in workspace (e.g., Peppol, country-specific)
- [ ] Series exists if workflow uses "Add sequential code" step
- [ ] Error handling flow is configured if job might fail
- [ ] Webhook endpoint is ready if using async processing
- [ ] Test in sandbox workspace before going live
- [ ] Job completed successfully: check state and attachments in entry
- [ ] If failed: read job faults array, not entry faults

## Resources

- **Comprehensive page listing**: https://docs.invopop.com/llms.txt
- **API Reference**: https://docs.invopop.com/api-ref/introduction
- **Console & Workflows**: https://docs.invopop.com/console/workflow-intro
- **GOBL Format Guide**: https://docs.gobl.org (external, open-source)

---

> For additional documentation and navigation, see: https://docs.invopop.com/llms.txt