Documentation & API

Standards & compliance

Every invoice created is therefore a valid ZUGFeRD, Factur-X and EN 16931 file at the same time.

Quick start

curl -X POST https://sichere-erechnung.de/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @invoice.json -o invoice.pdf

Authentication

Every call needs your API key in the header, as a bearer token or X-API-Key:

Authorization: Bearer YOUR_API_KEY

You manage keys in the dashboard (create/revoke). The key is stored only as a hash and is visible only once, when it is created.

Multiple companies (X-Company)

If you run several sender companies in one company group, every API key belongs to one company: without further details, everything is created in that company (number range, sender, archive, receivables). You address another company in the group with the header X-Company, using the company's short code, account ID or VAT ID as the value. With a JSON body, the top-level field company also works; for /v1/automap only next to data, because a JSON body without data is itself the raw text there. For XML and file uploads only the header applies.

X-Company: LTD

• A company other than the key's own requires group permission (tick it when creating the key in the dashboard), otherwise 403. Every key may name its own company.
• Unknown, ambiguous, deactivated or a company of another group: 422; the request never silently runs in a different company. Header and field at the same time but pointing to different companies: also 422.
• Billing uses the balance of the company group; the rate limit applies per key, an Idempotency-Key per addressed company. The key of a deactivated company responds with 403.
• GET /v1/companies tells you which companies a key may address (free of charge, also with a read-only key): per company id, code, name, country and vat_id; without group permission only its own.
• The VAT ID or tax number in seller must match the addressed company. If it belongs to another company in the group, the API responds with 422 and names that company, instead of silently creating the invoice in the wrong company.

Company management in the web interface

Under Companies owners and team admins create further companies (short code, name, country, legal form; for companies based outside Germany the legal form is a free-text field), deactivate them or reactivate them. Each company has its own master data, number range, customers, catalogue, archive, dunning and mailbox; login, team, plan, credits and AI switch apply to the whole group. With two or more companies you switch the active company in the top bar; the group view shows open receivables per company and currency and provides the full export with one folder per company. In the file import, the column absender (sender) selects the company per invoice; incoming invoices from the mailbox land in the addressed company.

Price: The first company is included. Each additional one costs 390 credits per month from the group's shared balance, charged at the start of the month and when created or reactivated. If the balance is insufficient, the company stays active and all documents remain accessible, but no new invoices can be created from it (422 with a note) until credits are topped up. Deactivated companies cost nothing from the following month.

Activation: We enable additional companies per account. Write to us at office@fhcp.de.

Endpoints

Example input (applies to /v1/cii and /v1/generate):

{
  "invoice": { "number": "2026-0001", "issue_date": "2026-06-29",
                "currency": "EUR", "payment": { "iban": "DE02..." } },
  "seller": { "name": "Ihre GmbH", "street": "Weg 1", "zip": "10115",
               "city": "Berlin", "country": "DE", "vat_id": "DE123456789" },
  "buyer":  { "name": "Kunde AG", "street": "Allee 2", "zip": "80331",
               "city": "München", "country": "DE", "vat_id": "DE987654321",
               "contact_name": "Erika Muster" },
  "lines": [ { "name": "Consulting", "qty": 10, "unit": "Hours",
               "unit_price": 120.00, "vat_rate": 19 } ]
}

?validate=1 additionally validates against KoSIT before delivery. Mandatory fields follow EN 16931 (full address of seller and buyer, VAT ID or tax number, at least one line item).

Idempotency (recommended for retries): POST /v1/generate accepts the header Idempotency-Key: <your ID>. A repeated call with the same key and the same body returns the stored response again (header X-Idempotent-Replay: true) without creating the invoice a second time or deducting credits again. Valid for 24 hours; the same key with a different body → 409.

Custom labels in the Word template: "invoice": {"label_overrides": {"de": {"label_payment_terms": "Zahlungsbedingungen"}, "en": {"label_payment_terms": "Terms of payment"}}} replaces the texts of the ${label_*} placeholders in the language of the document (at most 80 characters; without it, the custom texts stored in your profile apply, otherwise the default). Applies to the Word template only, not to the standard layout or the XML. ${label_item_discount} appears only on lines with a discount; ${item_discount_text} shows the discount with its label and without a sign (“Discount 10.00%”). ${label_item_code} labels ${item_code} (default “Item code”), ${label_order_confirmation} is the short label for ${seller_order_ref} (default “Confirmation”).

