Gutschrift parsen

Eine Gutschrift schickst du an einen eigenen Aufruf. E-Gutschriften (XML, ZUGFeRD, EDIFACT) lesen wir direkt, Scans liest die KI. Die Felder sind dieselben wie bei der Rechnung, plus die Nummer der vorangehenden Rechnung und der Grund. Eine normale Rechnung an dieser Stelle lehnen wir ab, ohne Credits abzubuchen.

So funktioniert der Aufruf

Für Gutschrift gibt es einen eigenen Aufruf mit festem Antwortformat. Du bekommst also immer dieselben Felder zurück und musst nicht raten, was gerade ankommt. Wie du dich anmeldest, was einzelne Fehlermeldungen bedeuten und wie du vorab den Preis erfährst, steht in der API-Dokumentation.

Eingabe-Beleg XRechnung / ZUGFeRD (Code 381) SERVER DE

gutschrift-gs-test-1.xml · Strukturierte Belege: 1 Credit je Datei.

Aussteller
Fixture GmbH · USt-IdNr. DE123456789
Gutschrift
GS-TEST-1 vom 15.03.2024 (Code 381)
Bezug
Zur Rechnung RE-TEST-0 vom 01.02.2024
Position 1
1 Stk. Testposition (Art. A-1) · 100,00 EUR
Erstattung
Netto 100,00 EUR + 19 % USt 19,00 EUR = Brutto 119,00 EUR

Beträge bleiben positiv wie auf dem Beleg; die Referenzrechnung steht in preceding_number.

Antwort-JSON creditnote.v1 HTTP 200 · warnings: []

POST /api/v1/credit-note · source: "xrechnung"

{
    "schema": "creditnote.v1",
    "source": "xrechnung",
    "billed": 1,
    "vendor": {
        "name": "Fixture GmbH",
        "vat_id": "DE123456789"
    },
    "credit_note": {
        "number": "GS-TEST-1",
        "type_code": "381",
        "date": "2024-03-15",
        "preceding_number": "RE-TEST-0",
        "preceding_date": "2024-02-01"
    },
    "totals": {
        "net": 100,
        "vat": 19,
        "gross": 119,
        "due": 119
    },
    "confidence": {
        "overall": 1,
        "totals": 1,
        "lines": 1
    },
    "warnings": []
}

Sofort kostenlos testen (0 Credits mit öffentlichem Test-Key):

curl -sS -X POST https://parser-api.micro-ki.de/api/v1/credit-note -H "Authorization: Bearer pak_test_X0001" -F "file=@gutschrift-gs-test-1.xml"

Welche Dateien du schicken kannst

Du schickst einfach die Datei. Welches Format sie hat, erkennen wir selbst, du musst nichts dazu angeben.

Unterstützte Dateiformate
Was du schickstWas das ist
XML (XRechnung CII/UBL) E-Gutschrift als reine XML-Datei
PDF (ZUGFeRD / Factur-X) PDF zum Anschauen, XML steckt drin
EDI (EANCOM INVOIC) elektronische Gutschrift aus der Warenwirtschaft
PDF / JPG / PNG / WEBP / TIFF / HEIC ohne XML Scan, Foto oder Druck-PDF
DOCX / ODT / TXT Word, LibreOffice, reiner Text
Gutschrift creditnote.v1

So rufst du es auf

# curl 7
curl -sS -X POST \
  -H "Authorization: Bearer pak_test_X0001" \
  -H "Idempotency-Key: lauf-1-0" \
  -F "file=@dokument.pdf" \
  https://parser-api.micro-ki.de/api/v1/credit-note

Beispiel-Antwort

