billware API | Documentation / Authentication

Authentication

Request

All methods use the same endpoint. The header X-Bw-Method determines which function is executed. Every call is sent as a POST request with the payload in the request body – including read methods such as order.read or order.list.

Endpoint

URL	`https://www.billware.de/api/v1`
Method	`POST`
`X-Bw-Method`	Name of the method, e.g. `order.create`
`X-Bw-Hmac`	API-Appid, a colon and the calculated HMAC, e.g. `appid:hmac`
`Content-Type`	`application/json`

authentication

Every API call is authenticated with a HMAC header based on the payload. Below is an example showing how to generate the header. Also refer to the test.connection method which generates and uses the header.

Code Examples

# Get your API secret from your billware customer area
API_SECRET="your-api-secret"

# Sign the exact body that will be sent – not a re-encoded copy of it
PAYLOAD='{"foo":"bar"}'

HMAC=$(printf '%s' "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_SECRET" -binary | base64)

# X-Bw-Hmac is the API-Appid, a colon and the HMAC
echo "your-app-id:$HMAC"

<?php

// Get your API secret from your billware customer area
$apiSecret = 'your-api-secret';

// Sign the exact body that will be sent – not a re-encoded copy of it
$payload = json_encode(['foo' => 'bar']);

$hmac = base64_encode(hash_hmac('sha256', $payload, $apiSecret, true));

// X-Bw-Hmac is the API-Appid, a colon and the HMAC
$header = 'your-app-id:'.$hmac;

import crypto from 'node:crypto';

// Get your API secret from your billware customer area
const apiSecret = 'your-api-secret';

// Sign the exact body that will be sent – not a re-encoded copy of it
const payload = JSON.stringify({ foo: 'bar' });

const hmac = crypto.createHmac('sha256', apiSecret).update(payload).digest('base64');

// X-Bw-Hmac is the API-Appid, a colon and the HMAC
const header = `your-app-id:${hmac}`;

import base64
import hashlib
import hmac
import json

# Get your API secret from your billware customer area
api_secret = "your-api-secret"

# Sign the exact body that will be sent – not a re-encoded copy of it
payload = json.dumps({"foo": "bar"})

signature = base64.b64encode(
    hmac.new(api_secret.encode(), payload.encode(), hashlib.sha256).digest()
).decode()

# X-Bw-Hmac is the API-Appid, a colon and the HMAC
header = f"your-app-id:{signature}"

using System.Security.Cryptography;
using System.Text;
using System.Text.Json;

// Get your API secret from your billware customer area
const string apiSecret = "your-api-secret";

// Sign the exact body that will be sent – not a re-encoded copy of it
var payload = JsonSerializer.Serialize(new { foo = "bar" });

using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiSecret));
var signature = Convert.ToBase64String(hmac.ComputeHash(Encoding.UTF8.GetBytes(payload)));

// X-Bw-Hmac is the API-Appid, a colon and the HMAC
var header = $"your-app-id:{signature}";

test.connection

You can test your connection. Call the method test.connection with your calculated X-Bw-Hmac header.

Code Examples

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

PAYLOAD='[]'

# 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: test.connection" \
  -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 = '{}';

// 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: test.connection',
        '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({});

// 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': 'test.connection',
        '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({})

# 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": "test.connection",
        "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 { });

// 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", "test.connection");

var response = await client.SendAsync(request);

Console.WriteLine(await response.Content.ReadAsStringAsync());

Postman Example


// Pre-request Script in Postman

const payload = JSON.stringify({});
const apiAppId = APP_ID; // Replace with your actual API App ID
const apiSecret = API_SECRET; // Replace with your actual API Secret

const encoder = new TextEncoder();
const keyData = encoder.encode(apiSecret);
const data = encoder.encode(payload);

crypto.subtle.importKey(
    'raw',
    keyData,
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
).then(key => {
    return crypto.subtle.sign('HMAC', key, data);
}).then(signature => {
    const hmacBase64 = btoa(String.fromCharCode(...new Uint8Array(signature)));

    pm.request.headers.add({
        key: 'X-Bw-Hmac',
        value: `${apiAppId}:${hmacBase64}`
    });

    pm.request.headers.add({
        key: 'X-Bw-Method',
        value: 'test.connection'
    });

    pm.request.headers.add({
        key: 'Content-Type',
        value: 'application/json'
    });
});

Note

In the Body tab, set the type to raw and select JSON as the format. Enter {} as the content.

The data in the Body must be identical to the data used in the Pre-request Script to ensure the HMAC signature is valid.

Response

{
    "response": true,
    "data": null,
    "message": "Connection test success"
}