Daten schreiben (POST / PUT / DELETE) – aifinyo | Billomat

Mit POST erstellst du neue Datensätze, mit PUT bearbeitest du bestehende – und mit DELETE entfernst du sie dauerhaft.

Die drei Schreib-Methoden im Überblick

Während GET ausschließlich liest, verändern diese drei Methoden tatsächlich Daten in deinem Account. Geh damit entsprechend sorgfältig um – besonders mit DELETE.

Methode	Was sie tut	Antwort bei Erfolg	Rückgängig machbar?
`POST`	Neuen Datensatz erstellen	`201 Created`	✅ Ja – Datensatz kann wieder gelöscht werden
`PUT`	Bestehenden Datensatz bearbeiten	`200 OK`	⚠️ Bedingt – vorherige Werte sind überschrieben
`DELETE`	Datensatz löschen	`200 OK`	🚨 Nein – Löschung ist dauerhaft

Wichtig: Teste schreibende Requests immer zuerst in einer sicheren Umgebung – z.B. mit einem Entwickler-Account oder an Testdaten. Ein versehentlich gelöschter Datensatz kann nicht wiederhergestellt werden.

POST – Neuen Datensatz erstellen

Mit POST legst du einen neuen Datensatz an. Die Daten, die du erstellen möchtest, schickst du im Request-Body mit – entweder als XML oder JSON (je nach gesetztem Content-Type-Header).

Die API antwortet bei Erfolg mit 201 Created und gibt den vollständigen neu erstellten Datensatz zurück – inklusive der von Billomat vergebenen ID.

Beispiel: Neuen Kunden anlegen

Mit XML:

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/xml' \
  -d '<client><name>Musterfirma GmbH</name></client>' \
  https://{deineBillomatID}.billomat.net/api/clients

Mit JSON:

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{"client":{"name":"Musterfirma GmbH"}}' \
  https://{deineBillomatID}.billomat.net/api/clients

Die Antwort enthält den neuen Datensatz mit der vergebenen ID:

<client>
  <id>789</id>
  <name>Musterfirma GmbH</name>
  ...
</client>

Tipp: Die zurückgegebene ID solltest du in deiner Anwendung direkt speichern – sie ist der eindeutige Schlüssel, über den du den Datensatz später abrufen, bearbeiten oder löschen kannst.

PUT – Bestehenden Datensatz bearbeiten

Mit PUT änderst du einen vorhandenen Datensatz. Die ID des zu ändernden Datensatzes gehört direkt in die URL. Im Request-Body schickst du nur die Felder mit, die du ändern möchtest – nicht geänderte Felder bleiben unberührt.

Die API antwortet bei Erfolg mit 200 OK und gibt den vollständigen aktualisierten Datensatz zurück.

Beispiel: Name eines Kunden ändern

curl -X PUT \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/xml' \
  -d '<client><name>Neue Musterfirma GmbH</name></client>' \
  https://{deineBillomatID}.billomat.net/api/clients/789

Hinweis: Manche Datensätze können nur in bestimmten Status bearbeitet werden. Eine abgeschlossene Rechnung (Status OPEN oder höher) lässt sich z.B. nicht mehr per PUT ändern – sie muss erst storniert werden. Die jeweiligen Einschränkungen sind in den Ressourcen-Artikeln beschrieben.

DELETE – Datensatz löschen

Mit DELETE entfernst du einen Datensatz dauerhaft. Es wird kein Request-Body benötigt – die ID in der URL reicht. Die API antwortet bei Erfolg mit 200 OK.

Beispiel: Rechnungsentwurf löschen

curl -X DELETE \
-H 'X-BillomatApiKey: {dein-api-schluessel}' \
https://{deineBillomatID}.billomat.net/api/invoices/12345

Achtung: Das Löschen ist endgültig und kann nicht rückgängig gemacht werden. Beim Löschen einer Rechnung werden auch alle zugehörigen Positionen, Kommentare, Zahlungen und PDFs unwiderruflich entfernt. Bitte mit Bedacht einsetzen.

Spezielle Aktionen mit PUT

Neben dem einfachen Bearbeiten gibt es bei vielen Ressourcen spezielle Aktionen, die ebenfalls per PUT ausgelöst werden. Diese haben eine eigene URL-Endung:

Aktion	URL	Bedeutung
Rechnung abschließen	`/api/invoices/123/complete`	Entwurf → OPEN, PDF wird erzeugt
Rechnung stornieren	`/api/invoices/123/cancel`	Status → CANCELED
Angebot annehmen	`/api/offers/123/win`	Status → WON

Beispiel: Rechnung abschließen

curl -X PUT \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/xml' \
  -d '<complete><template_id>42</template_id></complete>' \
  https://{deineBillomatID}.billomat.net/api/invoices/12345/complete

Hinweis zur Rechnungsnummer: Solange eine Rechnung im Status DRAFT ist, hat sie noch keine endgültige Rechnungsnummer. Diese wird erst beim Abschließen (/complete) automatisch vergeben. Mehr dazu im Artikel Ressource: Rechnungen.

Nächste Schritte

Jetzt kennst du alle vier HTTP-Methoden. Als nächstes lernst du zwei weitere nützliche Konzepte kennen:

Eigene Meta-Daten (customfield) – eigene Daten an Billomat-Objekten speichern
Fehlerbehandlung & HTTP-Statuscodes – was zu tun ist, wenn etwas schiefgeht

Verknüpfung mit