Further options for /v1/generate: "seal": true (authenticity seal, see below) and "template": true (rendering with the Word template / corporate design stored in your profile, surcharge as per the price list below). Response headers: X-Credits-Cost (credits used), X-Pay-Url (public “Pay now” page), X-Seal-Verify-Url (with seal), X-Invoice-Template: used (template used) or X-Template-Warning with the reason if the PDF was created in the standard layout. A credit note and a document with a negative amount only run through a template that has the placeholder ${payment_text} (all templates created from 24 Sep 2026), otherwise in the standard layout, and the surcharge is then refunded. Likewise, advance payment invoices need ${service_text}, documents with an amount already paid need ${due_total} and documents with a note need ${advance_note} (see Advance payment). Foreign currency invoices need ${tax_total_tax_currency} (VAT in EUR); there are also ${tax_currency}, ${exchange_rate_text} (rate with source and date) and the block ${fx_block}…${/fx_block}, which is dropped for EUR.

Invoices with an early payment discount need ${skonto_text}, ${payment_terms} or ${payment_text}: without ${skonto_text}, the discount sentence appears on its own line below ${payment_terms}, otherwise before ${payment_text}; without all three, the invoice is created in the standard layout (the discount is a mandatory detail under Section 14 (4) no. 7 UStG). ${item_net} is the line amount after the line discount and charge; ${item_gross} and ${item_discount} are also available.

AI invoice from free text (one call, free text → finished PDF; uses your profile, customer records and catalogue):

curl -X POST "https://sichere-erechnung.de/v1/automap?generate=1" \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"data": "Invoice 2026-0007 to Muster AG, Munich: 10 hrs consulting at 120 EUR, 19% VAT", "seal": true}' \
  -o invoice.pdf

# Without generate: only the recognised JSON is returned (mapped + normalized), for prefilling your own forms:
curl -X POST "https://sichere-erechnung.de/v1/automap" -H "Authorization: Bearer YOUR_API_KEY" \
  -d 'Customer Muster AG, Munich; 10 hrs consulting at 120 EUR each; invoice no. 2026-0007'

If the AI recognises too little for a valid invoice, generate returns no PDF but 422 with the missing fields (then only the AI import rate is charged, not the generate rate).

Further fields & cancellation invoice

You create a cancellation invoice purely via the API: set type_code: "384", set reference_invoice to the original number and enter the line quantities or amounts as negative. Exactly the negated gross amount of one of your own documents counts as a cancellation and closes it in the open items; cancelling a final invoice reverses its deductions (Advance payment):

{
  "invoice": { "number": "STORNO-2026-0001", "issue_date": "2026-07-01",
               "type_code": "384", "reference_invoice": "2026-0001" },
  "seller": { … }, "buyer": { … },
  "lines": [ { "name": "Consulting", "qty": -10, "unit": "HUR",
               "unit_price": 120.00, "vat_rate": 19 } ]
}

Units of measure (BT-130)

Codes according to UN/ECE Recommendation 20 (BR-CL-23). You can send the code or the German word; unknown codes are passed through unchanged.

Authenticity seal & public verification

An authenticity seal cryptographically binds the core fields (issuer, number, date, amount, IBAN) to an Ed25519 signature. Your customer scans the QR code or opens the link and sees immediately: genuine, unchanged, correct IBAN. This protects your customers against forged “invoices from you” with someone else's bank details.

