Zum Inhalt springen

Lösungen

Freelancer & Selbstständige Rechnungen und Belege ohne Shop eBay Verkäufe automatisch abrechnen Shopify Bestellungen direkt aus dem Shop WooCommerce WordPress-Shop anbinden

Lieferanten

Mit diesen Methoden pflegst du die Lieferanten deines Kontos und ihre Dokumente, zum Beispiel Verträge und Preislisten. Einer Ausgabe ordnest du einen Lieferanten über supplier_ident zu, siehe Ausgaben.

Hinweis

Die Methoden brauchen die Erweiterung Lieferanten. Ist sie für dein Konto nicht aktiv, antwortet jede von ihnen mit 403. Was sich nicht so speichern lässt, wie du es sendest, wird mit dem Grund abgelehnt: Nichts wird stillschweigend gekürzt oder weggelassen. Die Längen zählen in der gespeicherten Form: billware speichert Text wie der Kundenbereich, dort belegt & fünf Zeichen, < und > je vier, " und ' je sechs.

supplier.create

Legt einen neuen Lieferanten an.

Daten

Felder Beschreibung Erlaubte Werte Standard
bill_company Firmenname, höchstens 128 Zeichen. String ""
bill_firstname Vorname, höchstens 64 Zeichen. String ""
bill_lastname Nachname, höchstens 64 Zeichen. String ""
bill_email E-Mail-Adresse, höchstens 256 Zeichen. Sie muss eine gültige Adresse sein. String ""
bill_title Anrede -1 Firma 0 Herr 1 Frau 2 Divers 3 Keine Anrede 4 Familie 5 Eheleute 6 Doktor 7 Professor 3
supplier_nr Lieferantennummer, höchstens 32 Zeichen. Sie darf im Konto nur einmal vorkommen. Ohne Angabe vergibt billware die nächste Nummer deines Nummernkreises. String Generated Number
supplier_type Quelle des Lieferanten, höchstens 32 Zeichen, z. B. der Name deines Systems. String "billware"
external_ident Kennung des Lieferanten in deinem System, höchstens 512 Zeichen. Nach ihr kannst du in supplier.list filtern. String ""
bill_vat_nr Umsatzsteuer-Identifikationsnummer, höchstens 32 Zeichen. String ""
bill_street Straße und Hausnummer, höchstens 128 Zeichen. String ""
bill_street2 Adresszusatz, höchstens 64 Zeichen. String ""
bill_zipcode Postleitzahl, höchstens 64 Zeichen. String ""
bill_city Ort, höchstens 128 Zeichen. String ""
bill_country Ländercode (ISO 3166 ALPHA-2), z. B. de. Großschreibung wird klein gespeichert. String Das Standardland deines Kontos
bill_phone Telefonnummer, höchstens 64 Zeichen. String ""
bill_phone_mobile Mobilnummer, höchstens 64 Zeichen. String ""
account_bank Name der Bank, höchstens 128 Zeichen. String ""
account_iban IBAN, höchstens 32 Zeichen. String ""
account_bic BIC, höchstens 16 Zeichen. String ""
account_paypal PayPal-Adresse des Lieferanten, höchstens 64 Zeichen. Sie muss eine gültige E-Mail-Adresse sein. String ""
user_note Notiz, höchstens 1024 Zeichen. String ""

Eines der Felder bill_company, bill_lastname oder bill_email ist Pflicht: Ein Lieferant braucht etwas, woran er sich erkennen lässt.

Codebeispiele

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"bill_company":"Papier & Druck KG","bill_firstname":"Jörg","bill_lastname":"Becker","bill_title":-1,"bill_vat_nr":"DE123456789","bill_street":"Hauptstraße 5","bill_zipcode":"50667","bill_city":"Köln","bill_country":"de","bill_phone":"+49 221 123456","bill_email":"einkauf@papier-druck.example","account_bank":"Sparkasse KölnBonn","account_iban":"DE89370400440532013000","account_bic":"COBADEFFXXX","supplier_nr":"L-7001","external_ident":"ERP-4711","user_note":"Zahlungsziel 30 Tage"}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: supplier.create" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Rückgabewerte

Die Antwort enthält den angelegten Lieferanten mit derselben Struktur wie supplier.read.

Beispielantworten


