Rechnungsvorschau, Zahlungserfassung und Gutschrift per API

Rückblick - Mai bis August 2026
Dieser Artikel wurde nachträglich verfasst und beschreibt die separaten Rechnungsaktionen, die über die API verfügbar gemacht wurden.

Eine Integration muss zwischen dem Lesen einer Rechnung, dem Erfassen einer Aktion und dem Geldtransfer unterscheiden. Beginnen Sie beim Prüfen von Positionen und Beträgen mit einer Vorschau und erstellen oder laden Sie anschließend die Rechnung, wie es der aktuelle Vertrag vorsieht.

Ein Testablauf

1. Prüfen Sie über den Vorschau-Endpunkt des Kunden für Rechnungen Zeiträume, Positionen und Gesamtbetrag.
2. Laden Sie bei Bedarf die PDF-Vorschau zur internen Freigabe herunter.
3. Erstellen oder lesen Sie die Rechnung und verwenden Sie ihre UUID für spätere Aufrufe.
4. Verwenden Sie mark-as-sent, wenn Ihr Ablauf das Dokument zugestellt oder registriert hat. Der Aufruf versendet keine E-Mail; er erfasst die Zustellung über einen externen Kanal und unterdrückt eine noch ausstehende automatische Rechnungs-E-Mail.
5. Verwenden Sie mark-as-paid, wenn eine Zahlung manuell erfasst werden soll. Dadurch wird kein neuer Karteneinzug ausgelöst.
6. Verwenden Sie den Gutschrift-Endpunkt, wenn einzelne Rechnungspositionen gutgeschrieben werden sollen. Eine Gutschrift ist eine eigene Aktion und nicht dasselbe wie das Löschen der Rechnung.

Eine Erstattung kann noch ausstehen, obwohl die Anfrage angenommen wurde. Prüfen Sie die Antwort und späteren Status, bevor Sie den Betrag als zurückerstattet anzeigen.

Fehler und Erwartungen

Vorschau, PDF, Versand, Zahlung und Gutschrift haben unterschiedliche Antworten und Status. Verwenden Sie für Schemas und zulässige Felder die aktuelle OpenAPI-Referenz. Verwenden Sie in Testcode keine echten Tokens oder Kundeninformationen, sondern synthetische UUIDs.

Die Anleitung zu öffentlicher API und Webhooks (Markdown-fil, AI-agentvenlig) beschreibt den aktuellen Vertrag.

Versendet mark-as-sent eine E-Mail? Niemals. Der Aufruf erfasst, dass ein externer Kanal die Rechnung zugestellt hat, und unterdrückt eine noch ausstehende automatische Rechnungs-E-Mail. Soll Alunta die E-Mail senden, verwenden Sie die separate Versandaktion.

Bewegt mark-as-paid Geld? Nein. Der Aufruf erfasst eine manuelle Zahlung und löst keinen neuen Karteneinzug aus.

Ist eine Teilgutschrift möglich? Ja. Verwenden Sie die dokumentierte Aktion zum Gutschreiben einzelner Positionen und lesen Sie den Status erneut aus, bevor Sie den Vorgang als abgeschlossen anzeigen.

Statuswerte in Ihrer Integration getrennt behandeln

Eine Vorschau kann dem Benutzer zeigen, was in Rechnung gestellt wird, bevor ein endgültiges Dokument existiert. Ein PDF liefert dieselben Informationen in einem Format, das freigegeben oder archiviert werden kann. Sobald die Rechnung existiert, erfasst mark-as-sent den Arbeitsablauf. Muss Ihre Integration das Dokument außerdem versenden, sollte sie die dokumentierte Versandaktion verwenden und deren Antwort separat verarbeiten.

Auch mark-as-paid erfasst eine manuelle Zahlung. Verwenden Sie diese Aktion nur, wenn ein Benutzer oder eine abgestimmte externe Quelle die Zahlung bestätigt hat. Leiten Sie aus einer erfolgreichen Vorschau oder einem Versandstatus keine Zahlung ab. Die Gutschrift ausgewählter Positionen ändert die Forderung über eine Gutschrift; sie löscht weder die ursprüngliche Rechnung noch erstattet sie automatisch Bargeld. mark-as-sent versendet nie eine E-Mail, auch nicht nach Fertigstellung der Rechnung; der Aufruf blockiert die ausstehende automatische Zustellung.

Verwenden Sie die Rechnungs-UUID für Folgeaufrufe und lesen Sie nach jeder Aktion den aktuellen Status aus. Ist die Antwort noch ausstehend, zeigen Sie weiterhin „ausstehend“ statt „abgeschlossen“ an. So kann der Benutzer das nächste Ergebnis der Integration prüfen, ohne eine bereits erfasste Aktion zu wiederholen.