# einvoice.asapeca.com — API and MCP server

> Check e-invoices — XRechnung, ZUGFeRD, Factur-X, EN 16931 in CII or UBL, as XML or PDF — with the official KoSIT validator, veraPDF and the ZUGFeRD rules, and recalculate every amount. Create a valid XRechnung from JSON. Open: no key, no sign-up. Files are checked in memory and not stored.

Base URL: `https://einvoice.asapeca.com`. Description: [OpenAPI 3.1](https://einvoice.asapeca.com/api/v1/openapi.json). This text for AI agents: [llms.txt](https://einvoice.asapeca.com/llms.txt).

## When to call it

- You have an invoice file and need to know whether a German recipient (or the public sector, or Peppol) will accept it, and what to fix: call **check**.
- You have invoice data (an order, a shop export) and need an XRechnung: call **create**. It computes the amounts, writes the XML and checks it.
- You changed an invoice: check it again. The answer is the same for the same file.

## Check an invoice

`POST /api/v1/check` — the file as the request body (XML or PDF, at most 10 MB), or as the field `file` of `multipart/form-data`.

```bash
curl -s --data-binary @invoice.xml -H 'Content-Type: application/xml' \
  https://einvoice.asapeca.com/api/v1/check
curl -s -F file=@invoice.pdf https://einvoice.asapeca.com/api/v1/check
```

```python
import requests
r = requests.post("https://einvoice.asapeca.com/api/v1/check",
                  data=open("invoice.xml", "rb"), headers={"Content-Type": "application/xml"})
report = r.json()
print(report["verdict"])
for p in report["problems"]:
    if p["level"] == "error":
        print(p["source"], p["code"], p.get("field", {}).get("id"), p["text"]["en"], p.get("fix", ""), p.get("expected", ""))
```

```javascript
import { readFile } from "node:fs/promises";
const r = await fetch("https://einvoice.asapeca.com/api/v1/check", {
  method: "POST", headers: { "Content-Type": "application/xml" }, body: await readFile("invoice.xml"),
});
const report = await r.json();
console.log(report.verdict, report.problems.filter(p => p.level === "error"));
```

### Reading the answer

`verdict` — decide by this field:

| verdict | meaning |
|---|---|
| `ok` | valid, nothing to fix |
| `warnings` | valid; warnings of the validators or a difference found by our recalculation — read `problems` |
| `rejected` | invalid: at least one problem with level `error`; a recipient will reject it |
| `unchecked` | no official rules for this profile (e.g. XRechnung older than 3.0) |
| `error` | not an invoice we can check (HTTP 422); `error.code` says why |

`problems` — every finding: errors first, and among them first the values to write (`source: recalc`, `fix: expected`). Each has:

- `source`: `kosit` (the official validator: XRechnung and EN 16931 rules), `zugferd` (ZUGFeRD / Factur-X rules), `pdfa` (the PDF/A check; for tax purposes the XML decides, so these are warnings at most), `recalc` (our recalculation of the amounts);
- `code`: the rule, e.g. `BR-DE-15`, `BR-CO-10`; for `recalc` the check: `line`, `total`, `vat-basis`, `vat-tax` …;
- `level`: `error` makes the invoice invalid, `warning` and `info` do not;
- `field`: the business term of EN 16931 (`BT-10` Buyer reference, `BT-116` VAT taxable amount …) with its name in German and English and `xpath`, where the field is in this file's syntax (CII or UBL) — also for a field that is missing;
- `line` (position of the invoice line, 1-based) or `lineId` (`recalc`: the line's BT-126), `path` (XPath);
- `text`: what is wrong — the validator's own text (one language; German for the BR-DE rules) in both `de` and `en`, our texts in two languages;
- `help`: a page on the rule with causes and the fix, if we have one;
- `recalc` only: `declared` (in the invoice), `expected` (by EN 16931 from the invoice's own amounts), `diff`, `fix` (what to do, see below), `cause` (`price-with-vat`, `rounding`, `from-lines`, `from-vat` …), `rule` (the official rule on the same sum).

Also: `file` (`container` xml or pdf, `syntax`, `profile` as BT-24, `profileKey` e.g. `xrechnung-3`, `number`, `currency`, `size`, `sha256`), `official` (`engine`, `config` — the rules and their date, `scenario`, `verdict` `accept` / `reject` / `no-scenario`), `zugferd` (PDF/A and ZUGFeRD), `recalc` (`totals` and `vat`: declared against expected), `pdfText` (a PDF: values of the XML its visible text does not show — a hint, the XML decides), `ms` (duration). The full schema: `Check` in the OpenAPI description.

### Fixing an invoice

1. Take the problems with level `error`, in the order given: first come the wrong values (`source: recalc`, `fix: expected`). A wrong amount often breaks several rules at once (`BR-CO-10`, `BR-S-08` …); fixing the value clears them all.
2. `recalc` — follow `fix`:
   - `expected`: write `expected` into `field` (for a line: the line with `lineId`);
   - `lines` or `vat`: this sum is right — keep it. The wrong values are line amounts (BT-131) or VAT amounts of the breakdown (BT-117); they come as their own problems (`code` `line` or `vat-tax`, level `error`, `fix: expected`). Do **not** write `expected` of the sum.
3. `kosit` and `zugferd`: the rule says what is missing or wrong; `field.xpath` says where it goes, `help` explains the rule. `BR-DE-15` (BT-10 Buyer reference) is the most common: for a public buyer the Leitweg-ID, for a business any reference agreed, e.g. the order number.
4. Check again until `verdict` is `ok` or `warnings`.

## Create an XRechnung

`POST /api/v1/create` — the invoice as JSON. Send seller, buyer, lines (quantity, unit, net price, VAT category and rate), delivery date and payment; do **not** send line nets, the VAT breakdown or totals: they are computed by EN 16931. Unknown fields are an error. Amounts as numbers or strings (`"19.99"`).

```bash
curl -s https://einvoice.asapeca.com/api/v1/create -H 'Content-Type: application/json' -d '{
  "format": "cii", "profile": "xrechnung",
  "invoice": {
    "number": "RE-1001", "issueDate": "2026-10-20", "type": "380", "currency": "EUR", "buyerRef": "#1001",
    "seller": {"name": "Shop GmbH", "vatId": "DE123456789", "eaddr": {"scheme": "EM", "value": "invoice@shop.example"},
      "address": {"street": "Hauptstr. 1", "city": "Berlin", "zip": "10115", "country": "DE"},
      "contact": {"name": "Accounts", "phone": "+49 30 1234567", "email": "invoice@shop.example"}},
    "buyer": {"name": "Kunde KG", "eaddr": {"scheme": "EM", "value": "ap@kunde.example"},
      "address": {"street": "Weg 2", "city": "Hamburg", "zip": "20095", "country": "DE"}, "contact": {}},
    "delivery": {"date": "2026-10-19"},
    "payment": {"means": "58", "accounts": [{"iban": "DE02120300000000202051"}], "terms": "14 days net"},
    "lines": [{"id": "1", "qty": 2, "unit": "H87", "price": "19.99", "category": "S", "rate": 19, "name": "Toolbox"}]
  }}'
```

- `format`: `cii` (default), `ubl` or `zugferd` — ZUGFeRD 2: a PDF/A-3 with the visible invoice and the CII inside (profile `EN16931` or `XRECHNUNG` after `profile`), `lang` `de` (default) or `en` is the language of the visible invoice; `profile`: `xrechnung` or `en16931`; when omitted, `xrechnung` for `cii` and `ubl`, `en16931` for `zugferd` — its XML is then named `factur-x.xml`, the name every program that reads ZUGFeRD finds (`xrechnung` gives ZUGFeRD in the profile XRECHNUNG with `xrechnung.xml`, e.g. for public bodies).
- `issued: true` (HTTP 200): `file.content` is the XML in base64 (for `zugferd` the PDF, `file.type` `application/pdf`) (`file.name`, `file.type`, `file.size`), `check` its check (as above), `totals` (`lineNet`, `allowances`, `charges`, `netTotal`, `tax`, `gross`, `prepaid`, `rounding`, `due` — BG-22) and `vat` (`category`, `rate`, `basis`, `tax`) what was written.
- `issued: false` (HTTP 422): `problems` name the field and the rule (official `BR-*` or ours `CORE-*`) that keep the invoice from being issued; no file.
- Required for each party: `name`, `eaddr`, `address` (with `country`) and `contact` (may be empty `{}`; XRechnung asks for the seller's contact name, phone and e-mail).
- All fields: schema `CreateRequest` in the [OpenAPI description](https://einvoice.asapeca.com/api/v1/openapi.json). VAT categories: `S` standard, `Z` zero, `E` exempt (also small businesses, § 19 UStG — the reason in `exemptions`), `AE` reverse charge, `K` intra-EU supply, `G` export, `O` not subject.

## MCP server

`https://einvoice.asapeca.com/api/v1/mcp` — Streamable HTTP, no key. Tools: `check_invoice` (`xml` as text, or `file_base64` for a PDF — one of the two) and `create_invoice` (the request of `/api/v1/create`). Answers as the REST API: the text content is the same JSON as `structuredContent` (`check_invoice` declares it as `outputSchema`). A refusal — over the limit, busy, no file, a request not by the contract — comes with `isError: true` and the reason as text (the JSON of the error answer). `filename` is optional and not used. Arguments the tool cannot take (no file, both `xml` and `file_base64`, not base64): code `bad-arguments`.

Claude Code:

```bash
claude mcp add --transport http einvoice https://einvoice.asapeca.com/api/v1/mcp
```

Claude (claude.ai, Desktop): Settings → Connectors → Add custom connector, the URL above.

Cursor, `~/.cursor/mcp.json`:

```json
{"mcpServers": {"einvoice": {"url": "https://einvoice.asapeca.com/api/v1/mcp"}}}
```

VS Code, `.vscode/mcp.json`:

```json
{"servers": {"einvoice": {"type": "http", "url": "https://einvoice.asapeca.com/api/v1/mcp"}}}
```

## Limits and errors

- Per IP address: 10 checks a minute with bursts of 20, the same for creating; MCP and REST share these limits. Over the limit: HTTP 429 with `Retry-After` (seconds).
- The file at most 10 MB (HTTP 413); through MCP in base64 about 7 MB.
- Every error answer has `error.code` and `error.text` (`de`, `en`): `no-file`, `too-large`, `rate-limit`, `busy` (HTTP 503, retry after `Retry-After`), `zugferd-unavailable` (HTTP 503, the ZUGFeRD PDF could not be made just now — retry after `Retry-After`; XML still works), `kosit-unavailable` (HTTP 503, the official validator did not answer — retry after `Retry-After`: 5 seconds on a timeout, otherwise 60); for a file we cannot check (HTTP 422): `not-xml-or-pdf`, `plain-pdf` (a PDF without invoice XML: not an e-invoice), `no-invoice-xml`, `xml-too-large`, `pdf-unreadable`, `not-an-invoice`, `zugferd-1`.
- Version: every answer has `version: 1`. Within v1 fields are only added; ignore fields you do not know.

## Terms of use

1. The interface is free and needs no sign-up. There is no claim to availability; we may change, limit or discontinue it. Within version v1 we change the format of the answers only by adding fields.
2. Limits per IP address: 10 checks and 10 creates a minute (bursts of 20). Whoever gets around the limits (e.g. through many addresses) or overloads the service automatically may be blocked.
3. The check follows the official rules (the KoSIT validator with the XRechnung configuration, the rules of ZUGFeRD/Factur-X) and our recalculation. It is not tax or legal advice; the issuer of an invoice remains responsible for its content and issuing.
4. Liability: we are liable without limit for intent and gross negligence and under the Product Liability Act; for slight negligence only for the breach of essential obligations and limited to the foreseeable damage.
5. Data: see the [privacy policy](https://einvoice.asapeca.com/privacy), section “Interface (API) and MCP server”. Whoever checks third parties' invoices through their own programs ensures a legal basis for passing them on.
6. The answers (reports, texts) may be shown and processed in your own programs; when showing them to others, we ask for the note “checked with einvoice.asapeca.com”.

## Data

The file is checked in memory and dropped with the request: no storage, no log of the content. We count anonymously what was checked (format, verdict, rules) and by which kind of client (curl, Python …), without IP addresses. Details: [privacy](https://einvoice.asapeca.com/privacy). The service checks against the official rules; it is not tax advice.