• When creating: /v1/generate with "seal": true → the QR code is embedded directly in the ZUGFeRD PDF, the verify_url comes in the header X-Seal-Verify-Url (+2 credits, customer key, IBAN required).
• Your own PDF: /v1/embed with "seal": true → the seal is created, verify_url in the header; your layout remains unchanged (place the QR code yourself).
• Seal only: /v1/seal (JSON as for /generate or core fields) → returns verify_url and token, without a PDF. With core fields, optionally type_code (document type, e.g. 381 for a credit note): the verification page then names the document type and, for a credit note, shows the IBAN as the customer's refund account; without it, the page refers neutrally to a document.
• Several bank accounts: if the invoice carries an additional bank account (invoice.extra_bank), the seal confirms all IBANs; the verification page lists them under “Confirmed bank accounts” with name and bank country. /v1/seal additionally returns fields.extra_ibans ([{"iban", "label"}], empty without); with core fields, extra_ibans is optional as a list of IBANs or {"iban", "label"}. The existing fields and all older seals remain valid unchanged.
• Verify: GET /verify/{token}, public, no key, no credit. Status: valid, revoked, tampered, notfound.
• Issuer, VAT ID and IBAN are those of your company: /v1/seal takes them from your profile and bank accounts. Missing details are filled in, deviating ones are rejected with 422 (for a credit note or direct debit the IBAN is the customer's account and is not checked). The currency is a three-letter code, e.g. EUR. The embedded white-label form always takes bank account and sender from the profile of the token holder, never from the request.
• White label: The verification page shows the issuer's logo and name (from their profile).
• Revocation: After a cancellation or correction, revoke the seal in the dashboard; the verification page then shows “revoked”.

curl -X POST https://sichere-erechnung.de/v1/generate \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"seal":true,"invoice":{…},"seller":{…},"buyer":{…},"lines":[…]}'

# Response: ZUGFeRD PDF with QR code   ·   Header: X-Seal-Verify-Url: https://sichere-erechnung.de/verify/AbC123…

Integrate into your software

Any language with HTTP will do: accounting software, ERP, online shop or your own tool. Two examples:

$ch = curl_init("https://sichere-erechnung.de/v1/cii");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer $key", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode($invoice),
  CURLOPT_RETURNTRANSFER => true,
]);
$xml = curl_exec($ch); // finished EN 16931 CII XML

import requests
r = requests.post("https://sichere-erechnung.de/v1/generate",
    headers={"Authorization": f"Bearer {key}"},
    json=invoice)
open("invoice.pdf", "wb").write(r.content)

Typical flow in accounting software or an ERP: on “finalise invoice”, send the invoice data to /v1/generate and store or send the returned ZUGFeRD PDF. Check incoming supplier invoices via /v1/validate before booking them.

Billing & limits

• Credits per call: /v1/cii, /v1/generate, /v1/embed, /v1/validate, /v1/extract, /v1/diff, /v1/dunning = 1; /v1/check (incoming invoice check) = 2; /v1/seal (authenticity seal) = 2; /v1/validate/fraud = 3; /v1/automap (AI import) = 10.
• Surcharges for /v1/generate: "template": true (your own Word template) +2, per embedded attachment +1, "seal": true +2.
• Surcharge for /v1/automap: "catalog": true (catalogue already used in the AI recognition instead of only in post-processing) → 30 instead of 10 credits (three times, more tokens per call).
• Free of charge (but key + rate limit): /v1/receivables, /v1/receivables/payment, /v1/receivables/paid, /v1/receivables/refund, /v1/partners, /v1/partners/archive, /v1/companies, /v1/embed/token, GET /v1. Free without a key: /verify/{token} and /health.
• Balance empty → 402 Payment Required (top up credits in the shop).
• Rate limit: 60 requests/minute per key; if exceeded, 429 with Retry-After. Every response carries X-RateLimit-Remaining.
• You only pay for a delivered result: If a call is rejected, whether due to a server error (5xx) or because the data is not EN 16931 compliant (422), we refund the credits used automatically, including any surcharges. Rejections due to insufficient balance, rate limit or a duplicate invoice number cost nothing anyway. Conversely, a validation result of “not compliant” is a result and is charged, since that is what you requested the check for (it comes as 200 with valid: false).

Error codes

Protection & corrections

