--- title: "EN-16931-Daten aus einer PDF-Rechnung auslesen (Abo oder 1 Credit)" method: POST path: "/extractions" tags: ["Rechnungen"] --- # EN-16931-Daten aus einer PDF-Rechnung auslesen (Abo oder 1 Credit) `POST /extractions` ## Request - Base URL: `https://finisma.de/api/v1` - URL: `https://finisma.de/api/v1/extractions` - Auth: one of: - HTTP bearer - OAuth 2 (authorization code, authorization URL `https://finisma.de/api/oauth/authorize`, token URL `https://finisma.de/api/oauth/token`, scopes: `invoice:verify`, `invoice:create`) Liest eine PDF-Rechnung mit derselben Pipeline aus wie das Web-Formular (Textpfad oder Vision-Modell, Reparaturschleife, deterministische Backfills für IBAN und USt-IdNr.) und liefert die EN-16931-Felder plus offene Probleme. Enthält die PDF bereits eine eingebettete E-Rechnung (ZUGFeRD/Factur-X), kommen die Felder deterministisch aus der XML (source='xml'), ohne Sprachmodell. Gedacht als Vorstufe zu POST /invoices: Felder prüfen, korrigieren, dann erzeugen. Erfordert ein aktives Abo oder 1 Credit je Aufruf; das kostenlose Tageskontingent von /invoices gilt hier NICHT. Rate-Limit 10 Aufrufe pro Minute und Credential. Wichtig: Felder, die das Modell nicht sicher lesen konnte, kommen als Platzhalter zurück ('KORRIGIEREN' für Text, '1900-01-01' für Datum, 0 für Beträge) und stehen in 'repairedPaths'. Diese Werte müssen vor dem Aufruf von /invoices ersetzt werden: Text- und Datums-Platzhalter blockieren dort als EXTRACTION_UNCERTAIN, ein 0-Betrag dagegen kann unbemerkt durchlaufen. ## Response `200` Ausgelesene Rechnungsdaten. - object - `invoice` Invoice, required - `invoiceNumber` string, required - `profile` 'en16931' | 'xrechnung' - `documentTypeCode` string - `precedingInvoiceNumber` string - `precedingInvoiceDate` string - `issueDate` string, required - `dueDate` string - `deliveryDate` string - `deliveryCountryCode` string - `delivery` object - `name` string - `gln` string - `address` object - `line1` string - `line2` string - `postalCode` string - `city` string - `countryCode` string - `currency` string - `buyerReference` string - `costCenter` string - `purchaseOrderReference` string - `contractReference` string - `invoicingPeriod` object - `start` string - `end` string - `projectReference` string - `despatchAdviceRef` string - `receivingAdviceRef` string - `allowanceCharges` object[] - `charge` boolean, required: true = Zuschlag (BG-21), false = Abzug/Nachlass (BG-20). - `amount` number: BT-92/BT-99: Betrag ohne Vorzeichen. Darf fehlen, wenn percent gesetzt ist: dann gilt round2(basisAmount × percent / 100). - `basisAmount` number: BT-93/BT-100: Grundbetrag des Prozentsatzes. Ohne Angabe die Summe der lineNetAmount aller Positionen mit ratePercent (bei gemischten Kategorien desselben Satzes nur die mit categoryCode). - `percent` number: BT-94/BT-101: Prozentsatz, z. B. 2 für 2 % Nachlass. - `categoryCode` string - `ratePercent` number: BT-96/BT-103: Steuersatz in Prozent. Darf beim Prozent-Eintrag ohne basisAmount fehlen, wenn alle Positionen denselben Satz haben. - `reason` string - `reasonCode` string - `seller` object, required - `name` string, required - `vatId` string - `gln` string - `registrationId` string: BT-30 (Verkäufer) / BT-47 (Käufer): Handelsregisternummer bzw. Registerkennung der Partei, z. B. "HRB 12345, Amtsgericht München". Nur angeben, wenn sie auf der Rechnung steht. Beim Käufer reicht sie bei Reverse Charge (Kategorie AE) statt der USt-IdNr., bei innergemeinschaftlicher Lieferung (K) nicht. - `address` object - `line1` string - `line2` string - `city` string - `postalCode` string - `countryCode` string - `contact` object - `name` string - `email` string - `phone` string - `electronicAddress` object - `id` string, required - `scheme` string - `customerAssignedId` string - `buyer` object, required - `name` string, required - `vatId` string - `gln` string - `registrationId` string: BT-30 (Verkäufer) / BT-47 (Käufer): Handelsregisternummer bzw. Registerkennung der Partei, z. B. "HRB 12345, Amtsgericht München". Nur angeben, wenn sie auf der Rechnung steht. Beim Käufer reicht sie bei Reverse Charge (Kategorie AE) statt der USt-IdNr., bei innergemeinschaftlicher Lieferung (K) nicht. - `address` object - `line1` string - `line2` string - `city` string - `postalCode` string - `countryCode` string - `contact` object - `name` string - `email` string - `phone` string - `electronicAddress` object - `id` string, required - `scheme` string - `lines` object[], required - `name` string, required - `quantity` number, required - `unitCode` string - `sellerArticleId` string - `buyerArticleId` string - `globalArticleId` string - `globalArticleScheme` string - `unitPriceNet` number, required - `vatRatePercent` number, required - `categoryCode` string - `allowanceCharges` object[] - `charge` boolean, required: true = Zuschlag (BG-28), false = Abzug/Rabatt (BG-27). - `amount` number: BT-136/BT-141: Betrag ohne Vorzeichen. Darf fehlen, wenn percent gesetzt ist: dann gilt round2(basisAmount × percent / 100). - `basisAmount` number: BT-137/BT-142: Grundbetrag des Prozentsatzes. Ohne Angabe Menge × unitPriceNet der Position (je Eintrag, nicht gestaffelt). - `percent` number: BT-138/BT-143: Prozentsatz, z. B. 10 für 10 % Rabatt. - `reason` string - `reasonCode` string - `lineNetAmount` number, required - `vatBreakdown` object[], required - `ratePercent` number, required - `basisAmount` number, required - `taxAmount` number, required - `categoryCode` string - `exemptionReason` string - `exemptionReasonCode` string - `totalNet` number, required - `totalVat` number, required - `totalGross` number, required - `paidAmount` number - `notes` union[] - union - string - object - `text` string, required - `subjectCode` string - `taxCurrencyCode` string - `totalVatInTaxCurrency` number - `payee` object - `name` string, required - `gln` string - `registrationId` string - `payment` object - `terms` string - `iban` string - `bic` string - `reference` string - `meansCode` string - `mandateId` string - `creditorId` string - `debitedIban` string - `accountName` string - `discountPercent` number - `discountDays` integer - `issues` ValidationIssue[], required: Offene Probleme der ausgelesenen Daten. severity='error' blockiert POST /invoices (dort läuft dieselbe Prüfung erneut), 'warning' nicht. - `code` string, required: Maschinencode, z. B. "BR-CO-26" oder "EXTRACTION_UNCERTAIN". - `path` string: Punkt-Pfad ins Invoice-Objekt, z. B. "seller.vatId". - `message` string, required: Deutsche Fehlermeldung. - `severity` 'error' | 'warning', required - `repairedPaths` string[], required: Punkt-Pfade der Felder, die mit einem Platzhalter gefüllt wurden, z. B. "seller.name" oder "lines.0.lineNetAmount". Vor dem Erzeugen prüfen und ersetzen. - `source` 'xml' | 'llm', required: Herkunft der Felder: 'xml' = deterministisch aus der in der PDF eingebetteten E-Rechnung übernommen, 'llm' = per Sprachmodell aus dem Druckbild extrahiert. ## Other responses - `400`: Ungültige Eingabe. - `401`: Kein oder ungültiges Credential. - `403`: Kein aktives Abo und kein Guthaben. Diese Funktion ist nicht Teil des kostenlosen Tageskontingents. - `429`: Rate-Limit oder kostenloses Tageskontingent erschöpft (siehe Retry-After). - `502`: Fehler im nachgelagerten Dienst. --- [API](https://skmtc.dev/finisma/apis/finisma-rest-api.md) · [All operations](https://skmtc.dev/finisma/apis/finisma-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/finisma/apis/finisma-rest-api/revisions/c1a9acfab69b?raw)