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

Kunden

customer.create

Legt einen neuen Kunden an.

Daten

Felder Beschreibung Erlaubte Werte Standard
external_ident Wurde der Kunde z. B. von eBay importiert, ist das die eindeutige Kennung aus der Quelle String ""
external_account_name Wurde der Kunde z. B. von eBay importiert, ist das der Name des eBay-Kontos String ""
customer_type Quelle des Kunden, z. B. "amazon". "csv" für den CSV-Import, das Programm, aus dem die Datei stammt, steht in external_account_name, z. B. "Billbee" String "billware"
customer_nr Kundennummer; ist sie leer oder nicht gesetzt, wird eine Kundennummer erzeugt String Generated Number
is_business_client Gibt an, ob der Kunde ein Geschäftskunde ist 0 Nein 1 Ja 0
bill_title Anrede des Kunden -1 Firma 0 Herr 1 Frau 2 Divers 3 Keine Anrede 4 Familie 5 Eheleute 6 Doktor 7 Professor -1
bill_firstname Vorname String ""
bill_lastname Nachname String ""
bill_company Firmenname String ""
bill_vat_nr Umsatzsteuer-Identifikationsnummer des Kunden String ""
bill_street Straße String ""
bill_street2 Adresszusatz String ""
bill_zipcode Postleitzahl String ""
bill_city Ort String ""
bill_country Ländercode (ISO 3166 ALPHA-2) in Kleinbuchstaben, z. B. de; Großschreibung wird klein gespeichert String ""
bill_phone Telefonnummer String ""
bill_phone_mobile Mobilnummer String ""
bill_email E-Mail-Adresse String ""
divergent_delivery_address Gibt an, ob für diesen Kunden eine Lieferadresse angelegt werden soll 0 Nein 1 Ja 0
delivery_title Lieferadresse: Anrede des Kunden -1 Firma 0 Herr 1 Frau 2 Divers 3 Keine Anrede 4 Familie 5 Eheleute 6 Doktor 7 Professor -1
delivery_firstname Lieferadresse: Vorname String ""
delivery_lastname Lieferadresse: Nachname String ""
delivery_company Lieferadresse: Firmenname String ""
delivery_street Lieferadresse: Straße String ""
delivery_street2 Lieferadresse: Adresszusatz String ""
delivery_zipcode Lieferadresse: Postleitzahl String ""
delivery_city Lieferadresse: Ort String ""
delivery_country Lieferadresse: Ländercode (ISO 3166 ALPHA-2) in Kleinbuchstaben, z. B. de; Großschreibung wird klein gespeichert String "de"
delivery_phone Lieferadresse: Telefonnummer String ""
delivery_phone_mobile Lieferadresse: Mobilnummer String ""
account_bank Name der Bank String ""
account_bic BIC der Bank String ""
account_iban IBAN des Kundenkontos String ""
account_paypal PayPal-Konto des Kunden String ""
term_of_credit Zahlungsziel in Tagen Integer Das Zahlungsziel aus deinen billware-Einstellungen
user_note Optionale interne Notiz zu diesem Kunden String ""
public_authority_id Leitweg-ID einer Behörde, z. B. 04011000-1234512345-06. Neue Aufträge des Kunden übernehmen sie. Die Prüfziffern werden geprüft, eine falsche ID wird abgelehnt. Eine Änderung erreicht auch die Aufträge des Kunden ohne Rechnungsnummer, die noch die bisherige Leitweg-ID tragen String bis 46 Zeichen ""

Codebeispiele

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

PAYLOAD='{"customer_type":"billware","is_business_client":0,"bill_title":"Mister","bill_firstname":"Max","bill_lastname":"Mustermann","bill_street":"Musterstraße 12","bill_zipcode":"12345","bill_city":"Musterstadt","bill_country":"de","bill_phone":"+49 123 4567890","bill_email":"max.mustermann@example.com","divergent_delivery_address":1,"delivery_title":"Mister","delivery_firstname":"Max","delivery_lastname":"Mustermann","delivery_street":"Lieferweg 5","delivery_zipcode":"54321","delivery_city":"Lieferstadt","delivery_country":"de","delivery_phone":"+49 987 6543210","account_iban":"DE89370400440532013000","account_bic":"COBADEFFXXX","account_bank":"Commerzbank","account_paypal":"max.paypal@example.com","user_note":"Kunde möchte Rechnung nur per E-Mail erhalten","public_authority_id":""}'

