Zum Hauptinhalt gehen

Kunden (clients)

Svenja Jacobs
Aktualisiert

Über die Ressource /api/clients verwaltest du alle Kundenstammdaten – lesen, anlegen, bearbeiten, archivieren und löschen.

 

Basis-Endpunkt

https://{deineBillomatID}.billomat.net/api/clients

 

Alle Kunden abrufen

Request:

GET /api/clients

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

Response (200 OK):

{
  "clients": {
    "@page": "1",
    "@per_page": "100",
    "@total": "2",
    "client": [
      { "id": "789", "name": "Musterfirma GmbH", ... },
      { "id": "790", "name": "Beispiel AG", ... }
    ]
  }
}

 

Kunden filtern

Alle Filterparameter können mit & kombiniert werden:

Parameter Beschreibung
name Suche im Firmennamen (Teilsuche, case-insensitive)
client_number Kundennummer
email E-Mail-Adresse
first_name Vorname des Ansprechpartners
last_name Nachname des Ansprechpartners
country_code Ländercode nach ISO 3166 Alpha-2 (z.B. DE, AT, CH)
note Suche in der Notiz
invoice_id ID einer Rechnung für diesen Kunden (mehrere kommasepariert)
tags Schlagworte (kommasepariert)
customfield Wert des eigenen Meta-Datenfeldes

 

Beispiel: Alle Kunden, deren Firmenname „gmbh" enthält:

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/clients?name=gmbh&format=json

Response (200 OK):

{
  "clients": {
    "@page": "1",
    "@per_page": "100",
    "@total": "1",
    "client": {
      "id": "789",
      "name": "Musterfirma GmbH",
      "client_number": "KD-0042",
      "email": "max@musterfirma.de",
      "country_code": "DE"
    }
  }
}

 

Einzelnen Kunden abrufen

Request:

GET /api/clients/{id}

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

Response (200 OK) – vollständiges Datenobjekt:

{
  "client": {
    "id": "789",
    "created": "2024-01-15T09:30:00+01:00",
    "archived": "0",
    "client_number": "KD-0042",
    "name": "Musterfirma GmbH",
    "salutation": "Herr",
    "first_name": "Max",
    "last_name": "Muster",
    "street": "Musterstraße 123",
    "zip": "12345",
    "city": "Musterstadt",
    "state": "Sachsen",
    "country_code": "DE",
    "address": "Herr Max Muster\nMusterstraße 123\n12345 Musterstadt",
    "phone": "+49 351 123456",
    "email": "max@musterfirma.de",
    "www": "www.musterfirma.de",
    "vat_number": "DE123456789",
    "tax_rule": "COUNTRY",
    "net_gross": "SETTINGS",
    "currency_code": "EUR",
    "due_days": "14",
    "discount_rate": "2",
    "discount_days": "7",
    "note": "Stammkunde seit 2020",
    "revenue_gross": "11900.00",
    "revenue_net": "10000.00",
    "customfield": "SHOP-4711"
  }
}

Tipp – eigene Account-Daten abrufen:
Mit der speziellen ID myself rufst du die Stammdaten deines eigenen Billomat-Accounts ab – nützlich z.B. um die eigene billomatID oder Kontodaten programmatisch abzufragen:

GET /api/clients/myself

 

Neuen Kunden anlegen

Request:

POST /api/clients

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{
    "client": {
      "name": "Musterfirma GmbH",
      "salutation": "Herr",
      "first_name": "Max",
      "last_name": "Muster",
      "street": "Musterstraße 123",
      "zip": "12345",
      "city": "Musterstadt",
      "country_code": "DE",
      "email": "max@musterfirma.de",
      "vat_number": "DE123456789",
      "due_days": "14",
      "customfield": "SHOP-4711"
    }
  }' \
  https://{deineBillomatID}.billomat.net/api/clients

Response (201 Created):

{
  "client": {
    "id": "789",
    "client_number": "KD-0042",
    "name": "Musterfirma GmbH",
    "email": "max@musterfirma.de",
    "country_code": "DE",
    "customfield": "SHOP-4711",
    ...
  }
}