// SUCCESS
{
    "response": true,
    "data": {
        "supplier_ident": "ckt8w78bfmj54054",
        "supplier_nr": "L-7001",
        "supplier_type": "billware",
        "external_ident": "ERP-4711",
        "bill_title": -1,
        "bill_firstname": "Jörg",
        "bill_lastname": "Becker",
        "bill_company": "Papier & Druck KG",
        "bill_vat_nr": "DE123456789",
        "bill_street": "Hauptstraße 5",
        "bill_street2": "",
        "bill_zipcode": "50667",
        "bill_city": "Köln",
        "bill_country": "de",
        "bill_phone": "+49 221 123456",
        "bill_phone_mobile": "",
        "bill_email": "einkauf@papier-druck.example",
        "account_bank": "Sparkasse KölnBonn",
        "account_iban": "DE89370400440532013000",
        "account_bic": "COBADEFFXXX",
        "account_paypal": "",
        "user_note": "Zahlungsziel 30 Tage",
        "date_created": "2026-11-16 10:30:09",
        "date_updated": "2026-11-16 10:30:09",
        "files": []
    },
    "message": "supplier created"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "A supplier needs bill_company, bill_lastname or bill_email"
}

supplier.read

Liefert einen Lieferanten mit seinen Dokumenten.

Daten

Felder Beschreibung Erlaubte Werte
supplier_ident Pflicht Kennung des Lieferanten String

Codebeispiele

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"supplier_ident":"ckt8w78bfmj54054"}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: supplier.read" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Rückgabewerte

Felder Beschreibung
supplier_ident Kennung des Lieferanten
supplier_nr Lieferantennummer
supplier_type Quelle des Lieferanten
external_ident Kennung des Lieferanten in deinem System
bill_title Anrede als Zahl, die Werte stehen bei supplier.create
bill_*
account_*
user_note
Name, Anschrift, Kontakt, Bankverbindung und Notiz, wie du sie gesendet hast
date_created
date_updated
Zeitpunkt der Anlage und der letzten Änderung in Serverzeit (UTC). Ein Lieferant, den du unverändert noch einmal sendest, gilt nicht als geändert.
files Die Dokumente des Lieferanten, das älteste zuerst, jedes wie in der Antwort von supplier.fileUpload. Die Belege seiner Ausgaben gehören nicht dazu, sie stehen bei den Ausgaben.

Beispielantworten


// SUCCESS
{
    "response": true,
    "data": {
        "supplier_ident": "ckt8w78bfmj54054",
        "supplier_nr": "L-7001",
        "supplier_type": "billware",
        "external_ident": "ERP-4711",
        "bill_title": -1,
        "bill_firstname": "Jörg",
        "bill_lastname": "Becker",
        "bill_company": "Papier & Druck KG",
        "bill_vat_nr": "DE123456789",
        "bill_street": "Hauptstraße 5",
        "bill_street2": "",
        "bill_zipcode": "50667",
        "bill_city": "Köln",
        "bill_country": "de",
        "bill_phone": "+49 221 123456",
        "bill_phone_mobile": "",
        "bill_email": "einkauf@papier-druck.example",
        "account_bank": "Sparkasse KölnBonn",
        "account_iban": "DE89370400440532013000",
        "account_bic": "COBADEFFXXX",
        "account_paypal": "",
        "user_note": "Zahlungsziel 30 Tage",
        "date_created": "2026-11-16 10:30:09",
        "date_updated": "2026-11-16 10:30:09",
        "files": [
            {
                "href": "https://www.billware.de/file?t=...",
                "file_ident": "l51gvi7q0su56l44",
                "controller": "supplier",
                "parent_ident": "ckt8w78bfmj54054",
                "file_name": "file_43a37bf8fa591e73a5d091b47a7c5b1f87b52c40.pdf",
                "file_user_name": "Rahmenvertrag 2026.pdf",
                "file_type": "user",
                "file_extension": "pdf",
                "reference_nr": "L-7001",
                "date_updated": "2026-11-16 10:30:10",
                "date_updated_user": "16.11.2026"
            }
        ]
    },
    "message": "Read supplier with ident: ckt8w78bfmj54054"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "Supplier not found"
}

supplier.list

Liefert mehrere Lieferanten als Liste.

Daten