Incoming invoice check (POST /v1/check, 2 credits): the comprehensive check of a received invoice (PDF or XML) in one call, KoSIT validation + IBAN fraud check (supplier history) + duplicate check. The response is a uniform risk report with risk: green|yellow|red and a list of findings (each with type, level: red|yellow|info|green, message; info is a note without effect on the risk). In addition to KoSIT, IBAN history, block list, IBAN vault, factoring detection, collection account, IBAN country and duplicate, the check detects fraud patterns from your own data, without external queries: payment pressure (pressure, red: new or changed IBAN + due within ≤ 7 days + first invoice from the supplier or first in 90 days), amount plausibility (amount: ≥ 3 times the median of the last 12 months yellow, round thousands from €5,000 info, amounts within 2 % below the usual approval limits €1,000/5,000/10,000/25,000 yellow), duplicate invoice with a new number (duplicate_new_number, yellow: same supplier, amount and IBAN within 30 days, but a different invoice number; a duplicate with the same number is still reported as duplicate; both can occur at the same time and then refer to two different earlier invoices), PDF forensics (consistency, red: visible IBAN, amount, invoice number, due date or issuer contradict the XML; pdf_meta: created with a word processor or online editor info, edited afterwards yellow, creation date > 30 days from the invoice date yellow) and, for invoices received via the mailbox, the sender check (sender: lookalike of a known supplier domain red, new domain yellow, Reply-To ≠ From yellow, SPF/DKIM failure yellow; the first domain per supplier is stored as a reference). Multiple companies: The check knows all companies in your group. If the invoice is addressed to another of your companies, the report contains company: {"status": "sister", "name"} and the finding recipient (yellow, not payable here); then check it with the header X-Company in that company. If the recipient matches several of your companies, the report shows company: {"status": "open", "candidates": [{"name"}]} and the finding empfaenger_firma (yellow); the invoice is not payable until it is assigned. An API key with group permission also receives id and code (short code) for each company. The block list applies to all companies in the group. Accounts without further companies get no company field. Every check is saved in the check history (visible in the web interface under Checked invoices). There you can mark checked invoices for payment and export them as a SEPA bulk transfer (pain.001), which you upload to your online banking (no money flows through us, the recipient IBANs have already been checked). In the IBAN vault you approve or block trusted supplier bank details; a blocked IBAN triggers a red warning on every check. No plain-text IBAN is stored (HMAC hash).

External sources in the incoming invoice check (free of charge, no registration, each as its own findings entry): vies: VAT ID of the issuer against EU VIES (invalid = red; if VIES returns the company name, it is compared with the invoice, mismatch = yellow; Germany returns no name). bank: for German IBANs, the bank code against the Deutsche Bundesbank bank code file (bank code does not exist = red; institution with instant account opening such as N26/Solaris/Revolut = yellow with explanation). sanctions: issuer name against the consolidated EU financial sanctions list (exact match = red, close match = yellow; no matches on names shorter than 5 characters). address: issuer address (DE/AT) via our address service (not found, or postcode and city do not match = yellow). If a source is currently unreachable, you get level: info (“check not possible”); the check never aborts and info does not affect the overall risk. VIES responses are cached for 24 h; the worker keeps the Bundesbank and sanctions lists up to date.

Team & four-eyes approval: Under Team you invite further users to your account (roles Admin/Member; shared balance, shared data and check history). As soon as there are at least two people in the team, the four-eyes principle applies automatically in the IBAN vault: an approval is requested and must be confirmed by a second person. Billing, API keys and account deletion remain reserved for owners and admins.

VAT ID monitoring & alerts: Under VAT ID check we automatically and regularly monitor your customers' stored VAT IDs via EU VIES and notify you by alert (dashboard + email) as soon as a previously valid number becomes invalid, which matters for reverse charge and tax exemption.

Mailbox connection (automatic incoming invoice check): In your profile (mailbox section) you connect an email mailbox via IMAP (read-only access, password encrypted). We fetch incoming invoices from it automatically, check them as above including the email sender (domain history per supplier, lookalike domains, Reply-To, SPF/DKIM from the headers, without network queries) and warn you by alert if anything looks suspicious, without manual uploads.

IBAN fraud protection (POST /v1/validate/fraud, 3 credits): validates a received invoice against KoSIT and compares the issuer's bank details with your supplier history. The response contains fraud_risk: high|low|unknown + a warning message. No plain-text IBAN is stored (HMAC hash). Detects: different IBAN, invalid check digit, IBAN country ≠ company location.

