Zum Hauptinhalt gehen

Lieferanten (suppliers) – inkl. Attribute & Schlagworte

Svenja Jacobs
Aktualisiert

Über die Ressource /api/suppliers verwaltest du alle Lieferantenstammdaten – lesen, anlegen, bearbeiten und löschen, inklusive Attributen und Schlagworten.

 

Basis-Endpunkt

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

 

 

Alle Lieferanten abrufen

Request:

GET /api/suppliers

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

Response (200 OK):

{
  "suppliers": {
    "@page": "1",
    "@per_page": "100",
    "@total": "2",
    "supplier": [
      { "id": "1234", "name": "Musterfirma", ... },
      { "id": "1235", "name": "Lieferant GmbH", ... }
    ]
  }
}

Verfügbare Filterparameter:

Parameter Beschreibung
name Firma/Bezeichnung (Teilsuche, case-insensitive)
email E-Mail-Adresse
first_name Vorname Ansprechpartner
last_name Nachname Ansprechpartner
country_code Ländercode nach ISO 3166 Alpha-2
creditor_identifier SEPA Gläubiger-ID
note Suche in der Notiz
client_number Kundennummer beim Lieferanten
incoming_id ID einer Eingangsrechnung für diesen Lieferanten (mehrere kommasepariert)
tags Kommaseparierte Schlagworte

 

 

Einzelnen Lieferanten abrufen

Request:

GET /api/suppliers/{id}

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

Response (200 OK) – vollständiges Datenobjekt:

{
  "supplier": {
    "id": "1234",
    "created": "2007-12-13T12:12:00+01:00",
    "name": "Musterfirma",
    "salutation": "Herr",
    "first_name": "Max",
    "last_name": "Muster",
    "street": "Musterstraße 123",
    "zip": "12345",
    "city": "Musterstadt",
    "state": "Bundesland",
    "country_code": "DE",
    "phone": "+49 123456789",
    "fax": "+49 123456789",
    "mobile": "+49 123456789",
    "email": "max@musterfirma.de",
    "www": "www.musterfirma.de",
    "tax_number": "12/3456/789",
    "vat_number": "DE123456789",
    "creditor_identifier": "DE98ZZZ09999999999",
    "bank_account_owner": "Kontoinhaber",
    "bank_number": "123456789",
    "bank_name": "Deutsche Bank",
    "bank_account_number": "123456789",
    "bank_swift": "DEUTDEDB",
    "bank_iban": "DE89370400440532013000",
    "currency_code": "EUR",
    "note": "Sehr netter Lieferant",
    "client_number": "KD123",
    "costs_gross": "11900.00",
    "costs_net": "10000.00"
  }
}

Hinweis: Die Felder costs_gross und costs_net sind nur lesbar – sie werden von Billomat automatisch aus den Eingangsrechnungen des Lieferanten berechnet und können nicht manuell gesetzt werden.

 

 

Neuen Lieferanten anlegen

Kein Feld ist Pflichtfeld – alle Angaben sind optional.

Request:

POST /api/suppliers

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{
    "supplier": {
      "name": "Musterfirma",
      "salutation": "Herr",
      "first_name": "Max",
      "last_name": "Muster",
      "street": "Musterstraße 123",
      "zip": "12345",
      "city": "Musterstadt",
      "state": "Bundesland",
      "country_code": "DE",
      "phone": "+49 123456789",
      "fax": "+49 123456789",
      "mobile": "+49 123456789",
      "email": "max@musterfirma.de",
      "www": "www.musterfirma.de",
      "tax_number": "12/3456/789",
      "vat_number": "DE123456789",
      "creditor_identifier": "DE98ZZZ09999999999",
      "bank_account_owner": "Kontoinhaber",
      "bank_number": "123456789",
      "bank_name": "Deutsche Bank",
      "bank_account_number": "123456789",
      "bank_swift": "DEUTDEDB",
      "bank_iban": "DE89370400440532013000",
      "currency_code": "EUR",
      "note": "Sehr netter Lieferant",
      "client_number": "KD123"
    }
  }' \
  https://{deineBillomatID}.billomat.net/api/suppliers

Response (201 Created):

{
  "supplier": {
    "id": "1234",
    "created": "2024-06-01T10:00:00+02:00",
    "name": "Musterfirma",
    ...,
    "costs_gross": "0",
    "costs_net": "0"
  }
}

Alle verfügbaren Felder beim Anlegen:

