https://sandbox.billwerk.com/api/v1/for the test system respectively
https://app.billwerk.com/api/v1/for the live system. Please note that the OAuth endpoint and some client-facing endpoints such as file download are not under
400 Bad Requestresponse.
422 Unprocessable Entityresponse.
404 Not Foundresponse.
curl -H "Authorization: Bearer OAUTH-TOKEN" https://app.billwerk.com/api/v1/...
client_secret, which can be used to retrieve an access token directly. This is the recommended approach if you want to query the billwerk API in response to webhooks or otherwise connect your web-based application to billwerk, because it decouples your API from your own frontend login and it does not run in any kind of user context.
client_secretwhich can be used to retrieve an access token in this way.
client_secretsecurely. Such applications are called 'public' OAuth clients.
POST /oauth/token/ Content-Type: application/x-www-form-urlencoded Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ= grant_type=client_credentials
Here, the Basic authorization consists of the
client_secret. Please note that
MUST NOT be specified in the request body because it's already contained in the Basic authorization header.
POST /oauth/token/ Content-Type: application/x-www-form-urlencoded grant_type=password&username=YOUR-USER-NAME&password=YOUR-PASSWORD&client_id=YOUR-CLIENT-ID
Please note that
username is the e-mail address of a billwerk user,
password is the user's password and
is the id of your app which must be registered with billwerk before use. Hence, the
requires the user to share his
password with you (2-legged OAuth).
username:password. For example, a user
foobarwould use the following header:
firstname.lastname@example.org:foobar | Concatenated username and password am9obi5kb2VAZXhhbXBsZS5jb206Zm9vYmFy | Base64 encoded Authorization: Basic am9obi5kb2VAZXhhbXBsZS5jb206Zm9vYmFy | HTTP HeaderIn the client credentials grant, this boils down to
// client_id:client_secret 51efffb9eb596a2c2cb17aee:9b9b8cfd45d32e5153e7deecfee7fc44 // base64 encoded: NTFlZmZmYjllYjU5NmEyYzJjYjE3YWVlOjliOWI4Y2ZkNDVkMzJlNTE1M2U3ZGVlY2ZlZTdmYzQ0 // formatted as HTTP Authorization header Authorization: Basic NTFlZmZmYjllYjU5NmEyYzJjYjE3YWVlOjliOWI4Y2ZkNDVkMzJlNTE1M2U3ZGVlY2ZlZTdmYzQ0
grant_types, specifically those required in 3-legged OAuth (3LO) where the user doesn't have to share his credentials with 3rd parties are planned.
takeparameters. However, skip/take pagination has some disadvantages:
skipis limited to 1000 elements, because the operation is rather expensive
https://app.billwerk.com/api/v1/contracts/?from=50f6b3d7eb596a1268f5651eThese cursors are stable and much faster than skips.
HTTP/1.1 200 OK [...] X-RateLimit-Limit: 10000 X-RateLimit-Remaining: 9954If you hit a rate limit you'll receive the
429 Too many requestserror.
HTTP/1.1 429 Too Many Requests [...] X-RateLimit-Limit: 10000 X-RateLimit-Remaining: 0
ETagheader. You can use the values of these header to make subsequent PUT / PATCH requests to those resources using an
If-Matchheader. If the resource changed meanwhile, the server will return a
412 Precondition Failed. Currently validation is done for the resources Customer and Contract. This validation will be extended to other resources in the future.
All data must be UTF-8 encoded JSON.
|decimal (json: number)||
A high-precision floating point value. Note: these will not be normalized.
For example, a price of "1.000" will be printed on your invoice with three decimal
places, even if the invoice is in a currency that usually has only two decimals, and even
though "1.000" has the same numerical value as "1". This allows for very fine-grained
control (for example if the products you sell are traded with another decimal of precision),
but can make your invoices look awkward if you perform normalization, i.e. if you supply
"1.34", "121.99" and "353" in a single document. The automatically calculated values, such
Also, please note that fractional usage periods in contract management will always be rounded to 6 decimal digits.
|Ids||Ids are either globally unique identifiers, truncated SHA1-hashes or other hexadecimal strings. You should treat these as opaque strings.|
|BearerType||A type of transmission channel. Must be one of:
|Currency||Three-letter currency code according to ISO 4217, e.g.
|Country||Two-letter country code according to ISO 3166-1 alpha-2, e.g.
|DateTime||Date and time are represented as ISO 8601 string, i.e. in the format