Several IBANs in an incoming invoice (additional credit transfers, BG-17): every additional IBAN is checked like the first against the block list, the IBAN vault, the supplier history and mule accounts. A known additional IBAN is not a finding, a previously unknown one appears as a yellow note (no fraud suspicion), a blocked or invalid one as red. The response lists them under fraud.extra_ibans (iban masked, status, risk, message), the verdict on the first IBAN under fraud.iban_risk. Invoices with one IBAN are assessed as before.

Invoice diff (POST /v1/diff): upload the fields original + corrected (PDF/XML) → structured line diff as JSON or, with ?format=html, as an embeddable Git-style diff view (green = new/more expensive, red/struck through = old/removed), also usable in the white label iframe.

Receivables management: dunning per partner and per invoice

Dunning has three levels, each inheriting from the one above: account (settings under Open items), business partner (“Dunning” card in the partner record, via API the fields dunning_* on POST /v1/partners) and invoice (“Adjust dunning” on the open invoice). Eight fields per level: mode (auto = the service sends reminders, manual = by hand only, off = never, button and API also refuse), tone, dunning texts per level, dunning costs of the first and last dunning letter, €40 flat fee, damages for late payment, level deadlines (days after the due date for the payment reminder, 1st and 2nd dunning letter, default 3/10/21) and payment deadline in the letter (default 10 days). An empty field means “same as the level above”; the interface shows next to each field which level supplies the value. The automatic run respects the levels as well: a partner set to auto receives dunning letters even if the account is set to manual, and vice versa.

Import from Excel, CSV and XML

Three ways, one creation pipeline: under Create from file you upload a file and first see a preview (invoices, line items, totals, errors with sheet and row); only then are the invoices created. POST /v1/import accepts the same files. Supported are Excel (.xlsx, .xls), LibreOffice (.ods), CSV (separator semicolon, comma or tab) and EN 16931 XML (ZUGFeRD/Factur-X CII and XRechnung in both syntaxes, CII and UBL). Excel files are read in an isolated container, formulas arrive calculated, macros are never executed.

Many invoices from one spreadsheet: one row per line item; rows with the same invoice number form one invoice. Header fields (recipient, payment, delivery address) may appear in every row; the first row per invoice counts. The header row may also sit below title rows. Mandatory columns are rechnungsnummer (invoice number), kunde (customer), position (item) and einzelpreis (unit price) or netto (net). The sender always comes from your profile. Download the template with all columns.

A whole Excel invoice: invoices you have written in Excel so far (letterhead, recipient block, item table) are recognised and taken over into the invoice form. If the layout is ambiguous, the interface offers AI mapping (opt-in, costs as for the AI import).

XML: an existing e-invoice (for example from another tool) is read back completely into the invoice schema, including cancellation reference, Leitweg ID, payment terms, early payment discount, delivery address and attachments. Anything that does not fit is reported as a note. UBL becomes CII in the process, which is permitted for XRechnung recipients. Beta Third-party XML (e.g. an ERP export without EN 16931 syntax) is not read deterministically; on request the AI maps the fields (opt-in, costs as for the AI import; check the result in the form).

No-Code & White-Label

Without code: upload a spreadsheet (Excel, LibreOffice or CSV) under Create from file → preview, then a ZIP with all ZUGFeRD PDFs. Ideal for staff without a technical background.

Make / Zapier: call POST /v1/generate per row with the “Webhooks/HTTP” module, no server of your own needed.

White label embedding: for SaaS providers. Your server mints a short-lived token from your API key and embeds the invoice form in your own corporate design via iframe; the end customer creates no account, credits are charged to your quota:

# 1) Create the token on your server (the API key stays secret)
curl -X POST https://sichere-erechnung.de/v1/embed/token \
  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"accent":"#e8590c","title":"Invoice, your brand","ttl":3600}'
# -> { "token": "…", "embed_url": "https://sichere-erechnung.de/embed?token=…" }

# 2) Embed embed_url in an iframe
<iframe src="https://sichere-erechnung.de/embed?token=…" style="width:100%;height:900px;border:0"></iframe>

