Kontakte, Rechnungen und Buchhaltung schreiben
Scopes, sichere Wiederholungen und Versionsprüfung für schreibende Integrationen.
Schreibzugriff wird je API-Schlüssel ausdrücklich vergeben. Ein bestehender Schlüssel mit read oder upload erhält dadurch keine Schreibrechte. Die Firma und der Inhaber ergeben sich aus dem Schlüssel; eine Firma lässt sich nicht im Anfrageinhalt auswählen.
Wiederholungen ohne Duplikate
Sende bei jedem Schreibaufruf den Header Idempotency-Key mit einer eindeutigen Kennung deiner fachlichen Aktion, zum Beispiel order-4711-create-invoice. Erlaubt sind 1–128 druckbare ASCII-Zeichen ohne Leerzeichen. Bewahre die Kennung zusammen mit dem gesendeten Inhalt auf.
- Wiederhole bei Verbindungsabbruch, Zeitüberschreitung oder einem vorübergehenden Serverfehler exakt denselben Aufruf mit derselben Kennung.
- Für eine neue Aktion verwende eine neue Kennung. Dieselbe Kennung mit anderem Inhalt wird mit
409 IdempotencyConflictabgelehnt. - Die Kennung gilt für den Schlüssel, die Firma und die jeweilige Aktion. Wechsle bei einer Wiederholung nicht den Schlüssel.
- Auch eine Wiederholung prüft die aktuelle Berechtigung. Widerrufene Schlüssel können keine früheren Ergebnisse mehr abrufen.
- Jede Änderung wird mit Name und ID des Schlüssels protokolliert, nie mit dem Schlüssel selbst. Das Änderungsprotokoll im DATEV-Export nennt ihn in der Spalte
via.
Der Datei-Upload behält seinen eigenen Header X-Upload-Request-Id, siehe Beleg-Upload.
Gelesenen Stand beibehalten
Lies das Objekt vor einer Änderung. Kontakte und Rechnungsentwürfe erwarten expectedUpdatedAt mit dem unveränderten updatedAt der Antwort. Speichere den Zeitstempel als Zeichenfolge einschließlich aller Nachkommastellen; eine Umwandlung über eine Datumsfunktion kann Präzision verlieren.
Belegkorrekturen erwarten expectedVersion aus dem gelesenen Beleg. Bei Zuordnungen enthält expectedVersions die Versionen der betroffenen Objekte gemäß Referenz. Verwende diese Werte als undurchsichtige Zeichenfolgen.
Bei 409 VersionConflict hat sich der fachliche Stand geändert. Lies das Objekt neu und prüfe die beabsichtigte Änderung erneut. Ersetze niemals automatisch die Version und sende denselben Änderungswunsch ungeprüft noch einmal.
Kontakte
Mit contacts:write kannst du Kontakte erstellen und gezielt übergebene Felder ändern. Mit contacts:read oder read liest du den aktuellen Stand. externalRef verbindet den Kontakt mit deiner eigenen Kennung; in der App heißt das Feld „Alte Nummer“, etwa für die Kundennummer aus dem früheren Programm, und steht nie auf Belegen.
datevAccounts nennt beim Lesen, Suchen (POST /api/contact/filter), Anlegen und Ändern eines Kontakts sein Debitorenkonto (debitor) und Kreditorenkonto (creditor) im DATEV-Export. bimetrics leitet beide aus der Kundennummer ab, wie die Buchungen, ändern lassen sie sich nur über die Kundennummer. Fehlt die Nummer oder ist sie zu groß für ein eigenes Konto, steht debitorCollective bzw. creditorCollective auf true: Dann bucht bimetrics auf das Sammelkonto 10000 bzw. 70000.
Eine Kundennummer kannst du beim Anlegen mitgeben, wie im Kontaktformular zwischen 1000 und 29999. Ohne Angabe vergibt bimetrics die Nummer nach der höchsten, die die Firma in diesem Bereich je vergeben hat. Die Nummer eines gelöschten Kontakts bleibt belegt, denn deine Kanzlei kennt sein Personenkonto vielleicht schon aus den DATEV-Stammdaten. Erst wenn 29999 vergeben ist, nimmt bimetrics die kleinste Nummer, die nie vergeben war. Ist keine mehr frei, schlägt das Anlegen mit 409 CustomerNumberRangeExhausted fehl. Eine Nummer außerhalb lehnt die API mit 400 InvalidContactWrite ab, context.field ist dann customerNumber. Beim Ändern gelten die Regeln des Kontaktformulars der App, wie über MCP: Bankverbindung (paymentInfo.iban, paymentInfo.bic), steuerliche Kontaktart (customerKind), USt-IdNr., Land, Name und Anschrift lassen sich auch bei Kontakten ändern, die schon in Belegen stehen. Die Kundennummer änderst du nur, solange der Kontakt in keinem Beleg steht, sonst antwortet die API mit 409 CustomerNumberInUse. Beim Anlegen nimmt die API weder Bankverbindung noch Kontaktart an (400 InvalidContactWrite), beides ergänzt du danach per PUT. Die API sendet keine E-Mails an den Kontakt. Prüfe Dublettenhinweise, bevor du erneut anlegst. noReminders: true setzt den Kontakt auf „Nicht mahnen“: Keine Rechnung an ihn lässt sich dann mahnen, auch eine schon ausgestellte; false hebt es auf.
contactInfo.notes ist die interne Notiz zum Kontakt, etwa „Rückruf nur vormittags“. Sie ersetzt die ganze Notiz, eine leere Zeichenfolge leert sie. bimetrics druckt sie nie auf Belege und versendet sie nie. Über MCP lesen und schreiben get_contact, search_contacts, create_contacts und update_contact sie ab MCP-Version 2026-11-17, dort mit höchstens 2000 Zeichen und ohne E-Mail-Adressen, Links oder IBANs.
paymentTerms hält Zahlungsziel (paymentTermDays) und Skonto (cashDiscount mit percent und days) eines Kunden, etwa {"paymentTermDays": 30, "cashDiscount": {"percent": "2", "days": 10}}. Statt der Vorgaben der Firma nehmen sie ein neuer Rechnungsentwurf über MCP, eine aus Angebot oder Auftragsbestätigung umgewandelte Rechnung (App, API und MCP) und ein Rechnungsentwurf über POST /api/draft/, der den Kunden mit buyer.contactId oder buyer.customerNumber nennt und weder dueDate noch cashDiscount mitschickt; was der Kunde offen lässt, kommt von der Firma. Hat er keine eigenen, setzt die API beim Anlegen weiter nichts. Duplikate behalten die Bedingungen des Originals, Serien ihre eigenen. Mitgeschickt ersetzt paymentTerms beide Werte, {} gibt den Kunden an die Vorgaben der Firma zurück, ohne Angabe bleiben sie. Es gelten die Grenzen der Firma: Zahlungsziel 0 bis 365 Tage, Skonto über 0 und unter 100 % mit höchstens zwei Nachkommastellen und 1 bis 365 Tagen, und die Skontofrist darf nicht länger sein als das Zahlungsziel. Sonst antwortet die API mit 400 BadRequest, context.field nennt das Feld, etwa paymentTerms.cashDiscount.days. Ausgestellte Rechnungen und offene Entwürfe behalten ihre Bedingungen. Über MCP liest get_contact sie ab MCP-Version 2026-11-17, create_contacts und update_contact setzen sie.
Kontakte prüfen
Eine neue oder geänderte IBAN prüft bimetrics wie die App: bekanntes Land, genau die Länge dieses Landes und die Prüfziffern. Besteht sie das nicht, etwa wegen eines Zahlendrehers, antwortet die API mit 400 InvalidIban, context.field ist paymentInfo.iban, und nichts wird gespeichert. Eine schon gespeicherte IBAN bleibt, solange du sie nicht änderst, und leeren geht immer.
Eine neue oder geänderte E-Mail-Adresse prüft bimetrics wie den Versand. Würde der Versand sie nicht nehmen, etwa mit einem Punkt direkt vor dem @, antwortet die API mit 400 InvalidContactEmail und context.field contactInfo.email. Gespeichert wird die Adresse so, wie der Versand sie liest, ohne Namen drumherum. Eine schon gespeicherte bleibt. Über MCP gilt die Regel schon heute, in create_contacts und update_contact.
Alles andere sperrt nie. Die Antwort von Anlegen und Ändern nennt in hints Hinweise zum gespeicherten Kontakt, das Feld fehlt ohne Hinweis. Bei der USt-IdNr. eines EU-Staats gibt es vat_id_format, wenn sie nicht die Form dieses Staats hat, und vat_id_check_digit, wenn die Form stimmt, die Prüfziffer aber nicht. params.prefix nennt den Staat mit seinem Länderpräfix, EL für Griechenland, XI für Nordirland. Die Prüfziffer kennt bimetrics für die Staaten, die ihre Regeln veröffentlicht haben, bei den übrigen nur die Form. Ob eine USt-IdNr. aus dem EU-Ausland wirklich vergeben ist, prüft bimetrics wie bisher beim Speichern über VIES.
Bei der ersten Anschrift in Deutschland und Österreich prüft bimetrics die PLZ. postal_code_format heißt, sie hat nicht fünf bzw. vier Ziffern (params.country). postal_code_city heißt, der Ort gehört nicht zur PLZ; params.postalCode nennt sie, params.city den Ort, der dazugehört. Ein Ortsteil wie „Hamburg-Altona“ passt zu Hamburg. postal_code_country heißt, die PLZ gibt es nur im anderen Land, params.country und params.city nennen es, etwa AT und Linz für 4020. Eine PLZ oder einen Ort, die bimetrics nicht kennt, prüft es nicht, denn die Listen sind nicht vollständig und Orte haben viele Schreibweisen. Quellen und Download der Listen: bimetrics.de/datenquellen. email_domain_typo heißt, die Domain der E-Mail ist ein häufiger Tippfehler eines bekannten Mail-Anbieters, etwa gmial.com, oder sein Name hat eine Endung, die es nicht gibt, etwa gmail.con; params.suggestion nennt die Adresse mit dem Anbieter. Weitere Codes können hinzukommen; zeig unbekannte einfach nicht an.
Mit POST /api/contact/check und contacts:read prüfst du iban, vatId, country, postalCode, city und email vorab, ohne etwas zu speichern, etwa während jemand in deinem Formular tippt. ibanValid sagt, ob das Speichern die IBAN annimmt, hints sind dieselben Hinweise wie beim Speichern. Bei einer gültigen deutschen oder österreichischen IBAN nennt bank Name und BIC der Bank aus ihrer Bankleitzahl, nach den Verzeichnissen der Deutschen Bundesbank und der Oesterreichischen Nationalbank (Quelle: Deutsche Bundesbank, Bankleitzahlendatei, gültig vom 07.09.2026 bis 06.12.2026, ab 07.12.2026 die Fassung gültig bis 07.03.2027; Quelle: Oesterreichische Nationalbank (OeNB), SEPA-Zahlungsverkehrs-Verzeichnis, Stand 06.11.2026, CC BY 4.0, Auszug; mehr unter bimetrics.de/datenquellen). Den Namen speichert bimetrics nicht am Kontakt; die BIC übernimmst du bei Bedarf in paymentInfo.bic. Eine USt-IdNr. ohne Länderpräfix ordnet country einem Staat zu. Über MCP kommen dieselben Hinweise ab MCP-Version 2026-11-17 in den Antworten von create_contacts und update_contact; die IBAN-Prüfung gilt dort schon heute.
Mit GET /api/address/postal und contacts:read liest du für Deutschland und Österreich die Orte einer PLZ (?country=DE&postalCode=21255) oder die PLZ eines Orts (?country=DE&city=Tostedt), dieselben Daten wie die Vorschläge im Kontaktformular der App. Hat eine PLZ mehrere Orte, steht der häufigste vorn. Den Ort darfst du schreiben, wie man ihn tippt: „Muenchen“, „St. Augustin“, „Frankfurt a.M.“. Trifft der Name genau einen Ort, stehen seine PLZ auch in postalCodes. Trifft er mehrere, etwa „Frankfurt“, stehen sie mit ihren PLZ in places, und postalCodes bleibt leer. Mit street (?country=DE&city=Hamburg&street=Mönckebergstraße 7) nennt streetPostalCodes die PLZ der Straße in einem deutschen Ort mit mehreren PLZ. Gibt es die PLZ nur im anderen der beiden Länder, nennt elsewhere dieses Land. Für andere Länder kommt supported: false. Die Daten stammen für Deutschland aus OpenStreetMap (ODbL 1.0), für Österreich von der RTR-GmbH. Zeigst du Vorschläge an, nenne attribution, bei source: "osm" mit Link auf https://www.openstreetmap.org/copyright. Über MCP gibt es beides ab MCP-Version 2026-11-17 als lookup_address: die Orte einer PLZ, die PLZ eines Orts, die PLZ einer Straße im Ort und Straßenvorschläge zu einem getippten Anfang.
Mit GET /api/address/streets und contacts:read bekommst du für Deutschland Straßenvorschläge zu einem getippten Anfang, ab drei Buchstaben (?country=DE&q=Mönckeb&city=Hamburg), mit Ort und Postleitzahlen, höchstens 8. Es sind dieselben Vorschläge wie im Feld „Straße und Hausnummer“ des Kontaktformulars. Mit city grenzt du auf einen Ort ein, mit postalCode auf Straßen mit dieser PLZ. Ohne Ort kommen Straßen in größeren Orten zuerst. Gibst du ohne Ort near mit, eine Postleitzahl wie die deiner Firma, stehen die Straßen aus deren Nähe vorn (?country=DE&q=Friedrichstr&near=80331 liefert zuerst München, dann Erding und Hallbergmoos). Die Daten stammen aus OpenStreetMap (© OpenStreetMap-Mitwirkende, ODbL 1.0). Hausnummern kennt die Liste nicht, und nicht jede Straße steht darin. Fragst du bei jedem Tastendruck ab, warte nach dem letzten Buchstaben etwa 250 ms, so macht es auch das Kontaktformular. Auch hier gelten die Limits, je Schlüssel 60 Anfragen pro Minute.
Ausgangsrechnungen
- Lege mit
invoices:drafteinen EUR-Rechnungsentwurf mit einer bestehenden Kontakt-ID an.externalRefkann die Bestellnummer deiner Anwendung enthalten. Mitbuyer.contactIdübernimmt der Server bei jedem Speichern Name und erste Anschrift des Kontakts. Zum Abschließen brauchen der Kontakt (Name, Straße, PLZ, Ort, Land) und die Firma (Straße, PLZ, Ort, Land) eine vollständige Anschrift, sonst antwortet die API mit422 InvoiceAddressRequired. Fehlt eine Anschrift, ergänze sie am Kontakt, perPUToder in der App, und speichere den Entwurf danach erneut perPUT. - Ergänze und prüfe den gespeicherten Entwurf. Beim Ändern wird der vollständige Entwurfsinhalt gesendet, zusammen mit
expectedUpdatedAt. Dazu gehören der PflichthinweistaxHintText(nullfür den Standardtext), die Lieferungdeliveryund eine SteuerausnahmetaxException, beiexempt_4mit einemshortcutausGET /api/tax-case/exempt-reasonsalsreason. Die BestätigungacceptStandardVatWithoutVatIdgilt nur für den gespeicherten Käufer.acceptUnverifiedVatIdsetzt die API nicht: Eine von VIES abgelehnte USt-IdNr. korrigierst du am Kontakt; eine gespeicherte Bestätigung darfst du unverändert zurückschicken. Bringt einPUTeinen Käufer mit anderem Namen, anderer USt-IdNr. oder anderem Land, etwa über einen anderen Kontakt oder eine in der App geänderte USt-IdNr., setzt der Server beide Bestätigungen auffalse. Für den neuen Käufer setzt duacceptStandardVatWithoutVatIdmit einem zweitenPUTneu;acceptUnverifiedVatIdlässt sich danach nicht mehr setzen. - Prüfe den Steuerfall. Die Prüfung meldet auch einen Entwurf ohne Position (
ItemsRequired), einen fehlenden Firmennamen und unvollständige Anschriften als blockierend. Eine erfolgreiche Vorprüfung ersetzt nicht die abschließende Prüfung der erzeugten E-Rechnung. - Mit dem gesonderten Scope
invoices:finalizeschließt du den gespeicherten Stand ab. Im Anfrageinhalt stehtexpectedUpdatedAt; bei Rechnungskorrekturen kann zusätzlichexpectedCapacityRevisionden geprüften Korrekturumfang binden. Bearbeitbare Rechnungsfelder werden beim Abschließen nicht angenommen. Der Server vergibt die Rechnungsnummer und erzeugt PDF, XML und Buchungsdaten. Es wird keine Nachricht versendet. Angebote und Auftragsbestätigungen schließt der Server wie der Editor nur ab, wenn der Leistungszeitraum nicht vor seinem Beginn endet und weder Skonto noch eine Steuerausnahme (taxException) eingetragen ist. Sonst antwortet die API mit400,context.fieldnennt das Feld. Ohne Position stellt der Server keinen Beleg aus und antwortet mit400,context.fieldistitems. Liegt das Rechnungsdatum vor deiner letzten Rechnung, meldet schon die Prüfung aus Schritt 3 den HinweisIssueDateBeforeLastInvoice, und die Antwort nennt ihn inwarnings. Das ist erlaubt, fällt aber bei einer Betriebsprüfung auf.
Angebote legst du genauso an, mit invoiceKind: "SalesProposal" und ohne typeCode. Ausgestellt wird ein Angebot ebenfalls mit invoices:finalize: Es bekommt eine Nummer aus dem Nummernkreis der Angebote und ein PDF, aber weder XML noch Buchungen, und steht in der Antwort unter salesProposal. Mit POST /api/draft/{id}/derive entsteht daraus eine Auftragsbestätigung oder die Rechnung.
Ein Angebot kann Positionen enthalten, die nicht fest beauftragt sind. option je Position in items ist optional, demand (Bedarfs- oder Eventualposition) oder alternative (Alternative zur nächsten festen Position darüber). Solche Positionen stehen mit dem Betrag in Klammern im PDF, zählen in keine Summe und stehen in keiner XML. Andere Belege lehnen option mit 400 ab. Bei POST /api/draft/{id}/derive nennt selectedLines die beauftragten Positionen als Index in items der Quelle, ab 0. Sie werden normale Positionen, eine gewählte Alternative ersetzt ihre feste Position. Ohne selectedLines kommen nur die festen Positionen mit.
Eine Rechnung oder ein Angebot duplizierst du mit POST /api/draft/{id}/copy und invoices:draft, wie „Duplizieren“ in der App, ohne Anfrageinhalt und mit Header Idempotency-Key. Der neue Entwurf übernimmt Käufer, Positionen und Texte und trägt das heutige Datum. Eine Rechnung behält die Zahlungsfrist des Originals in Tagen; ohne Fälligkeit im Original gilt das Zahlungsziel der Firma, ohne Zahlungsziel 14 Tage. Ihr Leistungszeitraum beginnt heute, ein Ende vor heute entfällt. Skonto bleibt nur, wenn es zur neuen Fälligkeit passt. Ein Angebot gilt so viele Tage wie das Original, ab heute gezählt. Das alte Lieferdatum entfällt. Auftragsbestätigungen, Stornorechnungen und Rechnungskorrekturen lassen sich nicht duplizieren (400).
title und subtitle gliedern Angebot, Auftragsbestätigung und Rechnung, je höchstens 200 Zeichen, ein Untertitel braucht einen Titel. Aufeinanderfolgende Positionen mit demselben Titel bilden im PDF einen Abschnitt mit Überschrift und Zwischensumme, in der XML bleibt die Liste flach. Die Zwischensumme zählt nur feste Positionen, auf Brutto-Belegen brutto, sonst netto nach Rabatt. Die Überschrift nimmt ihre Nummer vom Anfang der position ihrer ersten Zeile: 2.1 ergibt den Titel 2, 2.3.1 den Titel 2 und den Untertitel 2.3. Eine position ohne diese Teile, etwa 7, druckt die Überschrift ohne Nummer. Rechnungskorrekturen zeigen keine Titel, Stornos schon.
Leistungen verrechnest du mit einer negativen Menge und einem Einzelpreis ohne Minuszeichen: quantity: "-1" und unitPrice: "1250" ziehen 1.250 € gemäß priceType ab. App, API und die vorhandenen MCP-Werkzeuge für Rechnungsentwürfe unterstützen diese Eingabe; eine Menge von 0 ist im Editor und über MCP gesperrt. Umsatzsteuer und Gesamtsumme berücksichtigen den Abzug mit dem Steuersatz der Position.
Offene Entwürfe von Rechnungen, Stornorechnungen, Angeboten und Auftragsbestätigungen löschst du mit DELETE /api/draft/{id} und invoices:draft, wie „Löschen“ in der App. Im Anfrageinhalt steht das gelesene expectedUpdatedAt. Eine Nummer wird dabei nicht verbraucht. Ausgestellte Belege bleiben geschützt (409 DraftFinalized), sie werden korrigiert oder storniert. Entwürfe von Rechnungskorrekturen löscht nur die App.
Die API erzeugt Rechnungen in EUR, standardmäßig als ZUGFeRD im Profil EN 16931. Mit einvoiceProfile: XRECHNUNG entsteht eine XRechnung 3.0 (CII) für Behörden und Kunden, die eine XRechnung verlangen. Sie braucht eine Käuferreferenz (buyerReference, bei Behörden die Leitweg-ID); ohne Angabe übernimmt bimetrics bei buyer.contactId die Leitweg-ID des Kontakts. Fehlt eine Pflichtangabe, etwa die Telefonnummer deiner Firma, meldet die Prüfung des Entwurfs sie als blockierend, und das Abschließen antwortet mit 422 XRechnungDataRequired; context.field nennt die Angabe. Die XML lädst du nach dem Abschließen mit GET /api/draft/{id}/einvoice-xml herunter. Das Profil EXTENDED gibt es nur in der App.
Jede festgeschriebene Rechnung wird einmal als verarbeitetes Dokument erfasst und zählt zum Kontingent, wenn der Vertrag das vorsieht (invoicesCounted); Stornos und Korrekturen zählen nie. Ist das Kontingent danach ausgeschöpft, enthält die Antwort quotaNotice, die Rechnung ist trotzdem ausgestellt. Nur Verträge, die das vorsehen, lehnen weitere Rechnungen ab 110 % mit 402 InvoiceQuotaExceeded ab; der Entwurf bleibt erhalten. Stornos blockiert das Kontingent nie. Festgeschriebene Rechnungen werden nicht überschrieben. Der Storno-Endpunkt erzeugt einen Vollstorno vom Typ 384 aus dem Original; er nimmt keine frei formulierte Gutschrift entgegen. Als Referenz trägt der Storno die Nummer der Originalrechnung. Sein Datum liegt nie vor dem der Originalrechnung, sonst lehnt das Abschließen mit 400 und context.field: issueDate ab. Skonto und QR-Code entfallen; eine Fälligkeit hat der Storno nur, wenn er einen Betrag fordert.
Abschlags- und Schlussrechnung
Abschläge sind für Werk- und Bauaufträge, die noch nicht fertig sind, auch wenn schon ein Teil erledigt ist. Schon gelieferte Ware mit eigenem Preis und Leistungen mit Monatspreis wie Miete oder Wartung sind keine Abschläge, sie gehen als normale oder wiederkehrende Rechnung. Ist der ganze Auftrag fertig, rechnet die Schlussrechnung ihn ab und zieht die bezahlten Abschläge ab. Beides geht für Kunden in Deutschland mit 19 % und 7 %, mit § 13b UStG (Steuerregelung „§ 13b UStG“ in taxRateReason des Angebots; über eine Auftragsbestätigung trägt nur diese Steuerregelung, eine taxException des Angebots übernimmt sie nicht) und als Kleinunternehmer; sonst antwortet die API mit 422 DownPaymentTaxCaseUnsupported. Ist der Auftrag dann fertig, leite eine Rechnung über den ganzen Auftrag ohne invoiceRole ab.
-
Abschlag ableiten.
POST /api/draft/{id}/derivemitinvoices:draftaus einem ausgestellten Angebot oder einer ausgestellten Auftragsbestätigung, mittargetKind: "invoice",invoiceRole: "down_payment"und genau einem vonpercent(Zeichenfolge, z. B."30") oderamountMinor(Cent in der Preisart des Auftrags). Basis sind die festen Positionen ohne Auslagen, bimetrics schreibt je Steuersatz eine Position.expectedPerformancenennt, wann der ganze Auftrag voraussichtlich fertig ist, am Bau die Abnahme. Weißt du es noch nicht, lass es weg; aus einer Auftragsbestätigung übernimmt bimetrics ihren Leistungszeitraum, außer er ist vorbei. Ein Auftrag nimmt beliebig viele Abschläge.{"targetKind": "invoice", "expectedUpdatedAt": "2026-11-02T09:15:00.123456Z", "invoiceRole": "down_payment", "percent": "30", "expectedPerformance": {"from": {"year": 2027, "month": 3, "day": 1}, "to": {"year": 2027, "month": 3, "day": 31}}} -
Höhe ändern.
PUT /api/draft/{id}mitdownPaymentim Entwurf, etwa{"percent": "40"}oder{"amountMinor": 300000}. bimetrics baut dann Positionen und Preisart aus dem Auftrag neu, gesendeteitemszählen nicht. Das gilt auch, wenn du das gelesenedownPaymentunverändert zurückschickst. Willst du die Positionen selbst bestimmen, lassdownPaymentweg, dann geltenitemswie gesendet. Ein Abschlag hat keinen Leistungszeitraum, kein Lieferdatum und kein Skonto. -
Schlussrechnung ableiten. Wie den Abschlag, mit
invoiceRole: "final"und ohne Höhe. Sie übernimmt die Positionen des Auftrags; Mehr- oder Minderleistung trägst du als eigene Position ein. „Fertig am“ istperformancePeriodFrom, ein Tag, nicht nach dem Rechnungsdatum.performancePeriodTounddelivery.datebleiben leer oder nennen denselben Tag. Ohne Datum meldet die Prüfungfinal_performance_date_missingund sperrt das Ausstellen. -
Prüfen.
POST /api/draft/{id}/tax-casenennt bei der Schlussrechnung insettlement, was das Ausstellen mit den Abschlägen macht:deductionssind die Abzugszeilen je bezahltem Abschlag und Steuersatz,cancelleddie unbezahlten Abschläge, die bimetrics storniert,correcteddie teilbezahlten, die es auf den bezahlten Betrag korrigiert.acceptRequiredsagt, ob dafür eine Zustimmung nötig ist,revisionden geprüften Stand,dueMinorden Betrag „Noch zu zahlen“ nach den Abzügen. Bei Abschlag und Schlussrechnung zeigtbillingden Stand des Auftrags. -
Ausstellen.
PUT /api/draft/{id}/finalizemitinvoices:finalize,expectedUpdatedAtundexpectedSettlementRevision, beiacceptRequiredzusätzlich mitacceptCancelOpenDownPayments: true. Hat sich seit der Prüfung ein Zahlstand geändert, stellt bimetrics nichts aus und antwortet mit409 FinalInvoicePaymentsChanged. Schlussrechnung, Stornos und Korrekturen entstehen in einem Schritt mit fortlaufenden Nummern und dem Datum der Schlussrechnung. Die Schlussrechnung bekommt die nächste freie Nummer, Stornos und Korrekturen die folgenden; Stornos und Korrekturen tragensettledByFinalDraftId. Die Mail der Schlussrechnung hängt sie an, eine XRechnung geht allein: Stornos und Korrekturen sendest du dann einzeln.{"expectedUpdatedAt": "2026-11-09T10:20:30.123456Z", "expectedSettlementRevision": "<revision aus settlement>", "acceptCancelOpenDownPayments": true} -
Lesen.
GET /api/draft/{id}eines ausgestellten Angebots oder einer ausgestellten Auftragsbestätigung liefertbilling: Abschläge mitordinal, Zahlstand undcancelledByoderdeductedBy, die abschließende Rechnung und die Summen. InPOST /api/draft/filtertragen Angebote und AuftragsbestätigungenbillingSummary, AbschlägedownPaymentOrdinalunddeductedBy.invoiceRolelässt sich filtern. In den Buchungen heißt die Zahlung auf einen Abschlagdown_payment, ihre Auflösung in der Schlussrechnungdown_payment_clearing.
Sperren, alle unter Fehler:
409 FinalInvoiceExists: Der Auftrag hat schon eine Schlussrechnung oder eine Rechnung über den ganzen Auftrag, auch als Entwurf. Nach ihrem Storno geht wieder eine.409 DownPaymentsExist: Mit Abschlägen geht keine Rechnung über den ganzen Auftrag mehr, nur die Schlussrechnung.409 DownPaymentDraftsOpen,409 DownPaymentPaymentUnknown,409 DownPaymentOverpaid: Ein Abschlag ist noch Entwurf, sein Zahlstand ist unklar, oder er ist überzahlt.422 FinalInvoiceNegative,422 FinalInvoiceCashDiscount: Die Abzüge übersteigen die Leistung, oder nach ihnen geht kein Skonto.409 DownPaymentInFinalInvoice,409 DownPaymentCorrectionExceedsOpen,409 InvoiceRoleNotDuplicable: Ein abgezogener Abschlag ist gesperrt, ein bezahlter lässt sich nicht korrigieren, Abschlag und Schlussrechnung lassen sich nicht duplizieren.422 DownPaymentTaxStatusChanged,422 DownPaymentSmallBusinessCashBasis,422 DownPaymentBuyerChanged,422 DownPaymentReverseChargeChanged: Versteuerung, Kunde oder § 13b UStG haben sich seit den Abschlägen geändert.
Über MCP gehen Abschlag und Schlussrechnung seit MCP-Version 2026-11-17 mit derive_sales_document und invoiceRole, unter § 13b UStG ab Version 2026-11-22.
Sicherheitseinbehalt
Behält der Kunde einen Teil bis zum Ende der Gewährleistung ein, trägt die Rechnung den Einbehalt, und Mahnungen fordern nur, was jetzt fällig ist. Das geht an jeder Rechnung, auch an Abschlags- und Schlussrechnung.
- Setzen.
PUT /api/draft/{id}mitretentionim Entwurf, etwa{"percent": "5", "dueOn": "2030-10-30"}oder{"amountMinor": 59500, "dueOn": "2030-10-30"}. Die Prozent rechnen vom Gesamtbetrag, bei der Schlussrechnung von der ganzen Leistung vor Abzug der Abschläge, kaufmännisch auf den Cent gerundet. Am Abschlag lässt dudueOnweg: Sein Einbehalt wird mit der Schlussrechnung fällig.offerGuarantee: truedruckt den Satz, dass eine Bürgschaft den Einbehalt ablösen kann. - Prüfen.
POST /api/draft/{id}/tax-casenennt Probleme mit Codesretention_…, etwaretention_due_on_missingoderretention_exceeds_payable. Beim Ausstellen antwortet bimetrics darauf mit422 RetentionInvalid,context.problemnennt den Code. - Ausstellen. Rechnungsbetrag, Umsatzsteuer und der fällige Betrag der E-Rechnung (BT-115) bleiben. Die Zahlungsbedingungen (BT-20) nennen den jetzt fälligen Betrag und den Einbehalt mit seinem Tag, das PDF zeigt beides zusätzlich unter den Summen („Jetzt zu zahlen bis …“). Höhe und Tag stehen ab dann fest; früher fällig wird er nur mit Schritt 5. Mit Skonto (
cashDiscount) rechnet das Skonto vom jetzt fälligen Betrag, der Einbehalt bekommt keins. Die Zahlungsbedingungen nennen beides in einem Text, die XRechnung die Basis alsBASISBETRAGin der Zeile#SKONTO#, ZUGFeRD Extended inBasisAmount. ImcashDiscountdes Belegs istbasisAmountdann der jetzt fällige Teil undretainedAmountder Einbehalt. - Lesen.
GET /api/receivable/{id}undpaymentinPOST /api/draft/filtertragenretentionmitamountMinor,dueOnundheldMinor, dem Teil des offenen Betrags, der heute noch nicht fällig ist. Ist nur noch er offen, istpayment.detailretention, und bis zu seinem Tag stehtretention_not_dueinreminderBlockReason. Am Tag danach ist die Rechnung überfällig, undGET /api/home/tasksnennt die Zeileretention_due. - Früher fällig stellen.
POST /api/receivable/{id}/retention-releasemitexpectedReceivableVersionund optionalemreasonstellt den Einbehalt ab heute fällig, etwa gegen eine Bürgschaft. Die Rechnung bleibt, wie sie ist.
Über MCP zeigt die PDF-Vorschau den Einbehalt, die Prüfung meldet seine Probleme; setzen und fällig stellen geht dort ab MCP-Version 2026-11-17.
Zahlungen zuordnen und erfassen
matching:write erlaubt, bestehende Belege und Bankumsätze zuzuordnen oder zulässige Zuordnungen wieder zu lösen. Beim Zuordnen mit POST /api/match/ ist expectedVersions optional. Wenn du es mitschickst, nenne darin jeden gewählten Beleg mit seiner version aus GET /api/document/{id}. Bankumsätze und Buchungsvorlagen haben keine lesbare Version und gehören nicht hinein. Hat sich ein Beleg seit dem Lesen geändert, antwortet die API mit 409 VersionConflict. Ist ein Beleg oder Umsatz schon zugeordnet, kommt 409 MatchConflict. Ob bimetrics die neue Zuordnung fehlerfrei buchen kann, siehst du in bookingErrors, wenn du den Beleg danach erneut liest, siehe Buchungsfehler am Beleg. Vor dem Lösen liefert GET /api/match/:id/delete-preview die vollständige expectedVersions-Map und die IDs dabei gelöschter Serienbelege. Prüfe die Belege und sende die Map im DELETE-Body unverändert. Systemzuordnungen für Stornos lassen sich nicht lösen. Sind Buchungen der Zuordnung schon an DATEV exportiert, nennt die Vorschau ihre Monate in exportedMonths, etwa ["2026-01", "2026-03"]. DELETE löst die Zuordnung dann nur mit confirmExported: true, sonst kommt 409 FinalizedBookingsLocked. Zeig dem Nutzer die Monate und frag ihn vorher. bimetrics bucht dasselbe wie „Zuordnung lösen“ in der App: Storno und Neubuchung nur dort, wo sich etwas ändert, also höchstens in diesen Monaten. Beides geht mit dem nächsten Export der noch nicht exportierten Buchungen als Nachtrag an DATEV. Danach ordnest du Beleg und Umsatz mit POST /api/match/ neu zu. Die Route lehnt Belege und Umsätze mit exportierten Buchungen zunächst mit 409 FinalizedBookingsLocked ab und nennt die Monate in context.exportedMonths. Zeig sie dem Nutzer und sende die Anfrage nach seiner Bestätigung noch einmal mit confirmExported: true; dann bucht bimetrics wie beim Zuordnen in der App. Festgeschriebene Buchungen, ob exportiert oder nicht, bleiben stehen, solange DATEV für sie dieselbe Zeile bekäme. Ändert sich die Zeile, etwa weil ein Umsatz ein anderes Konto bekommt oder weil bei einer Sammelzahlung das Belegfeld wechselt, storniert bimetrics die Buchung in ihrem ursprünglichen Monat und bucht sie neu, wie in der App. Das gilt beim Lösen ebenso wie beim Zuordnen und Erweitern. Ändern sich dabei Datum, Konto, Steuerkennzeichen oder Betrag, nennt die Antwort den Monat in reversedFinalizedMonths, etwa ["2026-03"]. Ist die Umsatzsteuer-Voranmeldung für einen dieser Monate schon abgegeben, muss sie womöglich berichtigt werden. Ein Storno, der nur Buchungstext oder Belegfeld ändert, steht nicht in reversedFinalizedMonths, denn an der Voranmeldung ändert er nichts. Aus Zuordnungen über die REST-API lernt bimetrics keine Regel. Ob es aus Zuordnungen in der App und über MCP lernt, liest und schaltet die Firma mit GET /api/settings/matching und PUT /api/settings/matching (learnRules, Recht company:write), wie „Aus Zuordnungen lernen“ in Einstellungen › Buchhaltung. Die Schlüssel für category liefert GET /api/category/, die IDs der Buchungsvorlagen für documentSeriesIds POST /api/document/collection/series/filter.
Kommt eine weitere Teilzahlung oder ein weiterer Beleg dazu, erweiterst du die Zuordnung mit POST /api/match/{id}/extend, wie „Zuordnung erweitern“ in der App. Sende alle bisherigen und die neuen IDs, dazu expectedVersions aus delete-preview. bimetrics ersetzt die Zuordnung in einem Schritt durch eine neue mit derselben Kategorie und bucht neu, replacedMatchId nennt die alte. Nicht möglich ist das mit bestätigtem Skonto (400 CashDiscountNotEligible), außer um die spätere Zahlung eines Sicherheitseinbehalts (cashDiscount.retainedAmount), höchstens in seiner Höhe und ohne weiteres Skonto. Ebenso wenig geht es mit gebuchten Mahnkosten (422 ReminderChargesNotEligible), mit einem Beleg aus einer Buchungsvorlage (409 MatchNotExtendable) und bei Buchungen, die schon an DATEV exportiert sind (409 FinalizedBookingsLocked).
Ist die Differenz einer Zuordnung Skonto, gleichst du sie mit POST /api/match/{id}/cash-discount aus, wie „als Skonto ausgleichen“ in der App, ohne die Zuordnung vorher aufzuheben. GET /api/match/{id}/cash-discount-preview sagt vorher, ob das geht, und liefert Belegnummer, Verwendungszweck, Beträge, Prozent und expectedVersions. Eine Differenz allein beweist kein Skonto: Frag den Nutzer, ob wirklich Skonto vereinbart war, und nenne ihm reference.otherNumbers, wenn der Verwendungszweck eine andere Nummer trägt. Es gilt dieselbe Prüfung wie beim ersten Zuordnen mit confirmCashDiscount. bimetrics ersetzt die Zuordnung in einem Schritt durch eine neue über denselben Beleg und Umsatz, replacedMatchId nennt die alte. Der offene Betrag ist danach null, Belegbetrag und Steuerangaben bleiben. Eine Wiederholung mit gleichem Schlüssel bucht nichts erneut. Nicht möglich ist das, wenn die Zuordnung nicht passt oder schon ein Skonto ausgeglichen hat (400 CashDiscountNotEligible) und bei Buchungen, die schon an DATEV exportiert sind (409 FinalizedBookingsLocked). Andere festgeschriebene Buchungen bleiben stehen; storniert und neu gebucht werden sie nur, wenn sich für DATEV etwas ändert. reversedFinalizedMonths nennt den Monat der Zahlung, wenn dort festgeschriebene Buchungen liegen, denn für ihn kann eine schon abgegebene Umsatzsteuer-Voranmeldung eine Berichtigung brauchen. Eine aus der alten Zuordnung gelernte Regel schaltet bimetrics ab.
Ist der Beleg einer Zuordnung in einer Fremdwährung (documentCurrency) und fehlt sein Euro-Betrag noch (euroAmountSource fehlt, in der App „Euro-Betrag fehlt“), übernimmst du den Euro-Betrag der Zahlungen mit POST /api/match/{id}/euro-amount, wie „Euro-Betrag übernehmen“ in der App. GET /api/match/{id}/euro-amount-preview sagt vorher, ob das geht, und liefert Betrag laut Beleg, Euro-Betrag, jede Position vorher und nachher und expectedVersions. Nötig sind genau ein Beleg und mindestens ein gebuchter Euro-Umsatz, ohne Skonto und ohne erfasste Zahlungen. Frag den Nutzer, ob die Zahlungen den ganzen Beleg decken: Eine Teilzahlung würde den ganzen Beleg zu niedrig buchen. Einen anderen Euro-Betrag trägst du mit euroTotalAmount in PATCH /api/document/:id ein. bimetrics rechnet jede Position anteilig auf die Summe der Zahlungen um, Steuersätze und Kategorien bleiben, die Zuordnung bleibt mit ihrer ID, und der offene Betrag ist danach null. Eine Wiederholung mit gleichem Schlüssel bucht nichts erneut. Nicht möglich ist das, wenn die Zuordnung nicht passt (400 EuroAmountNotEligible, Grund in detail) und bei Buchungen, die schon an DATEV exportiert sind (409 FinalizedBookingsLocked). Festgeschriebene Buchungen werden storniert und neu gebucht, reversedFinalizedMonths nennt die Monate. Skonto bekommt ein solcher Beleg nicht (400 CashDiscountForeignCurrency), denn die Differenz ist meist der Wechselkurs.
Zahlt ein Kunde nach einer Mahnung mehr als die Rechnung, buchst du den Mehrbetrag mit POST /api/match/{id}/reminder-charges als Mahnkosten und Verzugszinsen der zuletzt ausgestellten Mahnung, wie „als Mahnkosten und Zinsen buchen“ in der App. GET /api/match/{id}/reminder-charges-preview nennt vorher Mahnung, Mehrbetrag, Aufteilung und Konten sowie expectedVersions; beim ersten Zuordnen geht das mit confirmReminderCharges. Es braucht genau eine Rechnung ohne Rechnungskorrektur und einen Zahlungseingang ohne Skonto und ohne erfasste Zahlungen, und der Mehrbetrag darf die Gebühren, Pauschale und Zinsen der Mahnung nicht übersteigen. Erst werden die Kosten ausgeglichen, dann die Zinsen, je eine Buchung ohne Umsatzsteuer am Zahltag. Sonst antwortet die API mit 422 ReminderChargesNotEligible; für exportierte Buchungen gilt dieselbe Sperre wie beim Skonto.
Vorschläge der App liest du mit read über POST /api/match/suggestions, für bis zu 20 Belege und Umsätze auf einmal. Einen falschen Vorschlag blendest du mit POST /api/match/dismiss aus, DELETE /api/match/dismiss/{id} holt ihn zurück. Das gilt auch für eine Kombination, die ausgeblendet ist, weil du ihre Zuordnung aufgehoben hast; die automatische Zuordnung darf sie dann wieder nehmen. Über die API lernt bimetrics keine Regel.
Eine Zahlung, die schon außerhalb der Bankumsätze erfolgt ist, erfasst du über POST /api/match/payment. Die Neuerfassung ist standardmäßig ausgeschaltet (manualPaymentsEnabled). Sende Beleg-ID, aktuelle Version, den zuletzt gelesenen remainingPaymentMinor als expectedAmountOpenMinor (ohne erfasste Zahlung den Bruttobetrag), positiven Betrag in Cent, Zahlungstag und method:
cash: bar aus der Kasse.private: privat bezahlt von einem Gesellschafter oder vom Inhaber, nur bei Eingangsbelegen. Optional nenntpaidBy, wer bezahlt hat, höchstens 100 Zeichen ohne doppelte Anführungszeichen; der Name steht im Buchungstext, etwa „Privat bezahlt von Erika Beispiel RE-0042“.clearing: ein anderer Zahlungsweg über das Verrechnungskonto.rounding: keine Zahlung, sondern der ganze Rest eines schon bezahlten Belegs als Rundungsdifferenz, etwa wenn eine Gebührenrechnung erst ihre Summe rundet.amountMinorist dann genau der offene Rest, höchstens 1 € und höchstens ein Cent je Zahlung des Belegs plus einer. bimetrics bucht ihn ohne Umsatzsteuer und ohne Steuerkennzeichen auf sonstige betriebliche Erträge (Eingangsbeleg, SKR03 8603, SKR04 4830) bzw. Aufwendungen (Rechnung, SKR03 4900, SKR04 6300). Nicht bei Belegen in Fremdwährung und nicht bei Abschlagsrechnungen, sonst400 RoundingNotEligiblemit dem Grund indetail; der Tag liegt nicht vor dem Rechnungsdatum oder einer erfassten Zahlung (400 PaymentDateOutOfRange). Solange die Rundung aktiv ist, nimmst du zuerst sie zurück und dann eine Zahlung (409 RoundingStillActive).write_off: keine Zahlung, sondern ein Forderungsausfall einer Ausgangsrechnung (§ 17 Abs. 2 Nr. 1 UStG), der ganze offene Rest oder ein Teil davon.notenennt den Grund, Pflicht und höchstens 500 Zeichen. Bei Soll-Versteuerung bucht bimetrics je Umsatzsteuersatz der Rechnung anteilig auf die Konten für Forderungsverluste (19 %: SKR03 2406, SKR04 6936; 7 %: 2401/6931; sonst 2400/6930), die Zeilen zu 19 % und 7 % mit DATEV-Buchungsschlüssel5000. Bei Ist-Versteuerung wird der offene Bruttoanteil je Steuersatz ausgebucht. Eine zweite Zeile bucht den Nettoverlust mit BU 0040. Ohne deutsche Umsatzsteuer genügt bei beiden Verfahren eine Zeile auf 2400/6930. Nicht für Eingangsbelege, Fremdwährung, Abschlags- und Schlussrechnungen, andere Steuersätze als 19 % und 7 % und nicht, solange die Leistung nach dem Tag noch läuft (400 WriteOffNotEligible, Grund indetail). Danach steht die Rechnung auf ausgebucht, wird nicht gemahnt und nimmt weder Gutschrift noch Storno an, bis die Ausbuchung zurückgenommen ist. Zurück geht sie vor anderen Zahlungen (409 WriteOffStillActive) und nur mitreversedOn: dem Tag der Zahlung, wenn der Kunde doch zahlt, nach einem Irrtum dem Tag der Ausbuchung. Die Zeilen übernehmen die Kostenstelle, die die Rechnung in diesem Moment hat, und behalten sie: erst die Kostenstelle setzen, dann ausbuchen.
Das Konto bestimmt der Server, ein mitgeschicktes Konto lehnt er mit 400 ab; die Antwort nennt es in payment.account. Bei private entscheidet die Rechtsform: GmbH und UG buchen auf „Verbindlichkeiten gegenüber GmbH-Gesellschaftern“ (SKR03 1665, SKR04 3640), ein Konto für alle Gesellschafter, bis die Firma den Betrag mit der Vorlage „Gesellschafter-Verrechnung“ erstattet. Einzelunternehmen, GbR und OHG buchen eine Privateinlage (1890 bzw. 2180). Fehlt die Rechtsform, antwortet die API mit 409 PrivatePaymentNeedsLegalForm, bei anderen Rechtsformen mit 409 PrivatePaymentUnavailable. Wie die Firma privat bezahlte Belege bucht und was sie dem Gesellschafter noch schuldet, liest du vorher mit GET /api/match/payment/private.
Einen Beleg in Fremdwährung bezahlst du auch in seiner Währung, auch solange der Euro-Betrag fehlt: currency ist dann die Belegwährung (etwa USD) und amountMinor in deren Hundertsteln, höchstens der in dieser Währung offene Rest (amountOpenOriginalMinor der Antwort). Das geht mit private und clearing. bimetrics bucht den Euro-Wert des Zahltags: euroAmountMinor, der Euro-Betrag laut Karten- oder PayPal-Abrechnung, sonst den EZB-Referenzkurs des Zahltags oder des letzten Arbeitstags davor; fehlt der, 409 ExchangeRateMissing. Die Zahlung trägt originalAmountMinor, originalCurrency, rate, rateSource (statement oder ecb) und rateDay. Hat der Beleg seinen Euro-Wert, bucht bimetrics die Kursdifferenz gleich mit, sonst im selben Aufruf, der den Euro-Wert setzt (PATCH /api/document/{id} mit euroAtMonthlyRate, euroTotalAmount oder euroAmountsConfirmed; anderes lehnt der Beleg mit Zahlung weiter ab). exchangeDifferenceMinor ist der Anteil der Zahlung am Euro-Wert minus ihr Euro-Betrag; gebucht wird er als eigene Zeile der Zahlung am Zahltag, ohne Steuerschlüssel, auf SKR03 2151/2661 bzw. SKR04 6881/4847 (nicht § 256a HGB). Bei Ist-Versteuerung ermittelt bimetrics die Umsatzsteuer einer Ausgangsrechnung aus dem Euro-Betrag ihrer Zahlungen, wie zum Tageskurs, und bucht keine Kursdifferenz. Gesetzlicher Regelfall nach § 16 Abs. 6 UStG ist bei Ist-Versteuerung der Durchschnittskurs des BMF für den Monat, in dem das Geld eingeht; den Tageskurs, belegt durch Bankmitteilung oder Kurszettel, kann das Finanzamt gestatten. Ob eine Gestattung vorliegt, klärt die Firma mit ihrer Steuerberatung. Weicht die Zahlung vom Euro-Wert ab, lehnt bimetrics sie mit 422 ExchangeDifferenceCashBasis ab, ebenso einen solchen Euro-Wert nach der Zahlung. Dann erfasst du die Zahlung in Euro (ohne currency) mit dem Betrag, der angekommen ist. Ist die Rechnung damit ganz bezahlt, setzt du vorher ihren Euro-Wert darauf (euroTotalAmount) und erfasst sie dann in Euro oder mit currency und demselben euroAmountMinor. Mehrere Zahlungen in der Währung erfasst du alle, bevor der Euro-Wert kommt, und setzt dann die Summe, die angekommen ist; jede Zahlung tilgt dann ihren eigenen Euro-Betrag, ohne Kursdifferenz. Welcher Fall vorliegt, sagt context.variant (siehe Fehler). Ein Beleg nimmt entweder Euro-Zahlungen oder Zahlungen in seiner Währung.
Der Zahlungstag liegt höchstens auf heute (deutsche Zeit), sonst antwortet bimetrics mit 400 PaymentDateOutOfRange. Vergangene und schon exportierte Monate sind erlaubt. Dieselbe Grenze gilt für Rücknahmen, Erstattungen und Verrechnungen; diese liegen außerdem nicht vor dem Datum des Korrekturbelegs bzw. der Rechnung. Teilbeträge dürfen den noch offenen Betrag nicht überschreiten. Der Aufruf löst keine Überweisung aus und erstellt keinen erfundenen Bankumsatz. Sammelbelege, Gutschriften und periodische Belege werden in diesem Ablauf nicht unterstützt. Hat der Beleg schon Buchungen, die an DATEV exportiert sind, bleiben diese unverändert: Die Zahlung ist eine neue Buchung zum Zahltag und geht mit dem nächsten DATEV-Export ihres Monats an die Kanzlei.
Ein neuer Idempotency-Key umgeht die Prüfung des offenen Betrags nicht. Eine irrtümliche Erfassung nimmst du mit POST /api/match/payment/reverse zurück: paymentId, aktuelle Belegversion, aktueller offener Betrag und optional reversedOn. Ohne Datum bucht bimetrics die Gegenbuchung auf den Zahltag, solange dessen Buchung offen ist, sonst auf heute, wie die App es vorschlägt. Die Rücknahme bleibt auch bei ausgeschalteter Neuerfassung und nach einem DATEV-Export verfügbar. Sie erzeugt eine Gegenbuchung und erhält Zahlung, Originalbuchung und GoBD-Historie. Über MCP heißen beide Wege record_document_payment und reverse_document_payment (siehe MCP-Version 2026-11-01).
Doppelt importierten Bankumsatz kennzeichnen
Öffne den doppelt importierten Umsatz in der App und wähle im Menü Doppelten Umsatz entfernen. Wähle dann den Umsatz, der bleiben soll. Vergleiche Gegenpartei, Betrag, Buchungstag und Verwendungszweck mit deinem Kontoauszug. Auch bei gleichen Beträgen kann es sich um zwei echte Zahlungen handeln.
Für beide Endpunkte brauchst du einen Schlüssel eines aktiven Inhabers mit dem Scope matching:write. Die ID im Pfad bezeichnet den doppelt importierten Umsatz. keepId bezeichnet das Original.
GET /api/banktransaction/{id}/duplicate-previewmit dem Query-ParameterkeepIdliefert beide Umsätze mit Buchungstag, Originalbetrag in Hundertsteln, Währung, Gegenpartei und Verwendungszweck (remittanceInformation). Zeige die Anzahl entfallender offener Buchungen (openBookings), vorhandener festgeschriebener Buchungen (finalizedBookings) und neuer Stornos (newReversals). BeialreadyMarkedbesteht die Kennzeichnung bereits.- Nach Bestätigung sende
keepIdund den unverändertenplanHashanPOST /api/banktransaction/{id}/mark-duplicate. Wiederhole dieselbe Anfrage mit demselbenIdempotency-Key. Bei409 TransactionDuplicatePlanChangedhole eine neue Vorschau, lass sie bestätigen und verwende für den neuen Plan einen neuen Schlüssel.
Beide Umsätze müssen zum selben Konto gehören, denselben vorzeichenbehafteten Originalbetrag und dieselbe Originalwährung haben. Ihre Buchungstage dürfen höchstens drei Tage auseinanderliegen. Bei HTTP 409 nennt code den Sperrgrund. Bei duplicate_matched prüfe die Zuordnung der Dublette. Bei duplicate_is_kept dient sie bereits einer anderen Dublette als Original. Bei datev_exported kläre die Berichtigung mit deiner Kanzlei.
Weitere Sperrgründe sind same_transaction (beide IDs gleich), transaction_not_found, transaction_deleted oder confirmation_mismatch (Umsätze in dieser Firma nicht verfügbar), bank_account_mismatch, amount_mismatch, currency_mismatch und booking_dates_apart. Bei keep_marked_duplicate ist das gewählte Original selbst eine Dublette. Bei duplicate_marked_otherwise gehört die Dublette bereits zu einem anderen Original. Bei transaction_changed hole eine neue Vorschau. Bei hooks_unavailable oder duplicate_not_reversed wurde die Kennzeichnung zurückgerollt.
Die Dublette verschwindet aus der Liste und bleibt unter ihrer ID lesbar. Festgeschriebene Buchungen bleiben erhalten. Jedes erforderliche Storno trägt das ursprüngliche Buchungsdatum. Du kannst die Kennzeichnung nicht selbst zurücknehmen. Bei einer Fehlmarkierung wende dich an den Support.
Ab MCP-Version 2026-11-22 gibt es preview_transaction_duplicate und mark_transaction_duplicate. Beide verwenden dieselben Rechte und Sperren. Vor der Kennzeichnung muss der Nutzer die gezeigten Folgen bestätigen.
Mehrere Belege auf einmal
Vier Aktionen der Mehrfachauswahl gibt es für bis zu 50 Belege je Aufruf: POST /api/document/bulk/category setzt eine Kategorie, POST /api/document/bulk/kind die Belegart, POST /api/document/bulk/cost-center die Kostenstelle, und POST /api/match/payment/bulk markiert Eingangsbelege als bar oder privat bezahlt. Alle nehmen documentIds, dryRun und expectedVersions und antworten mit denselben Listen:
change: was sich ändert oder geändert hat, dazutotalMinor.skipped: was bleibt, mitreason, nach denselben Regeln wie in der App.failed: was der Server ablehnt, mitcode. Eine Ablehnung ändert nichts. Nur beiOutcomeUnknownkann der Beleg gebucht sein, weil der Aufruf abbrach, während er lief. Eine Wiederholung mit gleichemIdempotency-Keyklärt das.
Die Route antwortet auch bei einem Teilerfolg mit 200. Mit dryRun: true ändert sie nichts und liefert je Beleg eine version. Zum Ausführen ist expectedVersions Pflicht, sonst antwortet sie mit 400 ExpectedVersionRequired, wie beim Einzelaufruf ohne Version. Es ändert sich nur, was unter change stand und seitdem unverändert ist: Ein inzwischen geänderter Beleg landet mit VersionConflict in failed, die übrigen laufen, und ein Beleg ohne Eintrag bleibt mit notPreviewed in skipped. Jeder Beleg läuft als eigener Befehl und zählt einzeln auf die Tagesgrenze. Eine Wiederholung mit gleichem Idempotency-Key ändert nichts doppelt und erledigt, was noch offen ist; replayed markiert, was schon erledigt war.
Bei der Belegart ist kind invoice oder receipt, und jede Änderung läuft wie kind in PATCH /api/document/:id. Das ist eine Wahl: Sie beendet „Belegtyp prüfen“ (kindReview) auch dann, wenn die Belegart gleich bleibt. Ein Beleg, der die Belegart schon hat und nicht auf diese Wahl wartet, bleibt mit unchanged in skipped, ebenso an DATEV exportierte (exported). change nennt die bisherige Belegart in kindBefore. Beim Richtungswechsel enthält der Eintrag zusätzlich kindChange mit denselben Angaben wie die Einzelkorrektur. Die Version bindet die geplanten Positionskategorien, die Gegenpartei samt Kundennummer und die resultierende Kostenstelle. Ändert sich beispielsweise die Standardkostenstelle des Zielkontakts, erhältst du für diesen Beleg VersionConflict.
Bei der Kostenstelle ist costCenterId Pflicht: die ID einer Kostenstelle oder Verteilung, ein leerer String entfernt sie. Weil sich kein Betrag ändert, geht das auch bei ausgestellten und bezahlten Belegen. Festgeschriebene Belege stehen mit finalized in skipped. Einzeln lässt sich ihre Kostenstelle mit PATCH /api/document/{id} trotzdem ändern; dann storniert bimetrics die Buchungen und bucht sie neu, nach dem DATEV-Export als Nachtrag; ein API-Schlüssel braucht dafür documents:correct. Stornorechnungen stehen mit cancellation in skipped, denn sie übernehmen die Kostenstelle ihrer Rechnung; geändert wird sie an der Rechnung. Hat ein Beleg samt seiner Zuordnung keine Buchung auf einem Erfolgskonto, etwa der Beleg einer Gehaltsvorlage, ändert sie keine Buchung: Dann geht sie auch an festgeschriebenen und exportierten Belegen, hier wie einzeln. Ein Beleg mit einer Anlage im Bestand, auch einem GWG, gehört nicht dazu, obwohl er nur auf das Anlagekonto bucht: Die Abschreibung der Anlage übernimmt seine Kostenstelle. Offene Abschreibungen bucht bimetrics neu, festgeschriebene storniert es zu ihrem Datum und bucht sie neu. Festgeschrieben bleibt ein solcher Beleg hier deshalb mit finalized in skipped. change nennt die bisherige Kostenstelle in costCenterBefore.
Bei der Zahlung bucht bimetrics je Beleg den vollen offenen Betrag, Zahltag ist das Belegdatum, bei einem Datum in der Zukunft heute. Geld bewegt sich nicht. method ist cash oder private, bei private ist paidBy Pflicht. Andere Wege und Teilbeträge laufen einzeln über POST /api/match/payment.
Belege gezielt korrigieren
Mit documents:write und PATCH /api/document/:id berichtigst du einen Beleg wie in der App: Kopffelder, Belegart, Gegenpartei sowie Bezeichnung, Betrag, Kategorie, Umsatzsteuersatz und Steuerfall einzelner Positionen. Ausgelassene Felder bleiben erhalten. Das ist kein Ersatz des gesamten Belegs.
- Positionen änderst du über
positions:update(Standard) undremovesprechen eine Position über ihren nullbasiertenindexin der zuletzt gelesenen Liste an,addhängt eine neue Position hinten an. Eine neue Position brauchtcategory,vatPercentageund einen Betrag ungleich 0. Die letzte Position eines Belegs lässt sich nicht entfernen. - Beträge sind Bruttobeträge in EUR-Cent (
amountMinor), wietotalim Beleg. Sobald sich Beträge ändern, sendest du die neue Bruttosumme aller Positionen alsexpectedTotalMinor. Ändert sich der Betrag einer Position, entfallen ihre Unterpositionen. - Steuersätze sind 19, 7 und 0 %, bei Eingangsbelegen auch 9 und 5,5 %.
- Steuerfall (
vatTreatment:none,reverseCharge,freeOfVat) gibt es nur bei 0 %; er entsprichtadditionalInfoim Beleg. Reverse Charge gilt für alle Positionen eines Belegs; setze ihn in einem Aufruf für jede Position. Eine neue Position eines Eingangsbelegs mit 0 % braucht einen Steuerfall. - Monatskurs (
euroAtMonthlyRate: true) rechnet einen Beleg in Fremdwährung mit „Euro-Betrag fehlt“ zum Monatskurs des BMF um; ob das gerade geht, sagt vorherGET /api/document/{id}/monthly-rate. - Euro-Betrag (
euroTotalAmount) trägst du bei einem Beleg in Fremdwährung ein, solange er fehlt oder wenn er sich ändert, wie „Euro-Betrag eintragen“ in der App: Bruttobetrag in EUR-Cent, größer 0. bimetrics rechnet die Positionen anteilig darauf um, Steuersätze und Kategorien bleiben, eine Gutschrift bleibt negativ, undeuroAmountSourcesteht danach aufperson.expectedTotalMinorist dabei freiwillig; sendest du es, muss es die Summe danach sein. Bei einem Euro-Beleg antwortet die API mit409 DocumentNotForeignCurrency. Hast du die Positionen schon selbst in Euro geändert, beendeteuroAmountsConfirmed: trueden Hinweis, ohne einen Betrag zu ändern. - Gegenpartei (
counterparty) ist bei Ausgangsrechnungen der Empfänger, sonst der Aussteller. MitcontactIdübernimmst du einen Kontakt deiner Firma samt Kundennummer, gebucht wird dann auf sein Personenkonto. Hätte der Kontakt auf dieser Seite kein eigenes Personenkonto, weil seine Nummer bei einem Eingangsbeleg über 29999 oder bei einer Ausgangsrechnung über 59999 liegt, lehnt die API das mit400 InvalidContactWriteab. Alternativ setzt duname,vatId,addressundibandirekt. Ein neuer Name löst die Verknüpfung mit dem Kontakt: Die Kundennummer entfällt, gebucht wird auf das Sammelkonto. Ein leerer Wert entfernt USt-IdNr., Adresse oder IBAN. - Belegart (
kind) wechselst du zwischeninvoiceundreceipt. Positionen, die du im selben Aufruf bearbeitest, werden für die gewählte Richtung geprüft. Bei einem Beleg ohne offene Typprüfung leert bimetrics Kategorien, die ausschließlich zur bisherigen Richtung gehören. Beim Wechsel zur Ausgangsrechnung kann eine eindeutige Erlöskategorie eingesetzt werden. Steht deine Firma erkennbar auf der buchungsrelevanten Seite und ist die andere Partei identifizierbar, tauscht bimetrics Aussteller und Empfänger. Eine gültige Kundennummer der Gegenpartei bleibt erhalten. Gibst du beim Wechselcounterpartyan, verknüpft nur eine ausdrücklichecontactIdeinen Kontakt. Drehst du bei „Belegtyp prüfen“ die Richtung eines unbearbeiteten, automatisch erkannten Belegs um, bleiben die Parteien erhalten und bimetrics vergibt die Kategorien im Hintergrund neu. Bei einem zugeordneten Beleg zählt der Betrag in der Zuordnung mit umgekehrtem Vorzeichen. Auch nach einer Festschreibung oder einem Export kannst du eine Einzelkorrektur speichern, wenn Angaben für die Neubuchung fehlen. Der Beleg zeigt die zugehörigen Buchungsmeldungen. - Ergebnis des Richtungswechsels (
kindChangein Vorschau und Ausführung). Incategoriesfindest du die automatisch geänderten Kategorien mit ihrem Positionsindex im Ergebnis (ab 0). Bei einer geleerten Kategorie stehtcategory: null.partiesSwappedmeldet den Tausch,categoriesMissingweist auf offene Kategorien hin. Bestätigst du einen Beleg unter Typprüfung, weistcategoriesMismatchauf beibehaltene Kategorien hin, die nicht zum bestätigten Typ passen. Steht deine Firma weiterhin als Gegenpartei am Beleg, meldetcounterpartyNeedsReview: true, dass du die Gegenpartei prüfen musst. Geleerte Kategorien bleiben dann offen. Eine Wiederholung mit demselben Idempotenzschlüssel führt den Wechsel nur einmal aus und liefert seinen Änderungsbericht beim ersten Aufruf. - Fälligkeit und Leistungsdatum: Ein leerer String (
"dueDate": "") entfernt die Fälligkeit,nulländert nichts."performancePeriodTo": ""macht aus dem Leistungszeitraum ein einzelnes Leistungsdatum, nämlich den Beginn. Ein einzelnes Datum setzt du mitperformancePeriodFromohne Ende. - Leistungszeitraum je Position: Haben Positionen verschiedene Zeiträume, etwa der Verbrauch des Vormonats und ein Abo bis in den nächsten Monat, setzt du je Position
performanceFromundperformanceTo(Datumsobjekt oderYYYY-MM-DD, leerer String entfernt). Die Position bucht dann auf ihren eigenen Zeitraum, die übrigen weiter auf den des Belegs.performanceTobraucht einen Beginn und liegt nicht davor. Bei in bimetrics ausgestellten Rechnungen lehnt der Server das ab (409 DocumentWriteLocked), auch zusammen mit einer fehlenden Kategorie. - Geschützt sind ausgestellte Ausgangsrechnungen und Belege aus Dauerbuchungen. Belege mit Buchungen, die schon an DATEV exportiert sind, berichtigt der Server wie in der App: Die exportierte Buchung bleibt stehen, bimetrics storniert sie in ihrem Monat und bucht neu, und
addendaMonthsin der Antwort nennt die Monate, die mit dem nächsten DATEV-Export des Monats als Nachtrag an die Kanzlei gehen. Ein API-Schlüssel braucht dafür das Rechtdocuments:correct; ohne dieses Recht antwortet der Server mit409 FinalizedBookingsLockedund nennt das Recht incontext.scope. An einem Beleg mit erfasster Zahlung, etwa bar über das Kassenbuch, nimmt der Server nur Felder an, die keine Buchung ändern:invoiceNumber,dueDate,costCenterIdundstatedTotalAmount; bei einer Zahlung in der Belegwährung kommt der Euro-Wert hinzu (euroTotalAmount,euroAtMonthlyRate,euroAmountsConfirmed). Auchcounterpartygeht: Beleg und Zahlung buchen dann gemeinsam auf den neuen Kontakt um, solange sich nur das Personenkonto ändert; sonst antwortet der Server mit409 DocumentWriteLocked, undcontext.reasonnennt den Grund (paidCounterpartyIssues,paidCounterpartyTax,paidCollective,paidSettlement,paidInCurrency). Alles andere lehnt der Server ebenfalls mit409 DocumentWriteLockedab, bis die Zahlung zurückgenommen ist. Belege aus Buchungsvorlagen lassen sich berichtigen; löst du später ihre Zuordnung, entfällt der erzeugte Beleg samt Berichtigung. Sind Buchungen nur festgeschrieben und nicht exportiert, storniert bimetrics sie wie in der App in ihrem ursprünglichen Monat und bucht mit den neuen Werten neu;reversedFinalizedMonthsin der Antwort nennt die Monate, in denen sich Datum, Leistungszeitraum, Konto, Steuerkennzeichen oder Betrag ändern.
Eine abgelehnte Änderung nennt in context.field das Feld der Anfrage, z. B. positions[1].vatTreatment. Eine Position aufteilen, also Betrag ändern und eine zweite Position anlegen:
{
"expectedVersion": "<version>",
"positions": [
{"index": 0, "amountMinor": 7000},
{"op": "add", "label": "Fachbuch", "amountMinor": 4900, "category": "magazines_books", "vatPercentage": "7"}
],
"expectedTotalMinor": 11900
}Per E-Mail senden
Ausgestellte Rechnungen, Stornorechnungen, Rechnungskorrekturen, Angebote, Auftragsbestätigungen und Mahnungen verschickst du wie mit „Per E-Mail senden“ in der App. Den Versand richtest du in der App unter Einstellungen › E-Mail-Versand ein (app.bimetrics.de/settings/email-sending), dort pflegst du auch Vorlagen und Signatur.
POST /api/document-mail/previewliefert mitsales:readden Vorschlag der App: Empfänger aus dem Dokument oder seinem Kontakt, Betreff und Text aus deiner Vorlage mit den Werten des Dokuments, die Anhänge und die letzte Sendung.target.kindistdraftfür Rechnungen, Angebote und Auftragsbestätigungen undreminderfür Mahnungen.POST /api/document-mail/sendsendet mitmail:sendantoundcc, mitsubjectundbodygenau so, wie du sie schickst. Darunter setzt bimetrics Signatur und Pflichtangaben. Absender ist bimetrics, Antworten gehen an deine Antwortadresse.
Weitere Dateien gibst du in attachments mit, in Vorschau und Senden gleich: bis zu 10 als {"documentId": …} für einen Beleg, {"draftId": …} für eine ausgestellte Rechnung, ein Angebot oder eine Auftragsbestätigung oder {"uploadId": …} für eine Datei, die du vorher mit POST /api/document-mail/attachments hochlädst. Erlaubt sind PDF, JPG und PNG, alle Anhänge zusammen höchstens 10 MiB, PDF und XML eingerechnet (400 DocumentMailAttachmentsTooLarge). Zu einer XRechnung gehen keine weiteren Dateien.
Die Vorschau ist freiwillig. Eine Versionsprüfung entfällt, denn ein ausgestelltes Dokument ändert sich nicht mehr. Der Header Idempotency-Key ist Pflicht: Eine Wiederholung sendet nichts doppelt. Je Firma gehen höchstens 20 Empfänger am Tag raus, in der Testphase 3, für App, API und MCP zusammen. Darüber antwortet die API mit 429 DocumentMailLimitExceeded. Einen Entwurf sendet sie nicht (409 DocumentMailNotIssued), eine stornierte Rechnung auch nicht (409 DocumentMailInvoiceCancelled): Dann sendest du ihren Stornobeleg. Eine Mahnung sendet sie nicht mehr, wenn ihre Rechnung storniert, ganz oder teilweise ausgebucht oder bezahlt ist oder eine spätere Mahnung sie abgelöst hat (409 DocumentMailReminderClosed, Grund in context.reason). Eine früher gesendete Mail bleibt in beiden Fällen gesendet.
GET /api/draft/{id} und GET /api/reminder/{id} liefern in documentMail die neueste Mail mit dem Dokument und ihren Versandstand, auch wenn die Vorschau das Dokument ablehnt. status ist queued, solange die Mail noch auf den Versand wartet, sent nach der Übergabe an den Maildienst, bounced, wenn sie bei einem Empfänger nicht ankam, und failed, wenn sie nicht rausging. Angekommen ist sie erst, wenn deliveredAt gesetzt ist, also alle Empfänger sie angenommen haben. Ob sie gelesen wurde, weiß bimetrics nicht.
Firmendaten ändern
Die Firmendaten änderst du mit company:write wie in den Einstellungen der App: Name, Rechtsform, Anschrift, Kontaktangaben, Geschäftsführung, Steuernummer, USt-IdNr., Handelsregister, Nummernkreise, Skonto-Vorgabe, Zahlungsziel, Schlusstext, Textvorlagen neuer Belege, DATEV-Nummern, Art der Umsätze und Rechnungsabgrenzung.
GET /api/company/liefert sie mitreaduntersettings, die Textvorlagen unterdocumentTexts, dazu ihreversion.PATCH /api/company/ändert nur die Felder, die du nennst, auch einzeln innerhalb vonaddress,contactInfo,accounting,invoiceDefaultsunddocumentTexts. Im Anfrageinhalt steht die geleseneversionalsexpectedVersion, dazu der HeaderIdempotency-Key.nullentfernt die Skonto-Vorgabe (accounting.cashDiscount) und das Zahlungsziel (invoiceDefaults.paymentTermDays).
Die Änderungen gelten für neue Entwürfe und ab jetzt ausgestellte Belege. Ausgestellte Belege behalten ihre Angaben. Es gelten dieselben Prüfungen wie in der App, etwa für den Start eines Nummernkreises (400 NumberStartTaken), die DATEV-Nummern (400 DatevNumberInvalid) und die USt-IdNr. (400 VatIdInvalid). Hat jemand die Firmendaten seit dem Lesen geändert, etwa in der App, antwortet die API mit 409 CompanyVersionConflict und ändert nichts. Kontenrahmen, Versteuerung samt Befreiungsgrund, Versteuerungsart (Soll oder Ist) und Bankverbindung änderst du nur in der App. Nennt der Anfrageinhalt eines dieser Felder oder ein unbekanntes, antwortet die API mit 400 CompanyFieldNotChangeable und dem Feld in context.field. Firmentexte, die auf Rechnungen stehen, nehmen keine Bankdaten auf, weder eine IBAN noch Wörter wie BIC, Kontonummer oder Bankverbindung: Ein geänderter Text damit ergibt 400 CompanyTextBankDetails, ein unveränderter gespeicherter Text bleibt.
Kostenstellen
Mit Kostenstellen kann die Steuerberatung jeden Standort oder Bereich getrennt auswerten, denn der DATEV-Export gibt sie als KOST1 weiter. Kostenstellen und Verteilungen änderst du mit company:write wie unter Einstellungen › Buchhaltung › Kostenstellen in der App.
GET /api/cost-centersliest sie mitread, auch archivierte, jeweils mit der Zahl der Belege undused.POST /api/cost-centerslegt eine Kostenstelle an (kindcentermitcodeundname) oder eine Verteilung (kinddistributionmitnameundshares). Die Anteile stehen in Basispunkten und ergeben zusammen 10000. HeaderIdempotency-Key.PUT /api/cost-centers/{id}ändert sie, mit dem gelesenenupdatedAtalsexpectedUpdatedAt. Schick alle Werte mit, auch die unveränderten. Nummer und Anteile stehen fest, sobald ein Beleg sie nutzt. Für andere Anteile legst du eine neue Verteilung an und archivierst die alte mitPOST /api/cost-centers/{id}/archive.
Am Beleg setzt du die Kostenstelle mit costCenterId in PATCH /api/document/{id}, an vielen Belegen auf einmal wie oben beschrieben. Bei einer Rechnung gibst du sie schon im Entwurf mit: costCenterId in POST /api/draft/ und PUT /api/draft/{id}. Ein leerer String heißt ausdrücklich keine; fehlt das Feld, gilt beim Ausstellen die des Kunden. Neue Belege eines Kontakts bekommen dessen defaultCostCenterId, Belege einer Dauerbuchung deren costCenterId. Neue Belege einer Vorlage bekommen deren costCenterId, vor der Vorgabe am Kontakt; Belege, die es schon gibt, behalten ihre. Am Beleg einer Dauerbuchung lässt sich nur die Kostenstelle ändern, alle anderen Felder folgen der Dauerbuchung. Eine Stornorechnung übernimmt die Kostenstelle ihrer Rechnung; eine eigene lehnt der Server mit 409 DocumentWriteLocked ab. An den Buchungen steht die Kostenstelle nur bei Aufwands- und Erlöskonten. Eine Verteilung teilt der DATEV-Export in eine Zeile je Kostenstelle, und costCenterParts der Buchung nennt die Beträge centgenau wie im Export. Eine archivierte Kostenstelle lässt sich nicht mehr wählen (409 CostCenterRejected), Belege behalten sie. Gelöscht wird nie.
Wie jede Kostenstelle dasteht, liest GET /api/cost-centers/report mit read: Erträge, Aufwand, Personalkosten und Ergebnis netto in Cent für einen Monat, ein Quartal oder ein Jahr und den Vergleichszeitraum, dazu je Kostenstelle die Konten. Gezählt wird jede Buchung auf einem Erfolgskonto, die Ertragskonten in revenueMinor, alle übrigen in expensesMinor; total ist die Summe aller Zeilen. Daneben stehen in payrollPaidMinor die Zahlungen über die Gehaltsvorlagen auf die Lohnverbindlichkeiten, am Tag der Zahlung und mit der Kostenstelle ihres Belegs; resultMinor zieht sie ab. Belege ohne Kostenstelle stehen in withoutCostCenter, auch Belege aus Buchungsvorlagen (templateId); die Kostenstelle setzt du wie oben mit costCenterId am Beleg. Für eine eigene Liste zum Wählen beschreibt GET /api/cost-centers/documents bis zu 20 Belege mit Name, Bruttobetrag, Sperre und den Kostenstellen, die der Kontakt schon hatte.
Kassenbuch
Hat die Firma eine Kasse mit Bargeld, führt ein Kassenbuch deren Bestand auf einem eigenen Kassenkonto. Ein- und ausschalten, anlegen, umbenennen und stilllegen darf nur ein Inhaber, mit company:write, wie unter Einstellungen › Kassenbuch in der App. bimetrics ist keine Registrierkasse: Einzelne Barverkäufe kommen nicht ins Kassenbuch, nur ihre Tagessumme aus einem Kassensystem mit TSE oder abends aus dem Kassenbericht.
PUT /api/settings/cash-bookschaltet das Kassenbuch ein (enabled: true). Ausschalten geht erst, wenn kein Kassenbuch mehr in Gebrauch ist. HeaderIdempotency-Key.POST /api/cash-bookslegt ein Kassenbuch an, mitkind,name,startDateundopeningBalanceMinor; liegt der Anfangsbestand über 0, auch mitopeningSource. Ohneaccountnimmt bimetrics das nächste freie Kassenkonto ausGET /api/settings/cash-book. Art, Kassenkonto, Beginn und Anfangsbestand stehen danach fest. Höchstens drei Kassenbücher sind gleichzeitig in Gebrauch; ein viertes lehnt bimetrics mit409 CashBookRejectedab, bis eins stillgelegt ist. HeaderIdempotency-Key.PATCH /api/cash-books/{id}benennt es um, mit dem gelesenenupdatedAtalsexpectedUpdatedAt.POST /api/cash-books/{id}/archivelegt es still; es bleibt lesbar, und sein Kassenkonto wird frei für ein neues Kassenbuch.
Buchen dürfen Inhaber und Nutzer, mit matching:write, nicht die Steuerberatung:
GET /api/cash-books/{id}/entriesliest einen Monat (month=JJJJ-MM) mit Tagen, Beständen und Einträgen. Jeder Eintrag hat eine Nummer, je Kassenbuch und Jahr lückenlos, etwaKB-2026-0001.POST /api/cash-books/{id}/entries/previewprüft Einträge und zeigt die Buchungen und den Bestand danach, mitexported, wenn ein Eintrag in einem schon an DATEV exportierten Zeitraum liegt,POST /api/cash-books/{id}/entriesbucht sie, mitexpectedBalanceMinoraus dem letzten Lesen und HeaderIdempotency-Key. Ohne Beleg gibt es Ausgaben mit Eigenbeleg (ohne Vorsteuer), Einlagen und Entnahmen und Geld zwischen Geschäftskonto und Kasse; mitdocumentIdbucht der Eintrag die Barzahlung eines Belegs. Der Bestand darf nach keiner Buchung unter 0 € fallen.POST /api/cash-book-entries/{id}/reversestorniert einen Eintrag mit Grund, auch Wochen später. Das Storno trägt den Kassentag des Eintrags, solange dessen Monat offen ist; ist der Monat abgeschlossen, steht es mit heutigem Datum im laufenden Monat. In einem stillgelegten Kassenbuch lässt sich nichts mehr stornieren. HeaderIdempotency-Key. Ist bei einem eigenen Eintrag ohne Beleg nur ein Wert falsch, korrigiertPOST /api/cash-book-entries/{id}/correctihn in einem Schritt: Storno mit Grund und richtiger Eintrag mitcorrectsEntryIdwerden zusammen gebucht oder keiner, mit Vorschau unterPOST /api/cash-book-entries/{id}/correct/preview. Eine Barzahlung zu einem Beleg und eine Zeile eines Tagesabschlusses gehen weiter nur per Storno.- Geld zwischen Geschäftskonto und Kasse braucht seinen Bankumsatz:
GET /api/cash-book-entries/{id}/bank-transactionsnennt die passenden,POST /api/cash-book-entries/{id}/bank-transactionordnet einen zu (Artcash_transit, gegen Geldtransit). Bis dahin trägt der EintragbankMissing. Gelöst wird mitDELETE /api/match/{id}; erst danach lässt sich der Eintrag stornieren. HeaderIdempotency-Key. Eine Barabhebung geht auch in einem Schritt vom Bankumsatz aus:GET /api/banktransaction/{id}/cash-in-previewmitcashBookIdund optionalentryDatezeigt Kassentag, passende Tage (firstDate,lastDate), Bestand vorher und nachher, beide Buchungen,exportedMonthsund inwaitingEinträge, die schon auf den Umsatz warten. Gibt es einen, ordne lieber ihn zu. Nach Bestätigung buchtPOST /api/banktransaction/{id}/cash-inmitcashBookId,entryDate,expectedBalanceMinorundplanHashden Eintragtransit_inund die Zuordnung zusammen, mit HeaderIdempotency-Key. Hat sich der Plan geändert, antwortet die Route mit409 CashBookRejected. Eine Bareinzahlung geht genauso aus der Kasse:GET /api/banktransaction/{id}/cash-deposit-previewundPOST /api/banktransaction/{id}/cash-depositbuchen einen Eintragtransit_outund lehnen ab, wenn der Kassenbestand unter null fiele. POST /api/cash-books/{id}/countsspeichert eine Zählung der Kasse mit heutigem Datum, nach Scheinen und Münzen oder als Summe, mitexpectedBalanceMinorund HeaderIdempotency-Key.POST /api/cash-books/{id}/counts/previewzeigt vorher Differenz und Buchung. Bei einer Differenz entscheidetresolution:later, wenn eine Buchung fehlt, die du danach erfasst, oderbookedfür einen Kassenfehlbetrag bzw. Kassenüberschuss ohne Umsatzsteuer. Ein Überschuss aus einer bar bezahlten Rechnung ist eine Einnahme und gehört mitdocumentIdan den Beleg. Die Monatsansicht nennt die Zählungen incounts.POST /api/cash-books/{id}/months/{month}/close/previewprüft, ob sich ein Monat (JJJJ-MM) abschließen lässt: vorbei, frühere Monate abgeschlossen, seit dem Monatsersten gezählt, eine maßgebliche Zählung ohne spätere Buchung bis zu ihrem Tag und ohne offene Differenz (countAgrees), nie im Minus, Nummern lückenlos.GET /api/cash-books/{id}/pdf/pagesliefert das PDF des Monats mit Seitenbildern zum Gegenlesen.POST /api/cash-books/{id}/months/{month}/closeschließt ihn endgültig ab, mitexpectedClosingMinorundexpectedEntriesaus der Prüfung und HeaderIdempotency-Key. Abschließen dürfen Inhaber und Steuerberatung, nicht der Nutzer. Danach geht keine Buchung und keine Barzahlung mehr in den Monat, seine Buchungen sind festgeschrieben (finalizedBycashbook), und ein Storno kommt in den laufenden Monat.closedThroughundnextCloseam Kassenbuch undclosedin der Monatsansicht zeigen den Stand.
Hat die Firma ein Kassenbuch in Gebrauch, braucht POST /api/match/payment mit method: cash die cashBookId; zurücknehmen lässt sich eine solche Zahlung nur über das Storno im Kassenbuch. Ohne Kasse geht Bargeld nur an Tagen, die kein Kassenbuch geführt hat, und eine Barzahlung ohne Eintrag lässt sich immer an ihrem eigenen Zahltag zurücknehmen. Die Sammelzahlung nimmt dann kein cash mehr. Stilllegen geht erst mit leerer Kasse. Gelöscht wird nie, und jede Änderung steht mit Person, Zeit und Kanal im Protokoll.
Bankkonten aktivieren und deaktivieren
Mit bankaccounts:write schaltest du Bankkonten ein und aus wie „Konto aktivieren“ und „Konto deaktivieren“ unter Einstellungen › Bank in der App. Ein API-Schlüssel gehört immer einem Inhaber und darf deshalb jedes Bankkonto der Firma schalten. Beide Routen brauchen den Header Idempotency-Key und antworten mit dem Konto, wie es danach gespeichert ist.
POST /api/bankaccount/{id}/enableaktiviert das Konto. Liefert eine funktionierende Bankfreigabe der Firma das Konto, hängt bimetrics es an die jüngste davon, ohne die Bank zu fragen; neue Umsätze holt deren nächster Abruf. Gibt es keine, bleibt die Bindung, wie sie war, undconnectedzeigt, ob das Konto eine Bankverbindung hat. Ein aktives Konto mit Bankverbindung belegt einen Platz im Tarif. Ist keiner frei, antwortet die Route mit402 LimitReachedund speichert nichts; ist ein anderes Konto deaktiviert oder der Tarif gewechselt, geht es mit demselbenIdempotency-Keyweiter.POST /api/bankaccount/{id}/disabledeaktiviert das Konto. bimetrics holt danach keine Umsätze mehr dafür, und der Platz im Tarif wird frei. Umsätze, Zuordnungen und Buchungen bleiben;POST /api/banktransaction/filterliefert die Umsätze eines deaktivierten Kontos aber nicht.
Läuft gerade der Abruf des Kontos oder eine andere Aktivierung, die die Plätze im Tarif zählt, wartet die Route höchstens 5 Sekunden und antwortet dann mit 409 BankAccountBusy, ohne etwas zu ändern. Sende denselben Aufruf mit demselben Idempotency-Key nach einer Minute noch einmal. Ein 409 IdempotencyConflict heißt dagegen, dass der Key schon für eine andere Anfrage benutzt wurde, etwa für ein anderes Konto; dann nimmst du einen neuen.
Ist ein Idempotency-Key schon verarbeitet, läuft bei einer Wiederholung nichts erneut. Die Antwort zeigt den aktuellen Stand des Kontos, und der kann inzwischen ein anderer sein: Hat jemand das Konto in der App wieder deaktiviert, antwortet die Wiederholung von /enable mit disabled: true. Ist das Konto schon im gewünschten Zustand, ändert sich nichts.
Bank verbinden, eine Freigabe erneuern und trennen geht nur in der App. Wie es um die Freigaben steht, liest du mit GET /api/bankaccount/connections. Bestehende Schlüssel erhalten bankaccounts:write nicht.
Kontoauszug einlesen
Umsätze aus einer Datei der Bank liest du mit statements:import ein, wie „Kontoauszug einlesen“ in der App. Das geht nur mit dem Schlüssel des Inhabers, und ohne Vorschau gar nicht:
POST /api/bankstatement/uploadnimmt die Datei an und nenntuploadId. Dieselbe Datei, noch nicht übernommen, ergibt denselben Upload. HeaderIdempotency-Key.POST /api/bankstatement/inspectschlägt Spalten (mapping), Format und Konto vor und zeigt bis zu 20 Zeilen.POST /api/bankstatement/previewliest die ganze Datei und vergleicht sie mit den Umsätzen des Kontos: neu, schon da, zu prüfen, vorgemerkt, dazu nicht gelesene Zeilen, Salden und Hinweise. Gebucht wird nichts.POST /api/bankstatement/applyübernimmt das, mit demselben Konto und derselben Zuordnung, spätestens 60 Minuten nach der Vorschau, sonst409 BankStatementPreviewRequired. Prüf-Fälle ähneln einem vorhandenen Umsatz und werden nur geschrieben, wennincludeReviewPositionssie nennt. HeaderIdempotency-Key.
Übernehmen lässt sich nicht rückgängig machen: Jede neue Zeile wird zum Umsatz mit Buchung und automatischer Zuordnung, im Hintergrund. Beim Einlesen vergleicht bimetrics noch einmal, die Zahlen können also von der Vorschau abweichen. GET /api/bankstatement/imports/{id} nennt das Ergebnis, POST /api/bankstatement/imports/{id}/retry startet einen fehlgeschlagenen Import neu. Bestehende Schlüssel erhalten statements:import nicht.
Belege löschen
Einen Beleg löschst du mit documents:delete wie „Löschen“ in der App, in zwei Schritten:
GET /api/document/{id}/delete-previewsagt mitread, was das Löschen gerade täte:deleted(Beleg, Datei und offene Buchungen verschwinden),cancelled(festgeschriebene Buchungen bleiben und werden in ihren Monaten storniert,reversedFinalizedMonths, der Beleg bleibt als storniert stehen) oderretained_copy(eine hochgeladene Kopie derselben Datei übernimmt, sonst ändert sich nichts). Geht es nicht, nenntrefusedBecauseden Grund.DELETE /api/document/{id}tut genau das. Im Anfrageinhalt stehenexpectedVersion,expectedOutcomeundexpectedRepresentativeIdaus der Vorschau, dazu der HeaderIdempotency-Key. Weicht einer der drei Werte ab, wird nichts gelöscht. Welche Monate tatsächlich storniert wurden, nennt die Antwort inreversedFinalizedMonths.
Gelöschtes lässt sich nicht wiederherstellen, einen Papierkorb gibt es nicht, und das Kontingent bleibt verbraucht. Belege mit an DATEV exportierten Buchungen löschst du nur in der App. Bestehende Schlüssel erhalten das Recht nicht.
Duplikat-Einträge entstehen, wenn eine Datei erneut hochgeladen wird, die die Firma schon hat. GET /api/document/duplicates liest sie, POST /api/document/duplicates/delete entfernt die ausgewählten. Beleg, Datei, Buchungen und Zuordnung bleiben stehen. Danach hält keine Kopie mehr den Beleg, wenn das Original gelöscht wird.
Vorlagen und Dauerbuchungen
Eigene Buchungsvorlagen und Dauerbuchungen änderst du mit collections:write wie in der App. Es gelten dieselben Regeln wie im Formular. Bezeichnung, Kategorie, Steuersatz und bei Dauerbuchungen der Rhythmus werden nur geprüft, wenn sie sich ändern, ältere Einträge lassen sich also weiter speichern.
Für eine Vorlage für Bußgelder und Verwarnungsgelder sendest du an POST /api/document/collection/series/ kind: "receipt", die Behörde in issuer und in der Buchungszeile die Kategorie fines_penalties mit vatPercentage: 0 und additionalInfo.freeOfVat: true.
POST /api/document/collection/contract/previewsagt, was Anlegen, Ändern, Beenden oder Löschen einer Dauerbuchung mit ihren Belegen täte: neue Belege, auch für vergangene Perioden, geänderte, entfallende und bleibende.POST /api/document/collection/contract/legt sie an,PUT /api/document/collection/contract/{id}ändert nur die Felder, die du nennst. Zum Beenden genügtdocumentContractRepetitionFixedmit dem neuenend. Das Ende gilt ausschließlich und muss die laufende Periode behalten.DELETE /api/document/collection/contract/{id}entfernt künftige Belege, mitpastDocuments=trueauch die bis heute. Zugeordnete, bezahlte und festgeschriebene Belege bleiben. Solange ein Beleg zugeordnet ist, lehnt die Route ab.
Ändern und Löschen brauchen expectedUpdatedAt mit dem gelesenen updatedAt, beim Löschen im Anfrageinhalt. Standardvorlagen von bimetrics (systemTemplateId gesetzt) lassen sich zuordnen, aber nur in der App ändern oder löschen.
Automatisierungen
Automatisierungen liest du mit automations:read und änderst sie mit automations:write, wie unter Automatisierung › Automatisierungen in der App. Eine freie Regel beschreibt in eigenen Worten, wie Belege gebucht werden; die Erkennung beachtet sie beim Lesen. Eine feste Regel hat Bedingungen in match, die bimetrics genau so prüft, wie sie dastehen. Sie setzt targetCategory und auf Wunsch mit setKind auch den Belegtyp, beim Upload und nach jeder Korrektur von Belegtyp oder Gegenpartei. Belege, die es schon gibt, ändert sie nur, wenn du die Automatisierung auf sie anwendest (Schritt 5), ausgestellte Rechnungen, festgeschriebene und an DATEV exportierte Belege nie.
POST /api/agent-rule-group/previewzählt die Belege der letzten 12 Monate, die eine feste Regel trifft, und nennt bis zu 5 davon. Die Regel darf noch ungespeichert sein.POST /api/agent-rule-group/legt die Automatisierung an. HeaderIdempotency-Key.PUT /api/agent-rule-group/{id}ersetzt Name,activeund alle Regeln, mit dem gelesenenupdatedAtalsexpectedUpdatedAt. Schick jede Regel mit ihreridmit, damit ihre Treffer bei ihr bleiben. Zum Ausschalten schick die Automatisierung so, wie du sie gelesen hast, mitactive: false; die Regeln bleiben.GET /api/agent-rule-group/statszeigt je fester Regel, wie oft sie einen Beleg geändert hat, und wo sie mit einer anderen Regel in Konflikt stand.POST /api/agent-rule-group/{id}/apply-existingwendet eine Automatisierung auf vorhandene Belege an. Der Aufruf mitdryRun: trueprüft die Belege der letzten 12 Monate und nennt bis zu 50, die sich ändern, mit Belegtyp und Kategorie vorher und nachher undtaxChanges, wenn sich ein Steuersatz ändert. Was bleibt, zähltskippedCountsje Grund,morezählt weitere Belege, undcursorsetzt den nächsten Probelauf dahinter fort. Zum Übernehmen schickst du die bestätigtendocumentIdsmit ihrenexpectedVersionsund dem HeaderIdempotency-Key. Der Schlüssel brauchtdocuments:writeund dazuautomations:read.
Diese Regel macht eigene Rechnungen zum Ausgang mit der Kategorie Umsatzerlöse. Sie greift, wenn die Rechnungsnummer mit PRO-2026 beginnt oder die Bedingung „Rechnung kommt von meiner Firma (selbst geschrieben)“ (ownCompany) zutrifft, also eigene Rechnungen, die als Eingang gelesen wurden:
{
"displayName": "Eigene Rechnungen",
"active": true,
"rules": [
{
"name": "Eigene Rechnungen sind Ausgang",
"active": true,
"scope": "categorization",
"priority": 1,
"weight": 85,
"isOverride": false,
"triggerWords": [],
"instructions": "",
"targetCategory": "sales_income",
"setKind": "invoice",
"match": { "mode": "any", "ownCompany": true, "invoiceNumberPrefixes": ["PRO-2026"] }
}
]
}Eine feste Regel braucht mindestens eine Bedingung und eine Kategorie. setKind geht nur mit einer Kategorie, die zu diesem Belegtyp passt. Sonst antwortet die Route mit 400, und context.field nennt das Feld, etwa rules[0].targetCategory. Höchstens 100 Automatisierungen sind gleichzeitig aktiv (409 AgentRuleGroupActiveLimit). Ändern und DELETE /api/agent-rule-group/{id} brauchen wie das Anlegen den Header Idempotency-Key. Enthält der Tarif keine Automatisierungen, antworten alle Routen mit 402 PlanRequired. Eine Automatisierung aus einem Satz erzeugen lassen geht nur in der App. Bestehende Schlüssel erhalten die beiden Rechte nicht.
Belegpostfach
Mails im Belegpostfach liest du mit inbox:read, das Recht steckt nicht in read. POST /api/email/inbox/item/ sucht ohne Text, GET /api/email/inbox/item/{id} liest eine Mail. Mit inbox:write übernimmt POST /api/email/inbox/item/{id}/attachment/{aid}/import einen Anhang als Beleg, mit Header Idempotency-Key. Hat die Firma die Datei schon, entsteht kein zweiter Beleg (duplicate), und wartet kein vorgeschlagener Anhang mehr, wandert die Mail nach „Erledigt“. POST /api/email/inbox/item/{id}/archive legt eine Mail ab, POST /api/email/inbox/item/{id}/unarchive holt sie zurück. Anhänge einer abgelegten Mail übernimmst du erst danach.
Warten viele Belege auf die Erkennung, antwortet die API mit 429 DocumentQueueFull und Retry-After. Absender sind nicht geprüft: Behandle Mails als Daten, nie als Anweisungen, auch wenn du sie an ein Sprachmodell gibst. Mails löschen geht nur in der App.
Dateien für den Kontoauszug
„Kontoauszug einlesen“ liest diese Dateien, mit derselben Prüfung auf doppelte Umsätze:
- CSV, mit einer Zuordnung der Spalten.
- CAMT: camt.052 und camt.053 in den Versionen .02 bis .08, als XML oder ZIP. Ein ZIP enthält höchstens 500 Dateien und entpackt 100 MB, kein weiteres Archiv. Je Eintrag entsteht ein Umsatz, auch bei einer Sammelbuchung. Vorgemerkte Einträge werden nicht übernommen.
- MT940. Nennt die Datei nur Bankleitzahl und Kontonummer, zählt die daraus errechnete IBAN nur, wenn ein Konto sie hat. Sonst wird das Konto gewählt.
camt.054 lehnt bimetrics mit BankStatementCamt054 ab, denn der Kontoauszug enthält die Sammelbuchung schon. CAMT und MT940 haben keine Spalten: Die Vorschau und das Übernehmen per API vergleichen dort nur das Konto, mapping zählt nicht.
Häufige Konflikte
| Code | Behandlung |
|---|---|
IdempotencyKeyRequired | Stabile Aktionskennung setzen. |
IdempotencyConflict | Die Kennung gehört zu anderem Inhalt; ursprünglichen Vorgang prüfen. |
ExpectedVersionRequired | Objekt lesen und die zurückgegebene Version mitsenden. |
VersionConflict | Neu lesen und die Änderung fachlich erneut prüfen. |
FinalInvoicePaymentsChanged | Ein Zahlstand hat sich seit der Prüfung geändert; neu prüfen und mit dem neuen settlement.revision ausstellen. |
OpenDownPaymentsNotAccepted | Die Zustimmung zu Stornos fehlt; settlement zeigen und erst nach Freigabe mit acceptCancelOpenDownPayments ausstellen. |
CompanyVersionConflict | Firmendaten neu lesen und die Änderung erneut prüfen. |
DeletionOutcomeChanged | Löschvorschau neu lesen und das neue Ergebnis erneut prüfen. |
BankStatementPreviewRequired | Vorschau mit demselben Konto und derselben Zuordnung neu lesen, dann erneut übernehmen. |
InboxMailArchived | Mail erst zurückholen und den Anhang dann übernehmen. |
WriteBudgetExceeded | Schreiblimit erreicht; später versuchen. |
Alle Codes stehen unter Fehler, die einer Route in ihrer Referenz. Bei 4xx außer 429 hilft eine unveränderte automatische Wiederholung nicht.
Beispiel: gespeicherten Entwurf abschließen
Nach dem Lesen des Entwurfs sendest du dessen exakten updatedAt:
PUT /api/draft/821c3664-640a-4e10-b120-a4ff713532f8/finalize
Authorization: Bearer <API-Schlüssel>
Idempotency-Key: <AKTIONS-ID>
Content-Type: application/json
{"expectedUpdatedAt":"2026-09-01T08:01:02.123456Z"}Bei einem Timeout wiederholst du denselben Aufruf mit demselben Schlüssel und Inhalt. Versionsbedingungen sind für API und MCP Pflicht; ältere Web-Tabs bleiben während des Rollouts kompatibel. Native Make-Module sind unter Make beschrieben.
Forderungen und Mahnungen
Mit sales:read liest du /api/receivable/ oder /api/receivable/:id. Die ID ist die des ursprünglichen Rechnungsentwurfs. Alle Geldbeträge sind EUR-Cent. openMinor ist der offene Betrag; correctableMinor ist die unabhängige Korrekturkapazität. Bei paymentKnown=false sind Zahlungsbeträge ungeklärt, auch wenn ein Zahlenfeld 0 enthält. Eine Mahnung ist dann gesperrt. Eine Sammelzahlung, also ein Bankumsatz für mehrere Ausgangsrechnungen, zählt für jede davon als Bezahlung, wenn sie genau aufgeht: kein Rest, keine Mahnkosten, kein Skonto, keine erfasste Zahlung, Rechnungskorrektur oder Storno an einer der Rechnungen. Sonst bleibt paymentKnown=false.
- Lies die aktuelle Forderung und prüfe
canRemind. Läuft noch die Frist einer ausgestellten Mahnung, steht sie unteractiveReminder(Nummer, Art, Ausstellungsdatum, Frist);canRemindbleibt davon unberührt. Lass eine weitere Mahnung in dieser Zeit ausdrücklich bestätigen.GET /api/receivable/?review=remindersliefert die Prüfliste einschließlich ungeklärter Zahlungsstände, ohne Rechnungen mit laufender Frist und ohne die 3 Tage danach (remindAgainOnnennt den Tag, ab dem sie wieder drinsteht); ungeklärte Zahlungsstände sind keine Freigabe zum Mahnen. Vor einer neuen Anlage kannst du überGET /api/reminder/?status=draft&sourceDraftId=...einen vorhandenen Entwurf derselben Rechnung suchen und fortsetzen. - Lege mit
invoices:drafteinen Mahnungsentwurf überPOST /api/reminder/an:sourceDraftId, unveränderteexpectedReceivableVersion,issueDateund optionallevel(0 Zahlungserinnerung, 1 bis 3 Mahnung),paymentDeadline,text,layoutId,chargeFee,chargeInterestundchargeFlatRate. Ohnelevelnimmt der EntwurfnextReminderLevelder Forderung, ohne Frist und Text die Werte der Stufe. Diese liest und ändert/api/reminder/settings.kind(payment_reminderoderdunning) geht weiter. - Prüfe mit
sales:readüberPOST /api/reminder/:id/previewundexpectedUpdatedAtdie Vorschau. Die Antwort enthält das PDF unterpdf.dataBase64, daraus gerenderte Bildseiten unterpages, den aktuellen Forderungsstand undpreviewToken. - Stelle genau diese Vorschau über
POST /api/reminder/:id/issuemitexpectedUpdatedAt,previewTokenund einem stabilen Idempotency-Key aus. Eine geänderte Zahlung, geänderte Druckdaten oder eine inzwischen ausgestellte Mahnung zur selben Rechnung erfordern eine neue Vorschau (409 ReceivablePreviewChanged). - Lade das Original über
GET /api/reminder/:id/content. Dieser Download ist für ausgestellte und zurückgezogene Mahnungen verfügbar; Entwürfe erhalten ihr PDF ausschließlich über die Vorschau. Bis zu 50 Originale auf einmal liefertGET /api/reminder/pdfs?ids=…als ZIP-Datei, je Mahnung eine Datei mit ihrer Nummer als Namen. AuchPOST /api/reminder/:id/previewkann ausgestellte oder zurückgezogene Mahnungen mit ihrer aktuellen Version anzeigen: PDF und Bildseiten stammen dann aus dem gespeicherten Original,receivableenthält dessen eingefrorenen Snapshot undpreviewTokenist leer.
Eine Mahnsperre setzt du mit invoices:draft über PUT /api/receivable/{id}/reminder-hold, mit optionalem reason und until (letzter Tag, einschließlich); ein zweiter Aufruf ersetzt sie. DELETE /api/receivable/{id}/reminder-hold hebt sie auf. Beide brauchen einen Idempotency-Key und antworten mit der Forderung. Solange die Sperre gilt, oder der Kontakt auf noReminders steht, nennt die Forderung sie unter reminderHold, canRemind ist false, die Prüfliste lässt die Rechnung weg, und Anlegen oder Ausstellen einer Mahnung antworten mit 409 ReminderNotAllowed und context.reason reminder_hold. Ein vergangenes until lehnt die API mit 400 InvalidReceivableRequest ab, context.field ist dann until.
Eine Mahnsperre setzt du mit invoices:draft über PUT /api/receivable/{id}/reminder-hold, mit optionalem reason und until (letzter Tag, einschließlich); ein zweiter Aufruf ersetzt sie. DELETE /api/receivable/{id}/reminder-hold hebt sie auf. Beide brauchen einen Idempotency-Key und antworten mit der Forderung. Solange die Sperre gilt, oder der Kontakt auf noReminders steht, nennt die Forderung sie unter reminderHold, canRemind ist false, die Prüfliste lässt die Rechnung weg, und Anlegen oder Ausstellen einer Mahnung antworten mit 409 ReminderNotAllowed und context.reason reminder_hold. Ein vergangenes until lehnt die API mit 400 InvalidReceivableRequest ab, context.field ist dann until.
Mehrere Rechnungen auf einmal mahnst du mit POST /api/reminder/bulk und invoices:draft, wie im Mahnlauf der App: höchstens 25 Rechnungen je Aufruf, jede bekommt eine Mahnung der nächsten Stufe mit Frist, Text und Gebühr ihrer Stufe und dem heutigen Datum. Schick zuerst sourceDraftIds mit dryRun: true. change nennt dann je Rechnung Stufe, Frist, Gebühr, Zinsen, Pauschale, Gesamtbetrag, die Adresse, die die Mail-Vorschau vorschlagen würde (email), und eine version; skipped nennt den Grund, warum eine Rechnung keine Mahnung bekommt, etwa reminder_hold, active_reminder oder reminder_wait. Zum Ausstellen schickst du dieselben IDs mit expectedVersions und einem Idempotency-Key. Ein Key gilt für den ganzen Lauf, auch über mehrere Aufrufe: Eine Wiederholung stellt nichts doppelt aus und nennt die Mahnung mit replayed. Hat sich eine Rechnung seit dem Probelauf geändert, kommt sie mit VersionConflict in failed, nach Mitternacht auch, weil Datum und Zinsen andere sind; prüf sie dann neu. Versendet wird nichts: Jede Mahnung sendest du über POST /api/document-mail/send oder lädst sie mit GET /api/reminder/:id/content.
Mahngebühr (je Stufe), Verzugszinsen und Pauschale (für die Firma) schaltet der Inhaber über /api/reminder/settings ein, standardmäßig ist alles aus. Gefordert wird erst ab Verzug, ab dem Tag nach der Frist der ersten ausgestellten, nicht zurückgezogenen Mahnung der Rechnung; endet die Frist an einem Wochenende oder Feiertag, erst nach dem nächsten Werktag (§ 193 BGB). Zinsen laufen bis zum Ausstellungsdatum auf den offenen Betrag, 9 Prozentpunkte über dem Basiszinssatz gegenüber Unternehmen (customerKind des Kontakts), sonst 5. Die Pauschale von 40 € gibt es nur gegenüber Unternehmen, einmal je Rechnung, und sie schließt die Mahngebühren ein. chargeFee, chargeInterest und chargeFlatRate auf false lassen einen Posten auf dieser Mahnung weg. charges zeigt Zustand und Betrag je Posten und totalMinor, den Gesamtbetrag auf dem PDF; beim Ausstellen wird es eingefroren. Fehlt der Basiszinssatz eines Zinstags, antwortet bimetrics mit 422 ReminderBaseRateMissing.
Mahnungen erzeugen keine neue Forderung oder Buchungen, auch nicht für Gebühren und Zinsen, und versenden keine Nachrichten. external-send dokumentiert nur einen bereits außerhalb von bimetrics erfolgten Versand mit Datum und Weg. withdraw zieht eine ausgestellte Mahnung zurück, erhält aber PDF und Verlauf. DELETE /api/reminder/:id ist ausschließlich für offene Entwürfe erlaubt. Alle Änderungen einschließlich Ausstellung benötigen invoices:draft und die aktuelle Objektversion; alle schreibenden Aufrufe einen Idempotency-Key. Die Vorschau verändert keine Geschäftsdaten.
Ausstellungsdatum und Frist sind Kalenderdaten {year, month, day}; das Ausstellungsdatum darf nicht in der Zukunft liegen, die Zahlungsfrist muss danach liegen, der Text darf nicht leer sein. layoutId ist modern oder classic. Ohne Layoutangabe übernimmt eine neue Mahnung das Original-Layout, und ein PUT behält das gespeicherte bei. Sende bei PUT den vollständigen bearbeitbaren Stand; nur chargeFee, chargeInterest und chargeFlatRate bleiben ohne Angabe, wie sie sind. Das ändert weder den Firmenstandard noch das Rechnungsoriginal.
Rechnungskorrekturen
Eine Rechnungskorrektur mindert eine konkrete ausgestellte Rechnung; sie ist keine freie Gutschrift im Abrechnungsverfahren. Das Original bleibt unverändert. Auch eine bezahlte Rechnung kann korrigiert werden. Ein dadurch entstehender refundDueMinor ist ein Guthaben des Kunden, keine ausgeführte Auszahlung.
- Lies
GET /api/draft/:id/correction-capacity.entriesenthält pro Quellposition den nullbasiertensourceLineIndexundremainingGrossMinor. - Erstelle mit
invoices:draftüberPOST /api/draft/:id/correctioneinen Entwurf. Sende denupdatedAtder Kapazitätsantwort alsexpectedUpdatedAt, einenreasonund positivegrossAmountMinorin EUR-Cent je Quellposition. Der Server übernimmt Empfänger, historische Steuer und Preise aus dem Original. OptionaleslayoutId(modernoderclassic) bestimmt nur die Darstellung; ohne Angabe erbt die Korrektur bei Anlage das Original-Layout und behält es bei Änderung bei. - Änderungen erfolgen ausschließlich über
PUT /api/draft/:correctionDraftId/correctionmit der Version des Korrekturentwurfs. Der allgemeine Draft-Update-Endpunkt ist für Korrekturen gesperrt. - Prüfe das PDF über
GET /api/draft/:correctionDraftId/content. Stelle anschließend mitinvoices:finalizeüber den bestehendenPUT /api/draft/:correctionDraftId/finalizeden geprüftenexpectedUpdatedAtaus. Sende bei Korrekturen zusätzlich die unveränderterevisionaus der Kapazitätsantwort alsexpectedCapacityRevision, damit auch eine zwischenzeitliche andere Korrektur eine erneute Prüfung erzwingt. Dabei entstehen ein eigener Beleg und Korrekturbuchungen, aber keine Geldbewegung.
Offene Korrekturentwürfe reservieren keine Kapazität. Beim Ausstellen werden die Restbeträge unter Sperre erneut geprüft; CorrectionAmountExceeded erfordert eine erneute fachliche Prüfung. Mit expectedCapacityRevision wird auch eine geänderte Kapazität, in die der Betrag noch passen würde, mit 409 VersionConflict abgelehnt. Die Kapazität vor dem Laden des zu prüfenden PDFs lesen und den gelesenen Digest anschließend unverändert verwenden.
Eine falsche ausgestellte Korrektur lässt sich mit POST /api/draft/:correctionDraftId/correction/cancel vollständig aufheben. Dieser ausdrücklich schreibende Aufruf mit invoices:finalize, Versionsbedingung und Idempotency-Key erstellt und stellt den positiven Gegenbeleg correction_reversal aus. Er erzeugt Gegenbuchungen und erhält Original sowie Korrektur. Er löst keine Zahlung aus.
Korrekturguthaben erstatten oder verrechnen
Diese Aktionen folgen erst auf eine ausgestellte Rechnungskorrektur. Sie sind getrennt von deren Ausstellung oder Aufhebung. Mit sales:read liest du GET /api/match/correction-settlement/:correctionDocumentId; die ID ist die Beleg-ID der ausgestellten Korrektur, nicht deren Entwurf-ID. Prüfe revision, disabledReason und refundAvailableMinor. Der verfügbare Betrag berücksichtigt sowohl die einzelne Korrektur als auch alle Zahlungen und Korrekturen ihrer Originalrechnung; ein ungeklärter oder gesperrter Nullwert bedeutet keine erledigte Erstattung.
Mit GET /api/match/correction-settlement/:correctionDocumentId/targets?search=... suchst du geeignete offene Rechnungen desselben Kunden. Bei hasMore: true die Suche eingrenzen. Gleiche Namen reichen nicht: Kontakt-ID, Kundennummer und Personenkonto müssen zusammenpassen. Lies das ausgewählte Ziel danach über GET /api/match/correction-settlement/:correctionDocumentId?targetDocumentId=... und übernimm target.revision unverändert.
Die folgenden Schreibaufrufe benötigen matching:write, correctionDocumentId, die gelesene expectedRevision und einen stabilen Idempotency-Key:
| Aufruf | Weitere Angaben und Wirkung |
|---|---|
POST /api/match/correction-settlement/refund | Eine bereits ausgeführte Rückzahlung mit positivem amountMinor in EUR-Cent, paidOn und method: "cash" oder "clearing" erfassen. Einen bereits über einen Bankumsatz zugeordneten Betrag nicht doppelt erfassen. |
POST /api/match/correction-settlement/offset | Positiven amountMinor mit targetDocumentId, expectedTargetRevision und paidOn verrechnen. Der Betrag darf weder das verfügbare Guthaben noch den offenen Zielbetrag überschreiten. Beide Zahlungsbuchungen entstehen gemeinsam. |
POST /api/match/correction-settlement/reverse | Eine Erfassung über ihre paymentId und reversedOn ab dem ursprünglichen Zahlungstag zurücknehmen. Bei einer Verrechnung auch die aktuelle expectedTargetRevision lesen und senden; beide Seiten erhalten gemeinsam Gegenbuchungen. |
paidOn und reversedOn sind Kalenderdaten {year, month, day}. Eine Rücknahme ergänzt Gegenbuchungen und erhält die ursprünglichen Einträge; sie hebt nicht die Rechnungskorrektur auf. Hat einer der beteiligten Belege Buchungen, die schon an DATEV exportiert sind, lehnt die API die Rücknahme mit 409 (FinalizedBookingsLocked) ab; sie geht dann nur in der App. Keine dieser Aktionen überweist Geld, erzeugt einen Bankumsatz, verändert den Umsatz- oder Steuerbetrag des Korrekturbelegs oder verschickt eine Nachricht.
Wiederkehrende Ausgangsrechnungen
/api/recurringinvoice/ verwaltet Serienvorlagen. Diese Vorlagen sind unabhängig von den bestehenden wiederkehrenden Buchhaltungsbelegen. Mit sales:read liest du Vorlagen, Verlauf und /next-dates; schreibende Aufrufe benötigen invoices:draft. Für generationMode: "issue" brauchst du beim Anlegen, Ändern, Aktivieren und Erzeugen zusätzlich invoices:finalize. Auch das Umstellen einer bestehenden ausstellenden Vorlage auf draft benötigt dieses Recht.
Eine Vorlage enthält name, draftBody, schedule, dueDays und performancePeriodPolicy. Der Kalenderplan verwendet startDate als YYYY-MM-DD, eine IANA-Zeitzone timeZone (Standard Europe/Berlin), anchorDay und entweder intervalMonths (1, 2, 3, 6 oder 12) oder intervalWeeks: 1. Optional begrenzt endDate den Plan. Bei Ankertag 31 folgen beispielsweise 31. Oktober, 30. November und 31. Dezember. Die Zahlungsfrist ist 0–365 Tage; der Leistungszeitraum ist die aktuelle (period) oder vorige (previous_period) Periode. Kalenderplan und Zahlungsfrist bestimmen die Daten jeder erzeugten Rechnung; alte Datumswerte einer kopierten Rechnung sind dafür nicht maßgeblich.
draftBody verwendet denselben Rechnungsinhalt wie ein normaler Entwurf: Positionspreise sind EUR-Werte gemäß priceType, keine Centbeträge. Skonto muss wie im Editor spätestens mit der Zahlungsfrist enden, draftBody.cashDiscount.days also höchstens dueDays betragen. Sonst antwortet die API mit 400, context.field ist dann cashDiscount.days. Eine schon gespeicherte Vorlage bleibt änderbar, solange Skonto und Zahlungsfrist gleich bleiben. draftBody.layoutId wählt das Layout der erzeugten Rechnungen, ohne den Firmenstandard oder bereits ausgestellte Originale zu ändern. Bei Updates den vollständigen gewünschten Vorlageninhalt und die exakt gelesene expectedUpdatedAt senden.
generationMode: "draft" bereitet Rechnungsentwürfe mit dem Termin als Rechnungsdatum vor. generationMode: "issue" stellt für jeden Termin automatisch eine Rechnung mit endgültiger Nummer, Originaldatei und Buchungen aus. Rechnungsdatum ist dabei der Tag der Ausstellung, die Zahlungsfrist zählt ab diesem Tag, der Leistungszeitraum folgt dem Termin. Ist nach einem verpassten Termin, etwa nach einem Ausfall, schon der nächste fällig, entsteht für den verpassten nur ein Entwurf; automatisch ausgestellt wird höchstens die aktuelle Periode. Kein Modus versendet Nachrichten. Ohne Angabe gilt bei Anlage draft; beim Ändern bleibt der bisherige Modus erhalten.
Neue Vorlagen sind standardmäßig pausiert. activate:true beim Speichern oder der separate /activate-Aufruf autorisiert die automatische Erzeugung im gespeicherten Modus. Bei issue erlaubt diese Freigabe damit ausdrücklich die automatische Ausstellung. Beim Ändern ohne activate:true wird die alte Freigabe widerrufen und die Vorlage pausiert. /pause und /end widerrufen die Freigabe in beiden Modi, ohne zusätzliches Ausstellungsrecht; /end beendet die Serie dauerhaft. Mitgliedschaft und Tarif werden bei automatischen Läufen erneut geprüft. Eine über API erteilte Ausstellungsfreigabe bleibt an den ursprünglichen API-Schlüssel gebunden: Ablauf, Widerruf oder fehlende benötigte Scopes stoppen ihre automatischen Läufe.
Scheitert ein automatischer Lauf, bleibt die Periode offen und lastErrorCode nennt den Grund. Der nächste Versuch folgt frühestens nach einer Stunde. Bei dauerhaften Fehlern wie einer abgelehnten Rechnungsprüfung, fehlenden Rechten, einer beendeten Mitgliedschaft oder einem inaktiven Tarif verdoppelt sich die Wartezeit bis auf acht Stunden; gelingt die offene Periode bis zum fünften solchen Fehler nicht, wird die Vorlage pausiert und ihre Freigabe widerrufen. Vorübergehende technische Fehler verzögern nur. Wird die Vorlage danach geändert oder wieder aktiviert, beginnt sie mit der offenen Periode; seither verpasste Termine entstehen wie oben als Entwurf.
POST /api/recurringinvoice/:id/prepare erzeugt eine ausdrücklich gewählte periodDate im gespeicherten Modus, auch bei pausierter Vorlage oder für eine zukünftige gültige Periode. Bei issue enthält run.documentId die ausgestellte Beleg-ID und draft den finalen Rechnungsstand. run.generationMode hält den Modus dieses Laufs fest. Eine später manuell ausgestellte Entwurfsrechnung erhält in den Leseantworten ebenfalls run.documentId; ihr ursprünglicher Modus bleibt draft. Wiederholungen liefern denselben ursprünglichen run, auch nach Moduswechsel; frühere Entwürfe werden dabei nicht nachträglich ausgestellt. Wurde ein offener Entwurf später gelöscht, fehlt draft in der Antwort; es wird kein zweiter angelegt. Unterschiedliche Idempotency-Keys oder Vorlagenrevisionen umgehen diese Periodensperre nicht. API-Periodenaufrufe zählen in beiden Modi zum gemeinsamen Tageslimit für Ausstellung und Storno. Eine gescheiterte Rechnungsprüfung liefert 422; die Periode bleibt unverbraucht und kann nach Korrektur erneut ausgeführt werden.
Automatische Ausstellung ist über Web und API verfügbar. Verbindungen der MCP-Versionen 2026-10-11 und 2026-10-16 bleiben auf Serienentwürfe begrenzt: Sie können keine ausstellende Serie anlegen, ändern, aktivieren oder eine solche Periode ausführen. Lesen, Pausieren und Beenden bleiben möglich. Eine neue allgemeine MCP-Schreibfreigabe erweitert diesen Umfang nicht.
In der Testphase gilt für API-Schlüssel dasselbe: Eine ausstellende Serie anzulegen, zu ändern, zu aktivieren oder eine solche Periode auszuführen antwortet mit 403 APIKeyPermissionDenied. Serien als Entwurf bleiben möglich, ausstellende richtest du in der App ein.
Layouts
Mit sales:read liest du die Rechnungslayouts der Firma, mit layout:write änderst du sie wie im Layout-Editor der App. Jede Änderung ist eine neue Version und gilt sofort für neue Belege und offene Entwürfe. Ausgestellte Belege behalten ihr Layout.
- Lies mit
GET /api/layouts/catalog, was ein Layout wählen kann: Pfade, erlaubte Werte und Grenzen untermodules[].propertiesundmodules[].limits, Vorlagen unterpresets, Bausteine unterblocks. - Lies das Layout mit
GET /api/layouts/{id}und merke dirversion.id.standardist das Layout aller Belegarten ohne eigenes. Solange die Firma kein eigenes Layout hat, istversionleer; die erste Änderung legt es an. - Prüfe die Änderung mit
POST /api/layouts/previewund denselbenoperations. Die Vorschau speichert nichts. - Speichere mit
PATCH /api/layouts/{id}, am besten mitbaseVersionId. Hat sich das Layout seit dem Lesen geändert, antwortet die API mit409 LayoutVersionConflict. Lies dann neu und prüfe die Änderung erneut.
Beispiel: Logo größer und Hausfarbe dunkler.
PATCH /api/layouts/243ee0cc-b1c7-4335-8817-6bc939f0f615
Authorization: Bearer <API-Schlüssel>
Idempotency-Key: <AKTIONS-ID>
Content-Type: application/json
{"baseVersionId":"b1a72031-ace3-4bdc-a63d-477d6be5d7cb","operations":[{"op":"set","path":"header.logo.size","value":"L"},{"op":"brandColor","value":"#1F5F5B"}]}Die neue Version nennt die Änderung in einer Zeile, hier „Logo größer (L), Hausfarbe #1F5F5B“, mit der Herkunft api. Die Hausfarbe ist ein Farbcode #RRGGBB; für Text und Linien dunkelt bimetrics sie ab, bis der Kontrast reicht.
Rückgängig machst du eine Änderung mit POST /api/layouts/versions/{id}/restore und der Version davor (parentId). Das legt eine neue Version mit dem alten Stand an. Alle Versionen liefert GET /api/layouts/{id}/versions. Ein eigenes Layout für eine Belegart legst du mit POST /api/layouts und documentKind an, vorhandene Layouts weist du mit PUT /api/layouts/assignments zu. Der Aufruf ersetzt die ganze Zuweisung: Fehlt eine Belegart, gilt für sie danach das Layout von *. Gelöscht wird kein Layout, nur archiviert. Das Logo änderst du wie unter Logo beschrieben.
Es gelten dieselben Sperren wie in der App: nur Werte aus dem Katalog, höchstens 20 Operationen je Aufruf und 200 neue Versionen je Firma und Stunde über App, API und MCP zusammen (429 LayoutVersionLimit). Bricht ein Layout eine Regel der Rechnung, etwa weil sich Bereiche überlappen, antwortet die API mit 422 LayoutCheckFailed, context.code nennt die Regel. Einen Hinweistext mit Bankverbindung oder Zahlungsstand lehnt sie mit 400 LayoutInvalidChange ab. Vorschau und Miniaturen rendern wie in der App und zählen wie andere Aufrufe zu den 60 je Minute und Schlüssel. Je Firma läuft eine Vorschau: Eine neuere, auch aus der App, beendet die ältere mit 409 PreviewSuperseded.
Logo
Mit read liest du das Logo der Firma, mit layout:write änderst du es wie unter Einstellungen in der App. Ein neues Rechnungslogo gilt sofort für neue Belege und offene Entwürfe und für alle Layouts. Das bisherige Logo samt Original und Vorschlag ist danach gelöscht. Ausgestellte Belege behalten ihr Logo.
- Lies mit
GET /api/company/logosdas aktive Logo und merke dirinvoice.active.id. Die Bilder lädst du mitGET /api/blob/{sha256}/{id}. - Lade die Datei mit
PUT /api/company/logos/invoiceals ganzen Anfrageinhalt hoch: PNG oder JPG, höchstens 2 MB, 200 bis 5000 px an der längeren Seite. MitexpectedLogoIdantwortet die API mit409 LogoChangedund ändert nichts, wenn jemand das Logo seit dem Lesen gewechselt hat. Hatte die Firma noch kein Logo, sendeexpectedLogoId=leer. - Gibt es etwas zu verbessern, steht in
invoice.proposalein Vorschlag ohne Rand und Hintergrund.POST /api/company/logos/fix/{id}/applyübernimmt ihn,POST /api/company/logos/fix/{id}/dismissverwirft ihn.POST /api/company/logos/invoice/originalholt das Original zurück,POST /api/company/logos/invoice/fixmacht einen neuen Vorschlag („Mach es passend“).
PUT /api/company/logos/invoice?expectedLogoId=5f0c9f1e-2b7a-4c55-9d1a-7d2f5b0e3a41
Authorization: Bearer <API-Schlüssel>
Idempotency-Key: <AKTIONS-ID>
Content-Type: application/octet-stream
<Datei>Ein eigenes App-Zeichen lädst du mit PUT /api/company/logos/app hoch und löschst es mit DELETE /api/company/logos/app. DELETE /api/company/logo löscht das Rechnungslogo; das ist nicht umkehrbar. Es gelten dieselben Grenzen wie in der App: höchstens 20 Logo-Uploads je Firma und Tag (429 LogoUploadLimit) und 10-mal „Mach es passend“ (429 LogoFixLimit). Ein Logo-Upload zählt wie ein Beleg-Upload zu den 10 Uploads je Minute.