Felder Beschreibung Erlaubte Werte Standard
date_type Das Datum, nach dem der Zeitraum gilt und die Liste sortiert ist, das neueste zuerst. "date_created" "date_updated" "date_created"
start_date Beginn des Zeitraums. Format: Y-m-d H:i:s (z. B. "2026-10-01 00:00:00"), verglichen wird mit den gespeicherten Zeitpunkten in Serverzeit (UTC). Mit date_type date_updated bekommst du so alles, was sich seit einem Zeitpunkt geändert hat. Ein neues oder gelöschtes Dokument ändert den Lieferanten dabei nicht. String
end_date Ende des Zeitraums, im selben Format wie start_date. String
supplier_nr Nur der Lieferant mit dieser Nummer. String
supplier_type Nur Lieferanten dieser Quelle. String
external_ident Nur der Lieferant mit dieser Kennung aus deinem System. String
bill_email Nur Lieferanten mit dieser E-Mail-Adresse. String
bill_company Nur Lieferanten mit genau diesem Firmennamen. String
bill_vat_nr Nur Lieferanten mit dieser Umsatzsteuer-Identifikationsnummer. String
bill_country Nur Lieferanten aus diesem Land, als Ländercode. String
page Seite der Liste. Ohne Angabe kommt die erste Seite. Integer 1
limit Zahl der Einträge je Seite, von 1 bis 100. Integer 25

Alle Angaben sind optional und lassen sich kombinieren, ein Lieferant muss dann zu jedem Filter passen. Ohne Angaben enthält die Liste alle Lieferanten deines Kontos.

Codebeispiele

supplier.list

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"page":1,"limit":50}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: supplier.list" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

supplier.list (changed since)

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"date_type":"date_updated","start_date":"2026-11-01 00:00:00"}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: supplier.list" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Rückgabewerte

Das Array suppliers enthält Einträge mit derselben Struktur wie die Antwort von supplier.read.

Seitenweise Ausgabe

Die Antwort enthält Angaben zur seitenweisen Ausgabe:

Mit page blätterst du durch die Seiten, mit limit legst du fest, wie viele Einträge eine Seite hat. Eine Seite hat höchstens 100 Einträge, insgesamt gibt es keine Obergrenze: Über die Seiten bis total_pages erreichst du jeden Eintrag.

Beispielantworten


// SUCCESS
{
    "response": true,
    "data": {
        "page": 1,
        "limit": 25,
        "total": 12,
        "total_pages": 1,
        "suppliers": [
            {
                "supplier_ident": "ckt8w78bfmj54054",
                "supplier_nr": "L-7001",
                "bill_company": "Papier & Druck KG",
                ...
            },
            ...
        ]
    },
    "message": "Supplier list retrieved successfully"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "Invalid date_type. Allowed: date_created, date_updated"
}

supplier.update

Ändert ein oder mehrere Felder eines Lieferanten.

Daten

Felder Beschreibung Erlaubte Werte
supplier_ident Pflicht Kennung des Lieferanten String

Dazu jedes Feld von supplier.create, das du ändern willst. Nur gesendete Felder ändern sich, ein leerer Text leert das Feld. Nummer, Anrede und Land lassen sich nicht leeren.

Codebeispiele

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"supplier_ident":"ckt8w78bfmj54054","bill_city":"Bonn","bill_zipcode":"53111"}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: supplier.update" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Rückgabewerte

Die Antwort enthält den Lieferanten im neuen Stand, mit derselben Struktur wie supplier.read.

Beispielantworten


// SUCCESS
{
    "response": true,
    "data": {
        "supplier_ident": "ckt8w78bfmj54054",
        "bill_city": "Bonn",
        ...
    },
    "message": "supplier updated"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "supplier_nr is taken already"
}

supplier.put

Legt einen Lieferanten an oder ändert ihn, in einem Aufruf. Damit gleichst du die Lieferanten deines Systems ab, ohne ihre Kennungen zu speichern.

billware sucht den Lieferanten in dieser Reihenfolge:

  1. über supplier_ident, wenn du sie sendest. Gibt es sie nicht, antwortet der Aufruf mit einem Fehler und legt nichts an.
  2. sonst über bill_email,
  3. sonst über bill_company.

Ein gefundener Lieferant wird geändert wie mit supplier.update, sonst wird ein neuer angelegt wie mit supplier.create. Ein leerer Text findet niemanden. Haben mehrere Lieferanten dieselbe E-Mail-Adresse oder Firma, wird der zuerst angelegte geändert.

Codebeispiele

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"bill_email":"einkauf@papier-druck.example","bill_company":"Papier & Druck KG","bill_phone":"+49 221 654321"}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: supplier.put" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Beispielantworten


// SUCCESS, the supplier was found
{
    "response": true,
    "data": {
        "supplier_ident": "ckt8w78bfmj54054",
        "bill_email": "einkauf@papier-druck.example",
        "bill_phone": "+49 221 654321",
        ...
    },
    "message": "supplier updated"
}

// SUCCESS, the supplier was new
{
    "response": true,
    "data": {
        "supplier_ident": "9v6c1x0p4w7m2k8d",
        ...
    },
    "message": "supplier created"
}