# 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: customer.create" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Rückgabewerte

Felder Beschreibung
customer_ident Kennung des angelegten Kunden
address_ident Kennung der angelegten Lieferadresse. Steht divergent_delivery_address auf 0, ist der Wert NULL

Beispielantworten

	// SUCCESS creating a customer with a delivery address
{
	"response":true,
	"data":{
		"customer_ident":"30818cqJ36X624SC",
		"address_ident":"61636lu6Et7324W8"
	},
	"method":"customer.create",
	"message":"customer created"
}
	

customer.read

Liefert die Daten eines Kunden.

Daten

Felder Beschreibung Erlaubte Werte
customer_ident Pflicht Kennung des Kunden String

Codebeispiele

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

PAYLOAD='{"customer_ident":"46yq1898qmohrz57"}'

# 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: customer.read" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Rückgabewerte

Felder Beschreibung Typ
customer_ident Kennung des Kunden String
external_ident Wurde der Kunde z. B. von eBay importiert, ist das die eindeutige Kennung aus der Quelle String
external_account_name Wurde der Kunde z. B. von eBay importiert, ist das der Name des eBay-Kontos String
external_username Wurde der Kunde z. B. von eBay importiert, ist das der Benutzername des Kunden String
date_created Datum und Uhrzeit, wann der Kunde angelegt wurde Datum als String
date_created_user Datum, wann der Kunde angelegt wurde, im Format des Kontos, z. B. "19.10.2018" Datum als String
date_updated Datum und Uhrzeit der letzten Änderung des Kunden Datum als String
date_updated_user Datum der letzten Änderung des Kunden im Format des Kontos, z. B. "19.10.2018" Datum als String
customer_type Quelle des Kunden, z. B. "amazon" String
customer_nr Die Kundennummer String
is_business_client Gibt an, ob der Kunde ein Geschäftskunde ist 0 Nein 1 Ja
bill_title Anrede des Kunden -1 Firma 0 Herr 1 Frau 2 Divers 3 Keine Anrede 4 Familie 5 Eheleute 6 Doktor 7 Professor
bill_firstname Vorname String
bill_lastname Nachname String
bill_company Firmenname String
bill_vat_nr Umsatzsteuer-Identifikationsnummer String
bill_street Straße String
bill_street2 Adresszusatz String
bill_zipcode Postleitzahl String
bill_city Ort String
bill_country Ländercode (ISO 3166 ALPHA-2) in Kleinbuchstaben, z. B. de; Großschreibung wird klein gespeichert String
bill_email E-Mail-Adresse String
bill_phone Telefonnummer String
bill_phone_mobile Mobilnummer String
account_bank Name der Bank String
account_bic BIC der Bank String
account_iban IBAN des Kundenkontos String
account_paypal PayPal-Konto des Kunden String
term_of_credit Zahlungsziel in Tagen Integer
user_note Interne Notiz zu diesem Kunden String
public_authority_id Leitweg-ID einer Behörde, leer, wenn keine gesetzt ist String
address_data Array mit den Adressen des Kunden Array
[KEYS] Array-Element mit den Feldern einer Adresse Array Key
address_ident Kennung der Adresse String
customer_ident Kennung des Kunden, dem diese Adresse gehört String
delivery_title Anrede des Kunden -1 Firma 0 Herr 1 Frau 2 Divers 3 Keine Anrede 4 Familie 5 Eheleute 6 Doktor 7 Professor
delivery_firstname Vorname String
delivery_lastname Nachname String
delivery_company Firmenname String
delivery_street Straße String
delivery_street2 Adresszusatz String
delivery_zipcode Postleitzahl String
delivery_city Ort String
delivery_country Ländercode (ISO 3166 ALPHA-2) in Kleinbuchstaben, z. B. de; Großschreibung wird klein gespeichert String
delivery_phone Telefonnummer String
delivery_phone_mobile Mobilnummer String