Theming: accent colour, title and corner radius via the token (accent, title, radius) or cosmetically via URL (?accent=ff8800&radius=4). Your logo comes from your profile.

Recipient contact & catalogue: the embedded form contains an “Attn.” field (BT-56, shown on the invoice) and suggests items from your catalogue via autocomplete (fills unit, net price and VAT), identical to the main interface and under your brand.

Events to the parent window (postMessage): the iframe sends zugferd:resize (height for auto-resize), zugferd:success (PDF created, including filename) and zugferd:error (with errors[]). This is how you connect it:

window.addEventListener('message', function (ev) {
  var d = ev.data || {};
  if (d.type === 'zugferd:resize') iframe.style.height = d.height + 'px';
  if (d.type === 'zugferd:success') console.log('Invoice created:', d.filename);
  if (d.type === 'zugferd:error') console.warn(d.errors);
});

See it live: white label page with embedded demo.

Advance payment, partial and final invoices

Document types: 386 advance payment invoice, 875 construction instalment invoice, 326 partial invoice (completed partial service), 876 construction partial final invoice, 877 construction final invoice. A final invoice is a remainder invoice (German VAT Application Decree, UStAE 14.8(11), and Federal Ministry of Finance (BMF) letter of 15 Oct 2024, paras. 47 and 48): it contains all items of the complete service and, per earlier document and tax rate, one negative line (quantity -1, net price positive). Tax, gross amount and amount due relate only to the remainder. The field invoice.prepaid (BT-113) is not used for this. An invoice 380 with deductions is called “Schlussrechnung” (final invoice) on the document, email, list and dunning letter; in the XML it remains 380.

Final invoice via API

For one of your own advance payment invoices, the number is enough. We add the date, document type, the amount to be deducted and the split per tax rate from your account:

{ "invoice": { "type_code": "380", "number": "SR-2026-001", "issue_date": "2026-09-30",
               "delivery_date": "2026-09-25", "seller_order_ref": "AB-2026-0815",
               "deductions": [ { "number": "AZ-2026-001" } ] },
  "seller": { … }, "buyer": { … },
  "lines": [ { "name": "Conversion of hall 3 as per order AB-2026-0815", "qty": 1, "unit_price": 30000.00, "vat_rate": 19 } ] }

Result for a paid advance payment of 10,710.00 (9,000.00 net): 30,000.00 minus 9,000.00 = 21,000.00 net, 3,990.00 VAT, amount due 24,990.00. An external earlier document (not in your account) needs the net amounts per tax rate; amount alone is only sufficient if the line items have exactly one tax rate (then with a note that net is more precise):

"deductions": [ { "number": "A-77", "issue_date": "2026-03-01", "type_code": "386",
                  "received_date": "2026-03-10", "rates": [ { "vat_rate": 19, "net": 9000.00 } ] } ]

An advance payment invoice states the expected date of the service instead of a date of supply:

{ "invoice": { "type_code": "386", "number": "AZ-2026-001", "issue_date": "2026-07-01",
               "expected_delivery_from": "2026-10", "seller_order_ref": "AB-2026-0815", "order_total_net": 30000.00 },
  "seller": { … }, "buyer": { … },
  "lines": [ { "name": "Advance payment 30 % on order AB-2026-0815", "qty": 1, "unit_price": 9000.00, "vat_rate": 19 } ] }

New fields

What is deducted

• 386 and 875: the amount received, pro rata per tax rate. If the advance payment invoice is unpaid or only partly paid, the final invoice claims the remainder; the advance payment invoice counts as superseded and is no longer dunned.
• 326 and 876: the partial consideration invoiced, including tax, regardless of payment; the partial invoice remains a separate claim.
• Explicit amount for one of your own earlier documents: at most its amount, at least the amount received (386, 875) or the partial consideration invoiced (326, 876), otherwise 422 (§ 14(5) sentence 2 of the German VAT Act, UStG). More than received counts as confirmation: the difference remains open on the advance payment invoice and continues to be dunned; the note states both amounts.
• Same currency and tax scheme; an earlier document can only be in one effective final invoice. A cancelled, paid earlier document only with cancelled_confirmed: true and without a recorded refund (UStAE 14.8(9)).

