canonical: https://jentic.com/apis/faktoora.com/faktoora

# Faktoora API

Faktoora is an e-invoicing platform focused on the German XRechnung and ZUGFeRD electronic invoice formats. The API exposes a small surface - list invoices, create an invoice, fetch a single invoice, validate it against the format spec, and download the rendered file - that covers the full lifecycle for a compliance-bound invoice in five operations. It is a fit for businesses that need to meet German B2G e-invoicing requirements without building XRechnung tooling in-house.

## For AI agents

Create, validate, and download XRechnung and ZUGFeRD electronic invoices. Useful for German B2G e-invoicing automation and compliance flows.

## Scope

Does not handle payment collection, accounting ledger entries, or tax filing - use for XRechnung and ZUGFeRD invoice creation, validation, and download only.

## Capabilities

- Create an XRechnung or ZUGFeRD invoice from structured fields
- List previously issued invoices on the workspace
- Validate an invoice against XRechnung and ZUGFeRD format rules
- Download a rendered invoice file in the chosen e-invoice format
- Fetch a single invoice record by id

## Use cases

### German B2G E-Invoicing

A business invoicing a German public-sector customer must deliver an XRechnung-compliant invoice. The agent creates the invoice via POST /invoices, calls `/invoices/{id}/validate` to confirm format compliance, and pulls the rendered file with `/invoices/{id}/download.` End-to-end the flow takes three calls and avoids any in-house XRechnung tooling.

Example prompt: POST the invoice payload to /invoices, call POST `/invoices/{id}/validate` to confirm compliance, and download the rendered XML via GET `/invoices/{id}/download.`

### Validation Pre-Check Before Sending

Before an accounting system emails an invoice to a German government customer, it pre-validates the payload through Faktoora. The `/invoices/{id}/validate` endpoint surfaces XRechnung rule violations so the issuer can correct fields before the invoice leaves their system. Useful as a guard in monthly invoicing batch runs.

Example prompt: POST the candidate invoice to /invoices, call `/invoices/{id}/validate`, and surface any rule violations in the response back to the accounting system before delivery.

### Invoice Download for Archival

After issuance, a finance system pulls the rendered invoice file and archives it for the statutory retention period. The flow uses GET /invoices to enumerate invoices, GET `/invoices/{id}` for metadata, and GET `/invoices/{id}/download` to fetch the file. Suited to nightly archival jobs that mirror invoices into a long-term store.

Example prompt: Call GET /invoices to list issued invoices for the day, then for each call GET `/invoices/{id}/download` and write the binary response to the archive store.

### AI Agent Compliance Helper

An AI agent helping a small business comply with German e-invoicing rules uses Jentic to discover Faktoora's five operations and walk through invoice creation, validation, and delivery. Jentic exposes the schemas with example payloads, so the agent can prompt the user for the missing fields and submit a valid invoice without reading the API docs.

Example prompt: Call jentic.search with 'create XRechnung invoice', load the /invoices and `/invoices/{id}/validate` operations, prompt the user for the missing required fields, and execute create-then-validate.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/invoices` | List invoices on the workspace |
| POST | `/invoices` | Create an XRechnung or ZUGFeRD invoice |
| GET | `/invoices/{id}` | Fetch a single invoice by id |
| POST | `/invoices/{id}/validate` | Validate an invoice against format rules |
| GET | `/invoices/{id}/download` | Download the rendered invoice file |

## Key resources

- **Invoices** — Create, list, and fetch electronic invoices in XRechnung and ZUGFeRD formats
- **Validation** — Validate an invoice against the XRechnung and ZUGFeRD format rules

## Why Jentic

- **Setup:** Wiring the Faktoora API by hand means registering its X-API-Key scheme, targeting the api.faktoora.com/api/v1 host, and sequencing the create-validate-download invoice calls yourself. Through Jentic you install once, import the Faktoora API from the API Directory, store the API key once, and your agent calls it.
- **Permission scoping:** Faktoora puts the invoice id in the URL path (`/invoices/{id}/validate`, `/invoices/{id}/download`), so a rule can pin your agent to one invoice: it can validate and download that invoice and nothing else. You choose the operations it may call, so creating new invoices is not included unless you add it.
- **Credential handling:** Your Faktoora X-API-Key is stored once, encrypted, by your own Jentic One instance and attached at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create an XRechnung invoice' or 'validate an e-invoice', and Jentic returns the matching Faktoora operation with its input schema so the agent chains create, validate, and download without browsing the developer docs.

## Related APIs

- **Fakturoid** — Czech online invoicing platform with a broader invoicing and accounting surface
- **Stripe** — Payment collection layer to pair with the issued invoice
- **SumUp** — European card payment provider often paired with German invoicing

## FAQ

### What authentication does the Faktoora API use?

Faktoora uses an X-API-Key header on every request. Through Jentic the key is stored encrypted in the vault and attached to outgoing /invoices calls so the raw value never enters the agent's context.

### Can I create an XRechnung invoice with the Faktoora API?

Yes. POST the invoice payload to /invoices and Faktoora returns the new invoice id. Follow up with `/invoices/{id}/validate` to confirm XRechnung compliance and `/invoices/{id}/download` to fetch the rendered XML file.

### What are the rate limits for the Faktoora API?

Rate limits are not declared in the spec. Faktoora applies fair-use throttling on the production endpoint - keep the create, validate, and download chain sequential per invoice rather than pushing all three calls in parallel.

### How do I validate an invoice through Jentic?

Run pip install jentic, call jentic.search with 'validate XRechnung invoice', load the `/invoices/{id}/validate` operation, and execute it with the invoice id returned from the create call. The X-API-Key is replayed from the vault.

### Does Faktoora support ZUGFeRD as well as XRechnung?

Yes. The API description covers both XRechnung and ZUGFeRD formats. The format selection is part of the create-invoice payload, and the validate endpoint runs the format-specific rule set against the invoice.

### Where can I download the rendered invoice file?

Call GET `/invoices/{id}/download` with the invoice id. The endpoint returns the rendered file in the chosen e-invoice format, suitable for archival or for sending to the recipient through a separate delivery channel.

### Can I limit what my agent is allowed to do with the Faktoora API?

Yes. Because you run Jentic One yourself, your own rules decide which Faktoora operations the agent may call, so you can allow it to validate and download invoices while leaving the create-invoice operation off. Faktoora also puts the invoice id in the URL path for `/invoices/{id}/validate` and `/invoices/{id}/download`, so a rule can pin the agent to a single invoice and block access to any other. Your X-API-Key is held by your own Jentic One instance and attached only to the calls you have permitted.