Eigene Meta-Daten (customfield) – aifinyo | Billomat

Mit dem customfield kannst du an jedem Billomat-Objekt eigene Daten hinterlegen – zum Beispiel die ID aus deinem eigenen System.

Was ist das customfield?

Das customfield ist ein freies Textfeld, das an den wichtigsten Billomat-Ressourcen verfügbar ist – z.B. an Kunden, Rechnungen, Artikeln oder Eingangsrechnungen. Du kannst dort beliebige Daten speichern, die Billomat selbst nicht kennt.

Der häufigste Anwendungsfall: Du synchronisierst Billomat mit einem externen System – z.B. einem Shop, CRM oder ERP. Jedes Objekt in deinem System hat eine eigene ID. Diese ID hinterlegst du im customfield, damit du bei jeder API-Anfrage sofort weißt, welcher Billomat-Datensatz zu welchem Datensatz in deinem System gehört.

Beispiel:

Dein Shop-System hat den Kunden Musterfirma GmbH mit der internen ID SHOP-4711. Diese ID hinterlegst du im customfield des entsprechenden Billomat-Kunden. Beim nächsten Abgleich findest du den richtigen Billomat-Datensatz sofort über diese ID – ohne aufwendige Namenssuche.

Bei welchen Ressourcen ist das customfield verfügbar?

Das customfield steht u.a. bei folgenden Ressourcen zur Verfügung:

Kunden (clients)
Rechnungen (invoices)
Artikel (articles)
Angebote (offers)
Eingangsrechnungen (incomings)
Lieferanten (suppliers)
Kontakte (contacts)

customfield auslesen

Das customfield eines Datensatzes rufst du über einen eigenen Endpunkt ab:

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
https://{deineBillomatID}.billomat.net/api/clients/789/customfield

Die Antwort sieht so aus:

<?xml version="1.0" encoding="UTF-8"?>
<client>
<id type="integer">789</id>
<customfield>SHOP-4711</customfield>
</client>

customfield schreiben

Das customfield setzt oder aktualisierst du per PUT – ebenfalls über den eigenen Endpunkt:

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

Tipp: Du kannst das customfield auch direkt beim Erstellen eines Datensatzes per POST mitgeben – so sparst du dir einen zweiten API-Aufruf:

-d '<client><name>Musterfirma GmbH</name><customfield>SHOP-4711</customfield></client>'

Nach customfield-Wert suchen

Du kannst Datensätze gezielt nach ihrem customfield-Wert filtern. Das ist besonders praktisch beim Abgleich zwischen zwei Systemen:

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
https://{deineBillomatID}.billomat.net/api/clients?customfield=SHOP-4711

Gibt es einen Kunden mit diesem customfield-Wert, wird er zurückgegeben. Gibt es keinen, erhältst du eine leere Liste – du weißt dann, dass der Datensatz in Billomat noch nicht existiert und neu angelegt werden muss.

Typisches Synchronisierungsmuster:

Datensatz im eigenen System hat die ID SHOP-4711.
Suche in Billomat: ?customfield=SHOP-4711
Treffer: Datensatz existiert bereits → per PUT aktualisieren.
Kein Treffer: Datensatz existiert noch nicht → per POST neu anlegen und customfield direkt mitgeben.

customfield leeren

Um das customfield zu leeren, schickst du einfach einen PUT-Request mit einem leeren Wert:

-d '<client><customfield></customfield></client>'

Was du noch wissen solltest

Das customfield ist ein reines Textfeld – du kannst jeden beliebigen String speichern, also IDs, JSON-Strings, kurze Notizen etc.
Der Wert ist nur über die API sichtbar – er erscheint nicht in der Billomat-Oberfläche oder auf Dokumenten.
Pro Datensatz gibt es genau ein customfield. Wenn du mehrere externe Schlüssel speichern möchtest, kannst du z.B. ein strukturiertes Format wie SHOP-4711|CRM-99 verwenden.

Nächste Schritte

Fehlerbehandlung & HTTP-Statuscodes – was die API zurückgibt, wenn etwas schiefläuft
Rate Limiting & Zugriffsbegrenzung – wie viele Anfragen du pro Zeitintervall stellen kannst

Verknüpfung mit