Notes on the document (BT-22 and PDF)

• Remainder invoice, if a negative line is created: “Remainder invoice: the deducted partial considerations are subtracted net as negative lines. Only the VAT on the remaining consideration is shown.”
• For each of your own advance payment invoices that is not fully deducted: “The advance payment invoice AZ-2 of 1 Aug 2026 has not been paid. Its amount is included in this invoice and is not payable separately.” or “Of the advance payment invoice AZ-2 of 1 Aug 2026, EUR 4,000.00 has been received and deducted. The remainder is included in this invoice and is not payable separately.” If more is confirmed than received: “… EUR 4,000.00 has been received. EUR 8,000.00 has been deducted. The difference of EUR 4,000.00 remains payable on the advance payment invoice AZ-2. …” (The notes are printed on the invoice in German.)
• Advance payment invoice: “Advance payment invoice: this invoice bills an advance payment before the service is performed.”, construction instalment invoice: “Instalment invoice: this invoice bills an instalment payment before acceptance of the construction work.”, plus the expected date. No date of supply (BT-72) and no service period (BG-14); a delivery_date or period_* sent along becomes the expected date, with a note. Advance payment invoices created before this change stay as issued when downloaded again.
• XRechnung: a 386 is written as 380 with the note “Anzahlungsrechnung:” (advance payment invoice; FAQ 4.5 of the German Federal Chamber of Tax Advisers, BStBK; BR-DE-17 is only a warning). 875, 876 and 877 remain. A 384 requires invoice.reference_invoice there (§ 31(5) sentence 2 UStDV, BR-DE-26); the other profiles give a note.

Cancellation and correction

A 384 referencing one of your own documents with exactly its negated gross amount is a full cancellation and closes it; a smaller negative amount is a partial correction, a positive one a supplementary charge. Cancelling a final invoice reverses its deductions, and the advance payment invoices become open again. Cancelling or correcting a deducted advance payment invoice is blocked as long as the final invoice is effective, even if the reference comes as a list. A cancellation takes over invoice.prepaid negated (line “plus reversal of amount already paid” in the PDF) and carries no deductions: Cancellation with an amount already paid (invoice.prepaid, BT-113): this document only refunds the amount due. Refund the amount already paid separately or carry it over to the new invoice.

Notes and headers

• X-Invoice-Hints on PDF and XML responses (/v1/generate, /v1/automap?generate=1, /v1/embed, /v1/cii as XML): notes from the check, separated by “ | ”, at most 2000 bytes, then “und N weitere Hinweise” (and N more notes). JSON responses carry hints (only if there are any).
• With ?validate=1 the warnings and information from the KoSIT validator go into the same channel. Valid means the validator recommends acceptance; /v1/validate, /v1/validate/fraud and /v1/check (under kosit.hints) return the notes separately from the errors. If the check ends without a check report (timeout), the document counts as not checked: “Check not completed: the KoSIT validator did not return a check report (timeout or abort). Please check again.”
• X-Invoice-Stored: 0: the PDF has been delivered, but saving it to your invoice list failed (recorded in the error log). X-Invoice-PayLink: 0: the payment link is missing, the invoice is saved.

Receivables and payments

GET /v1/receivables additionally returns per entry type_code, prepaid_cents, due_cents (amount due), claim_cents (claim after offsetting, null = amount due), open_cents, overpaid_cents, closed_reason (payment, offset offset, superseded superseded, cancelled, covered_by_prepayment, nothing_due) and links.predecessors[] / links.successors[] with {number, type_code, kind, applied_cents} (kind: offset, cancellation, correction, reference). payments[] carry value_date, kind (payment, settlement, refund) and note. Credit notes, cancellation and correction documents are not in the list. paid_cents is the sum of real payments, without capping.

• POST /v1/receivables/payment {number, amount_cents, value_date?, note?}: a date in the future or an amount_cents that is not a whole number returns 422; an overpayment is recorded and stated in overpaid_cents; cancellation and correction documents do not accept payments (409).
• POST /v1/receivables/paid {number, value_date?}: records the open balance as settled; nothing open returns 409.
• POST /v1/receivables/refund {number, amount_cents, value_date?, note?}: refund of an overpayment, up to overpaid_cents at most, otherwise 409.