Beispielantworten

	// SUCCESS
{
	"response": true,
	"data":
	{
		"customer":
		{
			"customer_ident": "3081k634q51Cw12v",
			"date_created": "2018-10-29 12:52:36",
			"date_updated": "2018-10-29 12:52:36",
			"external_ident": "",
			"external_account_name": "",
			"external_username": "",
			"customer_nr": "K-0025",
			"customer_type": "billware",
			"is_business_client": "1",
			"bill_title": "-1",
			"bill_firstname": "Max",
			"bill_lastname": "Mustermann",
			"bill_company": "Musterfirma Ltd.",
			"bill_vat_nr": "GB999999999",
			"bill_street": "23 Queen Victoria Street",
			"bill_street2": "",
			"bill_zipcode": "EC4N 4TR",
			"bill_city": "London",
			"bill_country": "gb",
			"bill_phone": "+4402043321",
			"bill_phone_mobile": "",
			"bill_email": "max.mustermann@www.de",
			"user_note": "",
			"account_number": "",
			"account_bank": "",
			"account_bank_code": "",
			"account_iban": "",
			"account_bic": "",
			"account_paypal": "max.mustermann@www.de",
			"term_of_credit": "30",
			"date_created_user": "29.10.2018",
			"date_updated_user": "29.10.2018",
			"public_authority_id": ""
		},
		"address_data": [
		{
			"address_ident": "6Cl11E63987I9680",
			"customer_ident": "3081k634q51Cw12v",
			"date_created": "2018-10-31 14:43:15",
			"date_updated": "2018-10-31 14:43:15",
			"delivery_firstname": "Maria",
			"delivery_lastname": "Mustermann",
			"delivery_company": "",
			"delivery_street": "23 Queensway",
			"delivery_street2": "",
			"delivery_zipcode": "W2 4QJ",
			"delivery_city": "London",
			"delivery_country": "gb",
			"delivery_phone": "",
			"delivery_phone_mobile": "",
			"delivery_title": "1"
		}]
	},
	"method": "customer.read",
	"message": "customer and address data loaded"
}
	

customer.update

Ändert ein oder mehrere Felder eines Kunden.

Daten

Felder Beschreibung Erlaubte Werte
customer_ident Pflicht Kennung des Kunden String
validate Der Aufruf kehrt ohne Änderung zurück, wenn der angegebene Wert schon existiert. Sonst wird der Kunde geändert. Siehe Beispiel unten. Feld Beispiel: customer_nr
[Weitere Felder] Siehe customer.create

Schreibgeschützt

Felder Beschreibung
customer_ident Interne Kennung
external_ident Interne Kennung
external_account_name Interne Kennung
date_created_user Wird automatisch berechnet, ändere stattdessen date_created (UTC)
date_updated Wird automatisch berechnet
date_updated_user Wird automatisch berechnet
address_data Nutze stattdessen die Funktion address.create

Codebeispiele

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

PAYLOAD='{"customer_ident":"46yq1898qmohrz57","bill_firstname":"Moritz"}'

# 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: customer.update" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Antwortdaten

Felder Beschreibung Typ
response Gibt an, ob die Aktion erfolgreich war true false
data Array mit den Antwortdaten Array
customer_ident Die Kennung des geänderten Kunden String
[fields] Alle geänderten und bereinigten Felder
method customer.update String
message Zusätzliche Information zur Anfrage String

Beispielantworten

	// SUCCESS after updating the customer term of credit
{
	"response":true,
	"data": {
		"customer_ident" : "30Wp80787u99z2qv",
		"term_of_credit" : "20"
	},
	"method":"customer.update",
	"message":"customer updated"
}

// ERROR
{
	"response":false,
	"data": null,
	"method":"customer.update",
	"message":"customer not found"
}
	