Alle verfügbaren Felder beim Erstellen:

Feld Typ Pflicht Beschreibung
name ALNUM — Firmenname
salutation ALNUM — Anrede
first_name ALNUM — Vorname
last_name ALNUM — Nachname
street ALNUM — Straße und Hausnummer
zip ALNUM — Postleitzahl
city ALNUM — Ort
country_code ISO 3166 — Ländercode (z.B. DE, AT, CH)
phone / fax / mobile ALNUM — Telefon, Fax, Mobil
email E-Mail — E-Mail-Adresse
www URL — Website (ohne http)
vat_number ALNUM — Umsatzsteuer-ID
tax_number ALNUM — Steuernummer
bank_iban IBAN — IBAN
bank_swift ALNUM — BIC/SWIFT
currency_code ISO — Währung (leer = Account-Standard)
tax_rule TAX / NO_TAX / COUNTRY — Steuerregel
net_gross NET / GROSS / SETTINGS — Preisbasis
due_days INT — Zahlungsziel in Tagen
discount_rate FLOAT — Skonto in Prozent
discount_days FLOAT — Skonto-Zeitraum in Tagen
reduction FLOAT — Standardrabatt in Prozent
sepa_mandate ALNUM — SEPA-Mandatsreferenz
sepa_mandate_date DATE — Ausstelldatum SEPA-Mandat
price_group INT — Preisgruppe des Kunden
debitor_account_number INT — Debitorennummer (für DATEV)
dunning_run BOOL — Automatischer Mahnlauf aktiv?
note ALNUM — Interne Notiz
archived BOOL — Archiviert? 0 = nein, 1 = ja
customfield ALNUM — Eigenes Meta-Datenfeld

 

Kunden bearbeiten

Es müssen nur die Felder mitgeschickt werden, die geändert werden sollen – alle anderen bleiben unberührt.

Request:

PUT /api/clients/{id}

curl -X PUT \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{"client": {"email": "neu@musterfirma.de", "due_days": "30"}}' \
  https://{deineBillomatID}.billomat.net/api/clients/789

Response (200 OK):

{
  "client": {
    "id": "789",
    "name": "Musterfirma GmbH",
    "email": "neu@musterfirma.de",
    "due_days": "30",
    ...
  }
}

 

Kunden archivieren

Kunden mit bestehenden Dokumenten können nicht gelöscht werden. Archiviere sie stattdessen – so bleiben alle Dokumente erhalten und der Kunde erscheint nicht mehr in der aktiven Kundenliste.

curl -X PUT \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{"client": {"archived": "1"}}' \
  https://{deineBillomatID}.billomat.net/api/clients/789

 

Kunden löschen

Request:

DELETE /api/clients/{id}

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

Response (200 OK) – kein Body.

Achtung: Löschen ist nur möglich, wenn keine Dokumente (Rechnungen, Angebote etc.) zu diesem Kunden existieren. Andernfalls antwortet die API mit 400 Bad Request. In diesem Fall: Kunden archivieren statt löschen.

 

Kundenbild abrufen

Liefert das hinterlegte Kundenbild in der gewünschten Größe (quadratisch zugeschnitten):

GET /api/clients/{id}/avatar?size=100

 

Unterressourcen

Ressource Endpunkt Beschreibung
Kontakte /api/contacts?client_id={id} Ansprechpartner eines Kunden → eigener Artikel
Attribute (Werte) /api/client-property-values?client_id={id} Werte der benutzerdefinierten Attribute → eigener Artikel
Schlagworte /api/client-tags?client_id={id} Tags eines Kunden → eigener Artikel
Meta-Daten /api/clients/{id}/customfield Eigenes Datenfeld → Eigene Meta-Daten

 

Verwandte Artikel

 

Verknüpfung mit

Kommentare

0 Kommentare

Zu diesem Beitrag können keine Kommentare hinterlassen werden.