Incoming invoice check

POST /v1/check reads BT-113, BT-114 and BT-115 and additionally returns prepaid_total and due_payable under invoice (decimal number like grand_total). The finding zahlbetrag (amount due) reports a deducted advance payment (note), a contradiction of more than 1 cent between the amount due and gross minus advance payment plus rounding, a negative BT-113 with a positive gross amount or rounding above 0.99 (yellow, can only be marked for payment with confirmation) and, for MINIMUM, a smaller amount due (note). If the amount due differs from the gross amount and is not in the readable PDF, consistency reports yellow. The SEPA bulk payment transfers the amount due, not the gross amount; an amount due of 0 cannot be marked for payment, nor can an invoice in a foreign currency (an unreadable currency appears as XXX). Documents from before this change without a read amount due are confirmed once in the payment run box.

Import and AI

The import column belegart (document type) accepts “Schlussrechnung”, “Endrechnung”, “Restrechnung” (final/remainder invoice, 380), “Teilschlussrechnung” (876), “Schlussrechnung Bau” (877), “Abschlagsrechnung” (386, with “Bau” 875). New columns: anrechnung (numbers, separated by “;” or “,”), leistung_voraussichtlich and _bis, anzahlung_eingang, weitere_bezuege, bezug_datum, auftragssumme. A deduction only works on invoices that have already been created: import the advance payment invoice and the final invoice in two runs. Several amounts in anzahlung are a row error. The template shows both (advance payment invoice 2026-002, final invoice 2026-003). /v1/import lists row errors and notes per invoice under invoices[i].errors and invoices[i].hints, and additionally fehlerJeRechnung and hinweiseJeRechnung in info; an invoice with a row error is not created. The AI capture (/v1/automap) recognises advance payment, partial and final invoices and “abzüglich Anzahlung AR-…” (less advance payment) as a deduction.

Word template

New placeholders: ${service_label}, ${service_text}, ${prepaid_line}, ${net_before_deductions}, ${deductions_net}, ${advance_note}, ${grand_label}, plus the blocks ${deductions_block}, ${net_block} and ${prepaid_block}. Templates created before this change do not know ${service_text}, ${due_total} or ${advance_note}: advance payment invoices, documents with an amount already paid and documents with a note are then created in the standard layout, the template surcharge is refunded and the reason is given in X-Template-Warning. Remedy: “Regenerate template” in your profile.

Intended changes for existing calls

• invoice.prepaid above the gross amount is an error instead of being silently capped; negative only for a negative gross amount.
• 386 and 875 no longer carry a date of supply; XRechnung with 386 is no longer an error but 380 with a note.
• A negative unit price without a list price is flipped (quantity and price multiplied by -1, same amount), with a note.
• lines[].net: null or "" now calculates like a missing field (quantity times price), previously as a net amount of 0.
• The receivables API records overpayments instead of capping them and no longer lists cancellation and correction documents.
• /v1/cii with Accept: application/json and /v1/import: for a negative invoice amount (cancellation), totals.prepaid is now 0 and totals.due the negative amount; previously the gross amount was shown as already paid and the amount due as 0.
• A second full cancellation of the same invoice returns 422 (“R-100 ist bereits durch ST-102 storniert.”, i.e. R-100 has already been cancelled by ST-102) instead of 200.
• Leading and trailing spaces in invoice.reference_invoice are removed (BT-25). Documents already saved are reproduced as issued when downloaded again.
• The cancellation of one of your own advance payment or construction instalment invoices (386, 875) carries no date of supply (BT-72), and a note is added in X-Invoice-Hints.
• invoice.prepaid as text with a decimal comma ("100,50") returns 422; previously it silently became 100.00.
• Profile minimum with invoice.prepaid or invoice.rounding: DuePayableAmount is the amount due instead of the gross amount. Documents already saved are reproduced as issued when downloaded again.

Example with notes in the header: curl -i -X POST https://sichere-erechnung.de/v1/generate … shows X-Invoice-Hints in the response.