{
    "schema": "creditnote.v1",
    "source": "xrechnung",
    "document": {
        "type": "credit_note",
        "page_count": 0,
        "currency": "EUR"
    },
    "vendor": {
        "name": "Fixture GmbH",
        "payee_name": null,
        "address": "Musterstraße 1, 10115 Berlin, DE",
        "vat_id": "DE123456789",
        "tax_number": null,
        "supplier_number": null,
        "registration_number": null,
        "gln": null,
        "iban": "DE02120300000000202051",
        "account_name": null,
        "bic": null,
        "contact_name": "Erika Muster",
        "contact_department": "Buchhaltung",
        "phone": "+49 30 1234567",
        "email": "rechnung@fixture.example"
    },
    "customer": {
        "name": "Testkunde AG",
        "address": "Beispielweg 5, 20095 Hamburg, DE",
        "vat_id": null,
        "customer_number": "K-1001",
        "registration_number": null,
        "gln": null,
        "contact_name": null,
        "contact_department": null,
        "phone": null,
        "email": null
    },
    "credit_note": {
        "number": "GS-TEST-1",
        "type_code": "381",
        "date": "2024-03-15",
        "due_date": "2024-04-14",
        "preceding_number": "RE-TEST-0",
        "preceding_date": "2024-02-01",
        "reason": "Leistung erbracht im März 2024.",
        "order_number": "PO-4711",
        "contract_number": null,
        "buyer_reference": "04011000-12345-03",
        "accounting_cost": null,
        "delivery_note_number": null,
        "payment_reference": "GS-TEST-1",
        "service_period": "2024-03-01/2024-03-31"
    },
    "delivery": {
        "name": null,
        "address": null,
        "gln": null
    },
    "totals": {
        "line_total": 100,
        "charges": 0,
        "allowances": 0,
        "adjustments": [],
        "net": 100,
        "vat": 19,
        "gross": 119,
        "prepaid": 0,
        "due": 119,
        "vat_rate": 19,
        "vat_breakdown": [
            {
                "rate": 19,
                "category": "S",
                "net": 100,
                "vat": 19,
                "exemption_reason": null
            }
        ]
    },
    "payment": {
        "method": "58",
        "method_text": "SEPA-Überweisung"
    },
    "payment_terms": {
        "text": "Zahlbar innerhalb von 30 Tagen ohne Abzug.",
        "discounts": [
            {
                "percent": 2,
                "days": 10,
                "date": null,
                "base_amount": null
            }
        ]
    },
    "notes": [
        "Leistung erbracht im März 2024."
    ],
    "lines": [
        {
            "seller_item_number": "A-1",
            "buyer_item_number": null,
            "gtin": "4012345001235",
            "description": "Testposition",
            "details": null,
            "quantity": 1,
            "unit": "C62",
            "unit_price": 100,
            "vat_rate": 19,
            "net": 100,
            "gross": null,
            "order_line": null,
            "account": null,
            "service_period": null,
            "note": null
        }
    ],
    "confidence": {
        "overall": 1,
        "vendor": 1,
        "credit_note": 1,
        "totals": 1,
        "lines": 1
    },
    "warnings": [],
    "request_id": "req_beispiel",
    "billed": 0,
    "available": 18,
    "pricing": {
        "rule": "structured",
        "label": "Strukturierte Belege: 1 Credit je Datei."
    }
}

Felder