customer.delete

Löscht einen bestehenden Kunden.

Daten

Felder Beschreibung Erlaubte Werte
customer_ident Pflicht Kennung des Kunden String

Codebeispiele

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

PAYLOAD='{"customer_ident":"46yq1898qmohrz57"}'

# 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: customer.delete" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Beispielantworten

	// SUCCESS
{
	"response":true,
	"data":null,
	"method":"customer.delete",
	"message":"customer deleted"
}

// ERROR
{
	"response":false,
	"data": null,
	"method":"customer.delete",
	"message":"customer not found"
}
	

customer.exists

Prüft, ob ein Kunde existiert.

Daten

Felder Beschreibung Erlaubte Werte
customer_ident Pflicht Kennung des Kunden String

Codebeispiele

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

PAYLOAD='{"customer_ident":"46yq1898qmohrz57"}'

# 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: customer.exists" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Beispielantworten

	// SUCCESS
{
	"response":true,
	"data": {
		"customer_ident" : "30Wp80787u99z2qv"
	},
	"method":"customer.exists",
	"message":"customer does exist"
}

// ERROR
{
	"response":false,
	"data": null,
	"method":"customer.exists",
	"message":"customer does not exist"
}
	

address.create

Legt eine neue Lieferadresse für einen Kunden an.

Daten

Felder Beschreibung Erlaubte Werte Standard
customer_ident Pflicht Kennung des Kunden String
delivery_title Anrede des Kunden -1 Firma 0 Herr 1 Frau 2 Divers 3 Keine Anrede 4 Familie 5 Eheleute 6 Doktor 7 Professor -1
delivery_firstname Vorname String ""
delivery_lastname Nachname String ""
delivery_company Firmenname String ""
delivery_street Straße String ""
delivery_street2 Adresszusatz String ""
delivery_zipcode Postleitzahl String ""
delivery_city Ort String ""
delivery_country Ländercode (ISO 3166 ALPHA-2) in Kleinbuchstaben, z. B. de; Großschreibung wird klein gespeichert String "de"
delivery_phone Telefonnummer String ""
delivery_phone_mobile Mobilnummer String ""

Codebeispiele

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

PAYLOAD='{"customer_ident":"46yq1898qmohrz57","delivery_title":0,"delivery_firstname":"Max","delivery_lastname":"Mustermann","delivery_company":"Muster GmbH","delivery_street":"Lieferweg 5","delivery_street2":"Etage 3","delivery_zipcode":"54321","delivery_city":"Lieferstadt","delivery_country":"de","delivery_phone":"+49 987 6543210","delivery_phone_mobile":"+49 171 1234567"}'

# 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: address.create" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Rückgabewerte

Felder Beschreibung
address_ident Kennung der angelegten Adresse
customer_ident Kennung des Kunden, dem diese Adresse gehört

Beispielantworten

	// SUCCESS
{
	"response":true,
	"data":{
		"customer_ident":"30818cqJ36X624SC",
		"address_ident":"61636lu6Et7324W8"
	},
	"method":"address.create",
	"message":"address created"
}

// ERROR
{
	"response":false,
	"data": null,
	"method":"address.create",
	"message":"customer_ident not set"
}
	

address.exists

Prüft, ob eine Lieferadresse existiert.

Daten

Felder Beschreibung Erlaubte Werte
address_ident Pflicht Kennung der Lieferadresse String

Codebeispiele

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

PAYLOAD='{"address_ident":"61636lu6Et7324W8"}'

# 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: address.exists" \
  -H "Content-Type: application/json" \
  -d "$PAYLOAD"

Beispielantworten

// SUCCESS
{
    "response": true,
    "data": {
        "address_ident": "61636lu6Et7324W8"
    },
    "method": "address.exists",
    "message": "address does exist"
}

// ERROR – the request itself was fine, the address is unknown
{
    "response": false,
    "data": {
        "address_ident": "61636lu6Et7324W8"
    },
    "method": "address.exists",
    "message": "address does not exist"
}