supplier.delete

Löscht einen Lieferanten mit seinen Dokumenten. Seine Ausgaben bleiben erhalten, sie haben danach keinen Lieferanten mehr.

Daten

Felder Beschreibung Erlaubte Werte
supplier_ident Pflicht Kennung des Lieferanten String

Codebeispiele

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"supplier_ident":"ckt8w78bfmj54054"}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: supplier.delete" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Beispielantworten


// SUCCESS
{
    "response": true,
    "data": null,
    "message": "supplier deleted"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "Supplier not found"
}

supplier.fileUpload

Speichert ein Dokument zu einem Lieferanten.

Daten

Felder Beschreibung Erlaubte Werte Standard
supplier_ident Pflicht Kennung des Lieferanten String
file_base64 Der Inhalt der Datei, Base64-kodiert. Entweder file_base64 oder file_url, nicht beides. String
file_url Ein Link, von dem billware die Datei selbst abruft. Nur https und nur öffentlich erreichbare Adressen. String
file_name Name der Datei. Ohne Angabe heißt das Dokument wie die Lieferantennummer, z. B. L-7001.pdf. String Die Lieferantennummer

Codebeispiele

supplier.fileUpload (Base64)

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"supplier_ident":"ckt8w78bfmj54054","file_base64":"JVBERi0xLjQKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyA+PgplbmRvYmoKdHJhaWxlcgo8PCAvUm9vdCAxIDAgUiA+PgolJUVPRgo=","file_name":"Rahmenvertrag 2026.pdf"}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: supplier.fileUpload" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

supplier.fileUpload (link)

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"supplier_ident":"ckt8w78bfmj54054","file_url":"https://www.example.com/vertraege/rahmenvertrag-2026.pdf"}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: supplier.fileUpload" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Rückgabewerte

Felder Beschreibung
href Link zum Herunterladen der Datei. Er funktioniert ohne Anmeldung, gib ihn also nur an Berechtigte weiter.
file_ident Kennung der Datei
parent_ident Kennung des Datensatzes, zu dem die Datei gehört
file_user_name Der Dateiname, wie du ihn gesendet hast
file_name Der Name, unter dem billware die Datei speichert
file_extension Endung der Datei, z. B. pdf
reference_nr Nummer des Datensatzes, zu dem die Datei gehört, so wie sie beim Hochladen war
date_updated Zeitpunkt des Hochladens in Serverzeit (UTC)

Beispielantworten


// SUCCESS
{
    "response": true,
    "data": {
        "href": "https://www.billware.de/file?t=...",
        "file_ident": "l51gvi7q0su56l44",
        "controller": "supplier",
        "parent_ident": "ckt8w78bfmj54054",
        "file_name": "file_43a37bf8fa591e73a5d091b47a7c5b1f87b52c40.pdf",
        "file_user_name": "Rahmenvertrag 2026.pdf",
        "file_type": "user",
        "file_extension": "pdf",
        "reference_nr": "L-7001",
        "date_updated": "2026-11-16 10:30:10",
        "date_updated_user": "16.11.2026"
    },
    "message": "File uploaded"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "Only PDF, XML, JPG, PNG, GIF, TXT, DOC, DOCX, RTF and XLSX files are accepted"
}

supplier.fileDelete

Löscht ein Dokument eines Lieferanten.

Daten

Felder Beschreibung Erlaubte Werte
supplier_ident Pflicht Kennung des Lieferanten String
file_ident Pflicht Kennung des Dokuments, aus der Antwort von supplier.fileUpload oder aus files des Lieferanten. String

Codebeispiele

# Get your API credentials from your billware customer area
API_APPID="your-app-id"
API_SECRET="your-api-secret"

PAYLOAD='{"supplier_ident":"ckt8w78bfmj54054","file_ident":"l51gvi7q0su56l44"}'

# The HMAC is calculated over the exact request body that is sent
HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

curl -X POST "https://www.billware.de/api/v1" \
  -H "X-Bw-Hmac: $API_APPID:$HMAC" \
  -H "X-Bw-Method: supplier.fileDelete" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Rückgabewerte

Die Antwort enthält den Lieferanten im neuen Stand, mit derselben Struktur wie supplier.read.

Beispielantworten


// SUCCESS
{
    "response": true,
    "data": {
        "supplier_ident": "ckt8w78bfmj54054",
        "files": [],
        ...
    },
    "message": "File deleted"
}

// ERROR
{
    "response": false,
    "data": null,
    "message": "File not found"
}