Felder in creditnote.v1
FeldTypBedeutung
schema const creditnote.v1 Unser Name für dieses JSON, zum Beispiel „creditnote.v1“. Das ist kein amtlicher Formatname.
source string Wie wir die Datei gelesen haben: „zugferd“, „factur-x“, „xrechnung“, „peppol“, „en16931“, „edifact“, „mistral“. „mistral“ heißt, die KI hat sie gelesen (Scan, PDF ohne XML, Word, Text). „en16931“ ist eine andere E-Gutschrift nach EN 16931.
request_id string Diese eine Anfrage, für Logs und Support.
billed integer Credits für diese Anfrage. 0 beim Test-Key und wenn wir in 15 Minuten dieselbe Datei wiedererkennen.
available integer Guthaben nach dieser Anfrage.
pricing object „rule“ und „label“: genau einer der drei Sätze, was ein Credit kostet.
document object Typ, Seiten, Währung.
document.type const credit_note Immer „credit_note“.
document.page_count integer|number|null Seitenzahl bei PDF und TIFF, 1 bei Bild (JPG, PNG, WEBP, HEIC), sonst 0 (XML, EDIFACT, DOCX, ODT, TXT).
document.currency string|null Währung, zum Beispiel EUR.
vendor object Lieferant.
vendor.name string|null Name des Lieferanten.
vendor.payee_name string|null Abweichender Zahlungsempfänger (BG-10, z. B. Factoring oder Zentralregulierer), nur wenn er vom Lieferanten abweicht, sonst null.
vendor.address string|null Adresse des Lieferanten. Eine Zeile, Teile mit Komma getrennt: Straße und Hausnummer, Zusatz, PLZ und Ort, Land als ISO-Code nur, wenn es in der Datei steht.
vendor.vat_id string|null USt-IdNr. des Lieferanten.
vendor.tax_number string|null Steuernummer des Lieferanten.
vendor.supplier_number string|null Lieferantennummer: unter dieser Nummer führt der Kunde den Lieferanten.
vendor.registration_number string|null Registernummer des Lieferanten (Handelsregister, SIRET, KVK), wörtlich wie in der Datei.
vendor.gln string|null GLN des Lieferanten (Global Location Number, 13 Ziffern, von GS1).
vendor.iban string|null IBAN auf der Gutschrift (Bankverbindung des Lieferanten oder Auszahlungskonto), ohne Leerzeichen. Die Prüfziffer wird bei jedem Format geprüft (Hinweis iban_checksum).
vendor.account_name string|null Kontoinhaber neben der IBAN des Lieferanten.
vendor.bic string|null BIC des Lieferanten.
vendor.contact_name string|null Ansprechpartner beim Lieferanten.
vendor.contact_department string|null Abteilung des Ansprechpartners beim Lieferanten (z. B. Einkauf, Buchhaltung).
vendor.phone string|null Telefon des Lieferanten oder des Ansprechpartners, wie in der Datei.
vendor.email string|null E-Mail des Lieferanten oder des Ansprechpartners.
customer object Kunde.
customer.name string|null Name des Kunden.
customer.address string|null Adresse des Kunden. Eine Zeile, Teile mit Komma getrennt: Straße und Hausnummer, Zusatz, PLZ und Ort, Land als ISO-Code nur, wenn es in der Datei steht.
customer.vat_id string|null USt-IdNr. des Kunden.
customer.customer_number string|null Kundennummer beim Lieferanten.
customer.registration_number string|null Registernummer des Kunden (Handelsregister, SIRET, KVK), wörtlich wie in der Datei.
customer.gln string|null GLN des Kunden (Global Location Number, 13 Ziffern, von GS1).
customer.contact_name string|null Ansprechpartner beim Kunden.
customer.contact_department string|null Abteilung des Ansprechpartners beim Kunden (z. B. Einkauf, Buchhaltung).
customer.phone string|null Telefon des Kunden oder des Ansprechpartners, wie in der Datei.
customer.email string|null E-Mail des Kunden oder des Ansprechpartners.
credit_note object Kopf der Gutschrift.
credit_note.number string|null Nummer der Gutschrift.
credit_note.type_code string|null Dokumentart-Code nach UNTDID 1001 bei strukturierten Belegen (z. B. 381 Gutschrift, 261 Selbstfakturierte Gutschrift), sonst null.
credit_note.date string|null Datum der Gutschrift.
credit_note.due_date string|null Datum, bis zu dem der gutgeschriebene Betrag überwiesen wird.
credit_note.preceding_number string|null Nummer der Rechnung, auf die sich die Gutschrift bezieht. Stehen mehrere da, die erste.
credit_note.preceding_date string|null Datum dieser Rechnung.
credit_note.reason string|null Grund der Gutschrift: der erste Hinweistext. Derselbe Text steht auch in notes.
credit_note.order_number string|null Bestellnummer des Kunden, auf die sich die Rechnung bezieht.
credit_note.contract_number string|null Vertrags- oder Rahmenvertragsnummer, auf die sich die Rechnung bezieht.
credit_note.buyer_reference string|null Käuferreferenz, bei öffentlichen Auftraggebern die Leitweg-ID.
credit_note.accounting_cost string|null Buchungskonto oder Kostenstelle des Käufers (BT-19).
credit_note.delivery_note_number string|null Nummer des Lieferscheins, auf den sich die Rechnung bezieht.
credit_note.payment_reference string|null Verwendungszweck, den der Lieferant für die Überweisung vorgibt.
credit_note.service_period string|null Leistungszeitraum als „YYYY-MM-DD/YYYY-MM-DD“ oder ein einzelnes Leistungs- bzw. Lieferdatum als „YYYY-MM-DD“.
totals object Summen der Gutschrift, positiv wie auf dem Beleg.
totals.line_total number|null Summe der Positionen.
totals.charges number|null Zuschläge auf Belegebene, zum Beispiel Fracht.
totals.allowances number|null Abschläge auf Belegebene, zum Beispiel Rabatt.
totals.adjustments[] array Einzelne Zu- und Abschläge auf Belegebene (BG-20, BG-21).
totals.adjustments[].kind string|null „charge“ Zuschlag oder „allowance“ Abschlag.
totals.adjustments[].amount number|null Betrag des Zu- oder Abschlags, positiv.
totals.adjustments[].percent number|null Prozentsatz des Zu- oder Abschlags, wenn angegeben.
totals.adjustments[].reason string|null Grund oder Bezeichnung des Zu- oder Abschlags (z. B. Frachtkosten, Treuerabatt).
totals.adjustments[].reason_code string|null Code des Zu- oder Abschlags nach UNTDID 5189 / 7161 (z. B. FC, 95, DI).
totals.adjustments[].vat_rate number|null MwSt-Satz dieses Zu- oder Abschlags in Prozent.
totals.net number|null Netto: Rechnungssumme ohne Umsatzsteuer (Positionen plus Zuschläge minus Abschläge).
totals.vat number|null Umsatzsteuer gesamt.
totals.gross number|null Brutto der Gutschrift, positiv wie auf dem Beleg, vor Abzug einer Anzahlung.
totals.prepaid number|null Schon erhaltene Anzahlungen.
totals.due number|null Gutzuschreibender Betrag, positiv wie auf dem Beleg.
totals.vat_rate number|null MwSt-Satz, wenn einheitlich.
totals.vat_breakdown[] array Umsatzsteuer je Steuersatz und Kategorie.
totals.vat_breakdown[].rate number|null Steuersatz in Prozent.
totals.vat_breakdown[].category string|null Steuerkategorie: S normal, Z null Prozent, E steuerfrei, AE Reverse Charge, K EU-Lieferung, G Export, O nicht steuerbar.
totals.vat_breakdown[].net number|null Netto zu diesem Satz.
totals.vat_breakdown[].vat number|null Umsatzsteuer zu diesem Satz.
totals.vat_breakdown[].exemption_reason string|null Grund für Steuerbefreiung oder Reverse Charge, als Text oder Code (z. B. VATEX-EU-AE), sonst null.
delivery object Warenempfänger, wenn er vom Kunden abweicht.
delivery.name string|null Name des Warenempfängers.
delivery.address string|null Lieferadresse. Eine Zeile, Teile mit Komma getrennt, wie vendor.address.
delivery.gln string|null GLN des Warenempfängers (13 Ziffern, von GS1).
payment object Wie gezahlt wird.
payment.method string|null Zahlungsart als Code nach UNTDID 4461, zum Beispiel 58 SEPA-Überweisung, 30 Überweisung, 59 SEPA-Lastschrift, 48 Karte.
payment.method_text string|null Zahlungsart als gedruckter Text, wenn die Datei einen nennt.
payment_terms object Zahlungsbedingungen.
payment_terms.text string|null Zahlungsbedingungen als Text, wie in der Rechnung.
payment_terms.discounts[] array Skonto-Stufen, nur aus strukturierten Angaben der Datei oder klar vom Beleg.
payment_terms.discounts[].percent number|null Skonto in Prozent.
payment_terms.discounts[].days integer|null Frist in Tagen ab Rechnungsdatum.
payment_terms.discounts[].date string|null Frist als Datum.
payment_terms.discounts[].base_amount number|null Skontofähiger Betrag, wenn angegeben.
notes[] array Bemerkungen zur ganzen Rechnung.
lines[] array Positionen.
lines[].seller_item_number string|null Artikelnummer des Lieferanten.
lines[].buyer_item_number string|null Artikelnummer des Kunden.
lines[].gtin string|null GTIN, früher EAN (8 bis 14 Ziffern, von GS1).
lines[].description string|null Artikelname der Position.
lines[].details string|null Langbeschreibung der Position, wenn sie neben dem Artikelnamen steht.
lines[].quantity number|null Menge.
lines[].unit string|null Einheit als UN/ECE-Code (Rec. 20), auf allen Wegen gleich: C62 Stück, HUR Stunde, DAY Tag, MON Monat, KGM Kilogramm, LTR Liter, MTR Meter, LS Pauschale (vollständige Liste im Abschnitt „Einheiten“). Unbekannte Einheiten wie gedruckt.
lines[].unit_price number|null Netto-Einzelpreis je Einheit, nach Positionsrabatt.
lines[].vat_rate number|null MwSt-Satz der Position.
lines[].net number|null Netto der Position.
lines[].gross number|null Brutto der Position, nur wenn es auf dem Beleg steht. E-Rechnungen kennen es nicht: null.
lines[].order_line string|null Positionsnummer auf der Bestellung, auf die sich die Zeile bezieht.
lines[].account string|null Buchungskonto oder Kostenstelle des Käufers für diese Position (BT-133).
lines[].service_period string|null Leistungszeitraum dieser Position, gleiches Datumsformat wie invoice.service_period.
lines[].note string|null Bemerkung nur zu dieser Position.
confidence object 0 bis 1 je Feldgruppe. Bei E-Gutschrift und EDIFACT 1 für jede Gruppe, die in der Datei steht, 0 für eine leere Gruppe (z. B. keine Positionen). Liest die KI (Quelle „mistral“), ist es ihre eigene Einschätzung.
confidence.overall number|null 0–1 für die ganze Gutschrift.
confidence.vendor number|null 0–1 für den Lieferanten.
confidence.credit_note number|null 0–1 für den Kopf der Gutschrift.
confidence.totals number|null 0–1 für die Summen.
confidence.lines number|null 0–1 für die Positionen.
warnings[] array Kurze Codes, keine Fließtexte. Welche es bei diesem Endpunkt gibt und was zu tun ist: Abschnitt „Hinweise (warnings)“.