Feld Typ Pflicht Beschreibung
name ALNUM — Firmenname
street ALNUM — Straße
zip ALNUM — PLZ
city ALNUM — Ort
state ALNUM — Bundesland, Bezirk, Region
country_code ISO 3166 — Ländercode (z.B. DE) – Standard: Wert aus eigenem Account
salutation ALNUM — Anrede
first_name ALNUM — Vorname
last_name ALNUM — Nachname
phone ALNUM — Telefon
fax ALNUM — Fax
mobile ALNUM — Mobiltelefon
email E-Mail — E-Mail-Adresse
www URL — Website (ohne http)
tax_number ALNUM — Steuernummer
vat_number Ust-IdNr. — Umsatzsteuer-Identifikationsnummer
creditor_identifier Gläubiger-ID — SEPA Gläubiger-ID
bank_account_number ALNUM — Kontonummer
bank_account_owner ALNUM — Kontoinhaber
bank_number ALNUM — BLZ
bank_name ALNUM — Bankname
bank_swift ALNUM — SWIFT/BIC
bank_iban IBAN — IBAN
currency_code ISO — Währung des Lieferanten (leer = Account-Währung)
note ALNUM — Interne Notiz
client_number ALNUM — Eigene Kundennummer beim Lieferanten
costs_gross FLOAT — Gesamtkosten brutto (nur lesen, automatisch berechnet)
costs_net FLOAT — Gesamtkosten netto (nur lesen, automatisch berechnet)

 

 

Lieferanten bearbeiten

Es müssen nur die zu ändernden Felder mitgeschickt werden.

Request:

PUT /api/suppliers/{id}

curl -X PUT \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{"supplier": {"name": "Die super Musterfirma"}}' \
  https://{deineBillomatID}.billomat.net/api/suppliers/1234

Response (200 OK) – vollständiger aktualisierter Datensatz:

{
  "supplier": {
    "id": "1234",
    "name": "Die super Musterfirma",
    "salutation": "Herr",
    "first_name": "Max",
    ...
  }
}

 

 

Lieferanten löschen

Request:

DELETE /api/suppliers/{id}

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

Response (200 OK) – kein Body.

Achtung: Das Löschen ist nur möglich, wenn keine Eingangsrechnungen zu diesem Lieferanten existieren. Andernfalls antwortet die API mit 400 Bad Request.

 

 

Teil 2: Benutzerdefinierte Attribute

Analog zu Kunden können auch Lieferanten mit eigenen Attributen versehen werden. Die Attributdefinitionen werden unter Einstellungen > Lieferanten-Attribute angelegt, die Werte über /api/supplier-property-values verwaltet.

 

Alle Attributwerte auflisten

Request:

GET /api/supplier-property-values

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

Filterparameter:

Parameter Beschreibung
supplier_id ID eines bestimmten Lieferanten
supplier_property_id ID eines bestimmten Attributs
value Wert des Attributs

 

Einzelnes Attribut abrufen

Request:

GET /api/supplier-property-values/{id}

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

Response (200 OK):

{
  "supplier-property-value": {
    "id": "1",
    "supplier_id": "1234",
    "supplier_property_id": "3",
    "type": "TEXTFIELD",
    "name": "Abteilung",
    "value": "Marketing"
  }
}

 

Attributwert setzen

Alle drei Felder sind Pflichtfelder.

Request:

POST /api/supplier-property-values

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{
    "supplier-property-value": {
      "supplier_id": "1234",
      "supplier_property_id": "3",
      "value": "Innendienst"
    }
  }' \
  https://{deineBillomatID}.billomat.net/api/supplier-property-values

Response (201 Created):

{
  "supplier-property-value": {
    "id": "1",
    "supplier_id": "1234",
    "supplier_property_id": "3",
    "type": "TEXTFIELD",
    "name": "Abteilung",
    "value": "Innendienst"
  }
}

 

 

Teil 3: Schlagworte (Tags)

Schlagworte dienen zur freien Kategorisierung von Lieferanten. Das Muster ist identisch mit den Kunden-Tags – nur mit dem Endpunkt /api/supplier-tags.

 

Alle Schlagworte (Tagcloud) abrufen

Request:

GET /api/supplier-tags

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

Response (200 OK):

{
  "supplier-tags": {
    "@total": "2",
    "supplier-tag": [
      { "id": "1", "name": "Stammlieferant", "count": "12" },
      { "id": "2", "name": "Ausland", "count": "7" }
    ]
  }
}

 

Schlagworte eines Lieferanten abrufen

supplier_id ist Pflichtparameter – Schlagworte können nur lieferantenbezogen abgerufen werden.

Request:

GET /api/supplier-tags?supplier_id={id}

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/supplier-tags?supplier_id=1234&format=json

Response (200 OK):

{
  "supplier-tags": {
    "@total": "1",
    "supplier-tag": {
      "id": "5",
      "supplier_id": "1234",
      "name": "Stammlieferant"
    }
  }
}

 

Schlagwort vergeben

Beide Felder sind Pflichtfelder.

Request:

POST /api/supplier-tags

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{"supplier-tag": {"supplier_id": "1234", "name": "Stammlieferant"}}' \
  https://{deineBillomatID}.billomat.net/api/supplier-tags

Response (201 Created):

{
  "supplier-tag": {
    "id": "5",
    "supplier_id": "1234",
    "name": "Stammlieferant"
  }
}

 

Schlagwort entfernen

Request:

DELETE /api/supplier-tags/{id}

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

Response (200 OK) – kein Body.

 

Verwandte Artikel

 

Verknüpfung mit

Kommentare

0 Kommentare

Zu diesem Beitrag können keine Kommentare hinterlassen werden.