Suppliers
With these methods you maintain the suppliers of your account and their documents, for example contracts and price lists. You link a supplier to an expense by supplier_ident, see Expenses.
The methods need the extension Suppliers. If it is not active for your account, each of them answers with 403. What cannot be stored the way you send it is refused with the reason: nothing is cut or dropped silently. Lengths count the stored form: billware stores text the way the customer area does, there & takes five characters, < and > four each, " and ' six each.
supplier.create
Create a new supplier.Data
| Fields | Description | Accepted Types | Defaults To |
|---|---|---|---|
| bill_company | Company name, 128 characters at most. | String |
"" |
| bill_firstname | First name, 64 characters at most. | String |
"" |
| bill_lastname | Last name, 64 characters at most. | String |
"" |
| bill_email | E-mail address, 256 characters at most. It has to be a valid address. | String |
"" |
| bill_title | Title | -1 Company 0 Mister 1 Miss 2 Diverse 3 No title 4 Family 5 Couple 6 Doctor 7 Professor |
3 |
| supplier_nr | Supplier number, 32 characters at most. It may exist only once in the account. Without it billware assigns the next number of your number range. | String |
Generated Number |
| supplier_type | Source of the supplier, 32 characters at most, e.g. the name of your system. | String |
"billware" |
| external_ident | Ident of the supplier in your system, 512 characters at most. You can filter by it in supplier.list. | String |
"" |
| bill_vat_nr | VAT number, 32 characters at most. | String |
"" |
| bill_street | Street and number, 128 characters at most. | String |
"" |
| bill_street2 | Addition to the address, 64 characters at most. | String |
"" |
| bill_zipcode | Zip code, 64 characters at most. | String |
"" |
| bill_city | City, 128 characters at most. | String |
"" |
| bill_country | Country code (ISO 3166 ALPHA-2), e.g. de. Upper case is stored in lower case. |
String |
The default country of your account |
| bill_phone | Phone number, 64 characters at most. | String |
"" |
| bill_phone_mobile | Mobile phone number, 64 characters at most. | String |
"" |
| account_bank | Name of the bank, 128 characters at most. | String |
"" |
| account_iban | IBAN, 32 characters at most. | String |
"" |
| account_bic | BIC, 16 characters at most. | String |
"" |
| account_paypal | PayPal address of the supplier, 64 characters at most. It has to be a valid e-mail address. | String |
"" |
| user_note | Note, 1024 characters at most. | String |
"" |
One of the fields bill_company, bill_lastname or bill_email is required: a supplier needs something it can be told apart by.
Code Examples
# 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"<?php
// Get your API credentials from your billware customer area
$apiAppId = 'your-app-id';
$apiSecret = 'your-api-secret';
$payload = json_encode([
'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 = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://www.billware.de/api/v1',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
'X-Bw-Method: supplier.create',
'Content-Type: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));import crypto from 'node:crypto';
// Get your API credentials from your billware customer area
const apiAppId = 'your-app-id';
const apiSecret = 'your-api-secret';
const payload = JSON.stringify({
"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
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');
const response = await fetch('https://www.billware.de/api/v1', {
method: 'POST',
headers: {
'X-Bw-Hmac': `${apiAppId}:${hmac}`,
'X-Bw-Method': 'supplier.create',
'Content-Type': 'application/json'
},
body: payload
});
console.log(await response.json());import base64
import hashlib
import hmac
import json
import requests
# Get your API credentials from your billware customer area
api_appid = "your-app-id"
api_secret = "your-api-secret"
payload = json.dumps({
"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
signature = base64.b64encode(
hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()
response = requests.post(
"https://www.billware.de/api/v1",
data=payload,
headers={
"X-Bw-Hmac": f"{api_appid}:{signature}",
"X-Bw-Method": "supplier.create",
"Content-Type": "application/json",
},
)
print(response.json())using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
// Get your API credentials from your billware customer area
const string apiAppId = "your-app-id";
const string apiSecret = "your-api-secret";
var payload = JsonSerializer.Serialize(new
{
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
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));
using var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
Content = new StringContent(payload, Encoding.UTF8, "application/json")
};
request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "supplier.create");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());Return Values
The answer holds the created supplier with the same structure as supplier.read.
Example Responses
// 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
Get a supplier with its documents.Data
| Fields | Description | Accepted Types |
|---|---|---|
| supplier_ident Required | Ident of the supplier | String |
Code Examples
# 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"<?php
// Get your API credentials from your billware customer area
$apiAppId = 'your-app-id';
$apiSecret = 'your-api-secret';
$payload = json_encode([
'supplier_ident' => 'ckt8w78bfmj54054',
]);
// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://www.billware.de/api/v1',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
'X-Bw-Method: supplier.read',
'Content-Type: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));import crypto from 'node:crypto';
// Get your API credentials from your billware customer area
const apiAppId = 'your-app-id';
const apiSecret = 'your-api-secret';
const payload = JSON.stringify({
"supplier_ident": "ckt8w78bfmj54054"
});
// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');
const response = await fetch('https://www.billware.de/api/v1', {
method: 'POST',
headers: {
'X-Bw-Hmac': `${apiAppId}:${hmac}`,
'X-Bw-Method': 'supplier.read',
'Content-Type': 'application/json'
},
body: payload
});
console.log(await response.json());import base64
import hashlib
import hmac
import json
import requests
# Get your API credentials from your billware customer area
api_appid = "your-app-id"
api_secret = "your-api-secret"
payload = json.dumps({
"supplier_ident": "ckt8w78bfmj54054",
})
# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()
response = requests.post(
"https://www.billware.de/api/v1",
data=payload,
headers={
"X-Bw-Hmac": f"{api_appid}:{signature}",
"X-Bw-Method": "supplier.read",
"Content-Type": "application/json",
},
)
print(response.json())using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
// Get your API credentials from your billware customer area
const string apiAppId = "your-app-id";
const string apiSecret = "your-api-secret";
var payload = JsonSerializer.Serialize(new
{
supplier_ident = "ckt8w78bfmj54054"
});
// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));
using var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
Content = new StringContent(payload, Encoding.UTF8, "application/json")
};
request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "supplier.read");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());Return Values
| Fields | Description |
|---|---|
| supplier_ident | Ident of the supplier |
| supplier_nr | Supplier number |
| supplier_type | Source of the supplier |
| external_ident | Ident of the supplier in your system |
| bill_title | Title as a number, the values are listed at supplier.create |
| bill_* account_* user_note |
Name, address, contact, bank details and note as you sent them |
| date_created date_updated |
Time of creation and of the last change in server time (UTC). A supplier you send again unchanged does not count as changed. |
| files | The documents of the supplier, the oldest first, each as in the answer of supplier.fileUpload. The receipts of its expenses are not part of them, they belong to the expenses. |
Example Responses
// 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
Get multiple suppliers as a list.Data
| Fields | Description | Accepted Types | Defaults To |
|---|---|---|---|
| date_type | The date the period refers to and the list is sorted by, the newest first. | "date_created" "date_updated" |
"date_created" |
| start_date | Start of the period. Format: Y-m-d H:i:s (e.g. "2026-10-01 00:00:00"), compared with the stored times in server time (UTC). With date_type date_updated this gives you everything that has changed since a point in time. A new or deleted document does not change the supplier here. |
String |
|
| end_date | End of the period, in the same format as start_date. |
String |
|
| supplier_nr | Only the supplier with this number. | String |
|
| supplier_type | Only suppliers of this source. | String |
|
| external_ident | Only the supplier with this ident of your system. | String |
|
| bill_email | Only suppliers with this e-mail address. | String |
|
| bill_company | Only suppliers with exactly this company name. | String |
|
| bill_vat_nr | Only suppliers with this VAT number. | String |
|
| bill_country | Only suppliers of this country, as country code. | String |
|
| page | Page of the list. Without it the first page is returned. | Integer |
1 |
| limit | Number of entries per page, from 1 to 100. |
Integer |
25 |
Every field is optional and they can be combined, a supplier then has to match every filter. Without any the list holds all suppliers of your account.
Code Examples
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"<?php
// Get your API credentials from your billware customer area
$apiAppId = 'your-app-id';
$apiSecret = 'your-api-secret';
$payload = json_encode([
'page' => 1,
'limit' => 50,
]);
// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://www.billware.de/api/v1',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
'X-Bw-Method: supplier.list',
'Content-Type: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));import crypto from 'node:crypto';
// Get your API credentials from your billware customer area
const apiAppId = 'your-app-id';
const apiSecret = 'your-api-secret';
const payload = JSON.stringify({
"page": 1,
"limit": 50
});
// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');
const response = await fetch('https://www.billware.de/api/v1', {
method: 'POST',
headers: {
'X-Bw-Hmac': `${apiAppId}:${hmac}`,
'X-Bw-Method': 'supplier.list',
'Content-Type': 'application/json'
},
body: payload
});
console.log(await response.json());import base64
import hashlib
import hmac
import json
import requests
# Get your API credentials from your billware customer area
api_appid = "your-app-id"
api_secret = "your-api-secret"
payload = json.dumps({
"page": 1,
"limit": 50,
})
# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()
response = requests.post(
"https://www.billware.de/api/v1",
data=payload,
headers={
"X-Bw-Hmac": f"{api_appid}:{signature}",
"X-Bw-Method": "supplier.list",
"Content-Type": "application/json",
},
)
print(response.json())using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
// Get your API credentials from your billware customer area
const string apiAppId = "your-app-id";
const string apiSecret = "your-api-secret";
var payload = JsonSerializer.Serialize(new
{
page = 1,
limit = 50
});
// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));
using var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
Content = new StringContent(payload, Encoding.UTF8, "application/json")
};
request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "supplier.list");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());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"<?php
// Get your API credentials from your billware customer area
$apiAppId = 'your-app-id';
$apiSecret = 'your-api-secret';
$payload = json_encode([
'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 = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://www.billware.de/api/v1',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
'X-Bw-Method: supplier.list',
'Content-Type: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));import crypto from 'node:crypto';
// Get your API credentials from your billware customer area
const apiAppId = 'your-app-id';
const apiSecret = 'your-api-secret';
const payload = JSON.stringify({
"date_type": "date_updated",
"start_date": "2026-11-01 00:00:00"
});
// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');
const response = await fetch('https://www.billware.de/api/v1', {
method: 'POST',
headers: {
'X-Bw-Hmac': `${apiAppId}:${hmac}`,
'X-Bw-Method': 'supplier.list',
'Content-Type': 'application/json'
},
body: payload
});
console.log(await response.json());import base64
import hashlib
import hmac
import json
import requests
# Get your API credentials from your billware customer area
api_appid = "your-app-id"
api_secret = "your-api-secret"
payload = json.dumps({
"date_type": "date_updated",
"start_date": "2026-11-01 00:00:00",
})
# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()
response = requests.post(
"https://www.billware.de/api/v1",
data=payload,
headers={
"X-Bw-Hmac": f"{api_appid}:{signature}",
"X-Bw-Method": "supplier.list",
"Content-Type": "application/json",
},
)
print(response.json())using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
// Get your API credentials from your billware customer area
const string apiAppId = "your-app-id";
const string apiSecret = "your-api-secret";
var payload = JsonSerializer.Serialize(new
{
date_type = "date_updated",
start_date = "2026-11-01 00:00:00"
});
// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));
using var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
Content = new StringContent(payload, Encoding.UTF8, "application/json")
};
request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "supplier.list");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());Return Values
The suppliers array contains entries with the same structure as the answer of supplier.read.
Pagination
The response includes metadata to support pagination:
page: The current page number that was requested.limit: The number of entries per page.total: The total number of entries that match the filter.total_pages: The total number of pages available based on the result count and page size.
Use page to walk through the pages and limit to set how many entries a page holds. A page holds 100 entries at most, there is no limit in total: through the pages up to total_pages you reach every entry.
Example Responses
// 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
Update one or more fields of a supplier.Data
| Fields | Description | Accepted Types |
|---|---|---|
| supplier_ident Required | Ident of the supplier | String |
Plus every field of supplier.create you want to change. Only fields you send change, an empty text empties the field. Number, title and country cannot be emptied.
Code Examples
# 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"<?php
// Get your API credentials from your billware customer area
$apiAppId = 'your-app-id';
$apiSecret = 'your-api-secret';
$payload = json_encode([
'supplier_ident' => 'ckt8w78bfmj54054',
'bill_city' => 'Bonn',
'bill_zipcode' => '53111',
]);
// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://www.billware.de/api/v1',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
'X-Bw-Method: supplier.update',
'Content-Type: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));import crypto from 'node:crypto';
// Get your API credentials from your billware customer area
const apiAppId = 'your-app-id';
const apiSecret = 'your-api-secret';
const payload = JSON.stringify({
"supplier_ident": "ckt8w78bfmj54054",
"bill_city": "Bonn",
"bill_zipcode": "53111"
});
// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');
const response = await fetch('https://www.billware.de/api/v1', {
method: 'POST',
headers: {
'X-Bw-Hmac': `${apiAppId}:${hmac}`,
'X-Bw-Method': 'supplier.update',
'Content-Type': 'application/json'
},
body: payload
});
console.log(await response.json());import base64
import hashlib
import hmac
import json
import requests
# Get your API credentials from your billware customer area
api_appid = "your-app-id"
api_secret = "your-api-secret"
payload = json.dumps({
"supplier_ident": "ckt8w78bfmj54054",
"bill_city": "Bonn",
"bill_zipcode": "53111",
})
# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()
response = requests.post(
"https://www.billware.de/api/v1",
data=payload,
headers={
"X-Bw-Hmac": f"{api_appid}:{signature}",
"X-Bw-Method": "supplier.update",
"Content-Type": "application/json",
},
)
print(response.json())using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
// Get your API credentials from your billware customer area
const string apiAppId = "your-app-id";
const string apiSecret = "your-api-secret";
var payload = JsonSerializer.Serialize(new
{
supplier_ident = "ckt8w78bfmj54054",
bill_city = "Bonn",
bill_zipcode = "53111"
});
// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));
using var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
Content = new StringContent(payload, Encoding.UTF8, "application/json")
};
request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "supplier.update");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());Return Values
The answer holds the supplier as it is now, with the same structure as supplier.read.
Example Responses
// 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
Create or update a supplier, in one call. This way you sync the suppliers of your system without storing their idents.billware looks for the supplier in this order:
- by
supplier_identif you send it. If it does not exist, the call answers with an error and creates nothing. - otherwise by
bill_email, - otherwise by
bill_company.
A supplier that is found is changed as with supplier.update, otherwise a new one is created as with supplier.create. An empty text finds nobody. If several suppliers share the e-mail address or company, the one created first is changed.
Code Examples
# 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"<?php
// Get your API credentials from your billware customer area
$apiAppId = 'your-app-id';
$apiSecret = 'your-api-secret';
$payload = json_encode([
'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 = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://www.billware.de/api/v1',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
'X-Bw-Method: supplier.put',
'Content-Type: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));import crypto from 'node:crypto';
// Get your API credentials from your billware customer area
const apiAppId = 'your-app-id';
const apiSecret = 'your-api-secret';
const payload = JSON.stringify({
"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
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');
const response = await fetch('https://www.billware.de/api/v1', {
method: 'POST',
headers: {
'X-Bw-Hmac': `${apiAppId}:${hmac}`,
'X-Bw-Method': 'supplier.put',
'Content-Type': 'application/json'
},
body: payload
});
console.log(await response.json());import base64
import hashlib
import hmac
import json
import requests
# Get your API credentials from your billware customer area
api_appid = "your-app-id"
api_secret = "your-api-secret"
payload = json.dumps({
"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
signature = base64.b64encode(
hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()
response = requests.post(
"https://www.billware.de/api/v1",
data=payload,
headers={
"X-Bw-Hmac": f"{api_appid}:{signature}",
"X-Bw-Method": "supplier.put",
"Content-Type": "application/json",
},
)
print(response.json())using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
// Get your API credentials from your billware customer area
const string apiAppId = "your-app-id";
const string apiSecret = "your-api-secret";
var payload = JsonSerializer.Serialize(new
{
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
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));
using var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
Content = new StringContent(payload, Encoding.UTF8, "application/json")
};
request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "supplier.put");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());Example Responses
// 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
Delete a supplier with its documents. Its expenses stay, they have no supplier afterwards.Data
| Fields | Description | Accepted Types |
|---|---|---|
| supplier_ident Required | Ident of the supplier | String |
Code Examples
# 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"<?php
// Get your API credentials from your billware customer area
$apiAppId = 'your-app-id';
$apiSecret = 'your-api-secret';
$payload = json_encode([
'supplier_ident' => 'ckt8w78bfmj54054',
]);
// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://www.billware.de/api/v1',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
'X-Bw-Method: supplier.delete',
'Content-Type: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));import crypto from 'node:crypto';
// Get your API credentials from your billware customer area
const apiAppId = 'your-app-id';
const apiSecret = 'your-api-secret';
const payload = JSON.stringify({
"supplier_ident": "ckt8w78bfmj54054"
});
// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');
const response = await fetch('https://www.billware.de/api/v1', {
method: 'POST',
headers: {
'X-Bw-Hmac': `${apiAppId}:${hmac}`,
'X-Bw-Method': 'supplier.delete',
'Content-Type': 'application/json'
},
body: payload
});
console.log(await response.json());import base64
import hashlib
import hmac
import json
import requests
# Get your API credentials from your billware customer area
api_appid = "your-app-id"
api_secret = "your-api-secret"
payload = json.dumps({
"supplier_ident": "ckt8w78bfmj54054",
})
# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()
response = requests.post(
"https://www.billware.de/api/v1",
data=payload,
headers={
"X-Bw-Hmac": f"{api_appid}:{signature}",
"X-Bw-Method": "supplier.delete",
"Content-Type": "application/json",
},
)
print(response.json())using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
// Get your API credentials from your billware customer area
const string apiAppId = "your-app-id";
const string apiSecret = "your-api-secret";
var payload = JsonSerializer.Serialize(new
{
supplier_ident = "ckt8w78bfmj54054"
});
// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));
using var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
Content = new StringContent(payload, Encoding.UTF8, "application/json")
};
request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "supplier.delete");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());Example Responses
// SUCCESS
{
"response": true,
"data": null,
"message": "supplier deleted"
}
// ERROR
{
"response": false,
"data": null,
"message": "Supplier not found"
}
supplier.fileUpload
Store a document for a supplier.Data
| Fields | Description | Accepted Types | Defaults To |
|---|---|---|---|
| supplier_ident Required | Ident of the supplier | String |
|
| file_base64 | The content of the file, Base64 encoded. Either file_base64 or file_url, not both. |
String |
|
| file_url | A link billware fetches the file from. https only, and only addresses that are publicly reachable. |
String |
|
| file_name | Name of the file. Without it the document is called like the supplier number, e.g. L-7001.pdf. |
String |
The supplier number |
- A document is a PDF file, an XML file, a file of Word (DOC, DOCX, RTF) or Excel (XLSX), a text file (TXT) or a picture as JPG, PNG or GIF.
- The file is taken by its content, not by its name. A file may be 10 MB at most.
- A file name may hold letters, digits, spaces and
. _ - ( ), 128 characters at most. Its ending has to fit the content: a PDF file is called.pdf. - A supplier can have several documents: every call adds one.
- With
file_urlbillware follows three redirects at most, gives up after 20 seconds and fetches nothing larger than 10 MB.
Code Examples
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"<?php
// Get your API credentials from your billware customer area
$apiAppId = 'your-app-id';
$apiSecret = 'your-api-secret';
$payload = json_encode([
'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 = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://www.billware.de/api/v1',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
'X-Bw-Method: supplier.fileUpload',
'Content-Type: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));import crypto from 'node:crypto';
// Get your API credentials from your billware customer area
const apiAppId = 'your-app-id';
const apiSecret = 'your-api-secret';
const payload = JSON.stringify({
"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
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');
const response = await fetch('https://www.billware.de/api/v1', {
method: 'POST',
headers: {
'X-Bw-Hmac': `${apiAppId}:${hmac}`,
'X-Bw-Method': 'supplier.fileUpload',
'Content-Type': 'application/json'
},
body: payload
});
console.log(await response.json());import base64
import hashlib
import hmac
import json
import requests
# Get your API credentials from your billware customer area
api_appid = "your-app-id"
api_secret = "your-api-secret"
payload = json.dumps({
"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
signature = base64.b64encode(
hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()
response = requests.post(
"https://www.billware.de/api/v1",
data=payload,
headers={
"X-Bw-Hmac": f"{api_appid}:{signature}",
"X-Bw-Method": "supplier.fileUpload",
"Content-Type": "application/json",
},
)
print(response.json())using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
// Get your API credentials from your billware customer area
const string apiAppId = "your-app-id";
const string apiSecret = "your-api-secret";
var payload = JsonSerializer.Serialize(new
{
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
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));
using var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
Content = new StringContent(payload, Encoding.UTF8, "application/json")
};
request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "supplier.fileUpload");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());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"<?php
// Get your API credentials from your billware customer area
$apiAppId = 'your-app-id';
$apiSecret = 'your-api-secret';
$payload = json_encode([
'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 = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://www.billware.de/api/v1',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
'X-Bw-Method: supplier.fileUpload',
'Content-Type: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));import crypto from 'node:crypto';
// Get your API credentials from your billware customer area
const apiAppId = 'your-app-id';
const apiSecret = 'your-api-secret';
const payload = JSON.stringify({
"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
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');
const response = await fetch('https://www.billware.de/api/v1', {
method: 'POST',
headers: {
'X-Bw-Hmac': `${apiAppId}:${hmac}`,
'X-Bw-Method': 'supplier.fileUpload',
'Content-Type': 'application/json'
},
body: payload
});
console.log(await response.json());import base64
import hashlib
import hmac
import json
import requests
# Get your API credentials from your billware customer area
api_appid = "your-app-id"
api_secret = "your-api-secret"
payload = json.dumps({
"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
signature = base64.b64encode(
hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()
response = requests.post(
"https://www.billware.de/api/v1",
data=payload,
headers={
"X-Bw-Hmac": f"{api_appid}:{signature}",
"X-Bw-Method": "supplier.fileUpload",
"Content-Type": "application/json",
},
)
print(response.json())using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
// Get your API credentials from your billware customer area
const string apiAppId = "your-app-id";
const string apiSecret = "your-api-secret";
var payload = JsonSerializer.Serialize(new
{
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
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));
using var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
Content = new StringContent(payload, Encoding.UTF8, "application/json")
};
request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "supplier.fileUpload");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());Return Values
| Fields | Description |
|---|---|
| href | Link to download the file. It works without a login, so pass it on to authorised people only. |
| file_ident | Ident of the file |
| parent_ident | Ident of the record the file belongs to |
| file_user_name | The file name as you sent it |
| file_name | The name billware stores the file under |
| file_extension | Ending of the file, e.g. pdf |
| reference_nr | Number of the record the file belongs to, as it was at the upload |
| date_updated | Time of the upload in server time (UTC) |
Example Responses
// 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
Delete a document of a supplier.Data
| Fields | Description | Accepted Types |
|---|---|---|
| supplier_ident Required | Ident of the supplier | String |
| file_ident Required | Ident of the document, from the answer of supplier.fileUpload or from files of the supplier. |
String |
Code Examples
# 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"<?php
// Get your API credentials from your billware customer area
$apiAppId = 'your-app-id';
$apiSecret = 'your-api-secret';
$payload = json_encode([
'supplier_ident' => 'ckt8w78bfmj54054',
'file_ident' => 'l51gvi7q0su56l44',
]);
// The HMAC is calculated over the exact request body that is sent
$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => 'https://www.billware.de/api/v1',
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $payload,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'X-Bw-Hmac: '.$apiAppId.':'.$hmac,
'X-Bw-Method: supplier.fileDelete',
'Content-Type: application/json',
],
]);
$response = curl_exec($curl);
curl_close($curl);
print_r(json_decode($response, true));import crypto from 'node:crypto';
// Get your API credentials from your billware customer area
const apiAppId = 'your-app-id';
const apiSecret = 'your-api-secret';
const payload = JSON.stringify({
"supplier_ident": "ckt8w78bfmj54054",
"file_ident": "l51gvi7q0su56l44"
});
// The HMAC is calculated over the exact request body that is sent
const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');
const response = await fetch('https://www.billware.de/api/v1', {
method: 'POST',
headers: {
'X-Bw-Hmac': `${apiAppId}:${hmac}`,
'X-Bw-Method': 'supplier.fileDelete',
'Content-Type': 'application/json'
},
body: payload
});
console.log(await response.json());import base64
import hashlib
import hmac
import json
import requests
# Get your API credentials from your billware customer area
api_appid = "your-app-id"
api_secret = "your-api-secret"
payload = json.dumps({
"supplier_ident": "ckt8w78bfmj54054",
"file_ident": "l51gvi7q0su56l44",
})
# The HMAC is calculated over the exact request body that is sent
signature = base64.b64encode(
hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()
response = requests.post(
"https://www.billware.de/api/v1",
data=payload,
headers={
"X-Bw-Hmac": f"{api_appid}:{signature}",
"X-Bw-Method": "supplier.fileDelete",
"Content-Type": "application/json",
},
)
print(response.json())using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
// Get your API credentials from your billware customer area
const string apiAppId = "your-app-id";
const string apiSecret = "your-api-secret";
var payload = JsonSerializer.Serialize(new
{
supplier_ident = "ckt8w78bfmj54054",
file_ident = "l51gvi7q0su56l44"
});
// The HMAC is calculated over the exact request body that is sent
using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));
using var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Post, "https://www.billware.de/api/v1")
{
Content = new StringContent(payload, Encoding.UTF8, "application/json")
};
request.Headers.Add("X-Bw-Hmac", $"{apiAppId}:{signature}");
request.Headers.Add("X-Bw-Method", "supplier.fileDelete");
var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());Return Values
The answer holds the supplier as it is now, with the same structure as supplier.read.
Example Responses
// SUCCESS
{
"response": true,
"data": {
"supplier_ident": "ckt8w78bfmj54054",
"files": [],
...
},
"message": "File deleted"
}
// ERROR
{
"response": false,
"data": null,
"message": "File not found"
}