Was du bekommst

Was kostet das

Zum Einstieg kaufst du nur Start für 4,90 € (80 Credits, API-Key inklusive) . Größere Pakete kaufst du später in deinem Konto nach, sie sind pro Credit günstiger. Kein Abo: Deine Credits gelten mindestens drei Jahre, bis zum Ende des dritten Jahres nach dem Kauf.

Endpreise. Gemäß § 19 UStG wird keine Umsatzsteuer berechnet. Angebot nur für Unternehmer (§ 14 BGB), nicht für Verbraucher.

Was du für ein Credit bekommst

  • E-Rechnung & Co.

    SERVER DE

    • XML
    • EDI
    • SWIFT
    • ZUGFeRD

    1 Dokument

    für 1 Credit

    Strukturierte Belege: 1 Credit je Datei.

  • Word & Text

    EU-KI

    • DOCX
    • ODT
    • TXT

    1 Dokument

    für 2 Credit

    Office und Klartext: 2 Credit je Datei.

  • PDF & Scan

    EU-KI

    • PDF
    • JPG
    • PNG
    • WEBP
    • TIFF
    • HEIC

    1 Seite

    für 2 Credit

    PDF-OCR: 2 Credit je Seite.

Die fertigen Vorlagen für n8n und Make bekommst du nach dem Kauf in deinem Konto. Öffentlich zum Download liegen sie nicht.

Weitere Dokumenttypen

So läuft es in n8n So läuft es in Make API-Dokumentation So funktioniert's Hilfe / FAQ