Kunden-Upsert
Ob die API nur eine Rechnung erzeugt oder zusätzlich einen Stammkunden anlegt/aktualisiert,
steuert allein das Feld recipient.customerNumber. Der Abgleich läuft ausschließlich über die
Kundennummer – nie über Name oder E-Mail (das würde Dubletten erzeugen).
Die drei Fälle
1. Keine Kundennummer → nur Rechnung
Ohne recipient.customerNumber wird kein Stammkunde angelegt. Der Empfänger erscheint als
Snapshot auf der Rechnung (das genügt für eine gültige Rechnung nach § 14 UStG). Die Antwort:
"customer": null2. Kundennummer neu → Kunde angelegt
Ist die Nummer im Konto noch nicht vergeben, wird ein neuer Stammkunde aus den recipient-Feldern
angelegt. Die Antwort bestätigt das:
"customer": { "number": "K-100", "apiCreated": true, "apiUpdated": false }Integrations-Anforderung: Ihre App muss sich die Kundennummer pro Endkunde merken. Vergeben Sie
pro Endkunde einmal eine stabile customerNumber (z. B. Ihre eigene Kunden-ID) und verwenden Sie
sie ab dann immer wieder. Andernfalls – etwa mit einer neuen Zufallsnummer je Rechnung – legt die API
bei jeder Rechnung einen neuen Kunden an, und der Kundenstamm läuft mit Dubletten voll.
3. Kundennummer existiert → partielles Update
Ist die Nummer bereits vergeben, werden nur die mitgelieferten Felder aktualisiert – fehlende Felder bleiben unverändert (sie werden nicht geleert). So können Sie z. B. nur eine geänderte Anschrift senden, ohne die hinterlegte E-Mail zu verlieren.
"customer": { "number": "K-100", "apiCreated": false, "apiUpdated": true }Zusammengefasst
customerNumber | Wirkung | Antwort customer |
|---|---|---|
| nicht gesetzt | nur Rechnung (Empfänger als Snapshot) | null |
| neu | Stammkunde angelegt | { number, apiCreated: true, apiUpdated: false } |
| existiert | partielles Update (fehlende Felder bleiben) | { number, apiCreated: false, apiUpdated: true } |
Der Kunden-Upsert und das Festschreiben laufen in einer Transaktion: Scheitert die Rechnung, wird auch der Kunde nicht angelegt/geändert. Es gibt kein Zwischenfenster.