Billwerk+ Transform employs the REST architectural style to interact with its services and resources. Here's a breakdown of how REST is utilized:

Accessing API Documentation

For detailed API specifications, refer to our Swagger documentation for both sandbox and production environments:

• Swagger JSON for Sandbox
• Swagger JSON for Production

You can access these links to explore the full list of available API endpoints, request and response models, and other relevant details or to generate API clients

JSON:

All data sent to and received from the Billwerk+ Transform API is formatted as JSON (JavaScript Object Notation), a lightweight, text-based, and human-readable data interchange format. It's also easy for machines to parse and generate, making it a suitable choice for RESTful interactions.

HTTP Verbs

We strive to use HTTP verbs as appropriately as possible. Accordingly, we support the following verbs:

• GET: Retrieves the resource.
• POST: Used to create resources (as long as their future location is determined by the server).
• PUT: Used for replacing objects or collections.
• DELETE: Used to delete resources (items or collections).
• PATCH: Used to update parts of an object. In contrast to PUT, it will only change the passed fields.

Response Codes:

The API uses standard HTTP response codes to indicate the success or failure of a request:

• 2xx (Success): The request was successfully received, understood, and accepted (e.g., 200 OK, 201 Created).
• 4xx (Client Error): The request contains bad syntax or cannot be fulfilled due to client-side issues (e.g., 400 Bad Request, 404 Not Found).
• 5xx (Server Error): The server failed to fulfil a seemingly valid request (e.g., 500 Internal Server Error).

For more details about response codes you can find here.

By adhering to the REST principles and utilizing JSON for data exchange, standard HTTP methods for actions, and HTTP response codes for status reporting, Billwerk+ Transform ensures a robust, scalable, and intuitive API that developers can interact with efficiently and effectively.

Rate Limiting

HTTP/1.1 200 OK
[...]
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9954

HTTP/1.1 429 Too Many Requests
[...]
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 0

Currently, we impose limits on the rate of API requests. The rate limits are conveyed in the HTTP headers of the response.

If you reach the rate limit, you will receive a 429 error indicating "Too many requests".

Conditional Requests

Most responses from the Billwerk+ Transform API return an ETag header. The values of these headers can be used to make subsequent PUT / PATCH requests to those resources using an If-Match header. If the resource has changed in the meantime, the server will return a 412 Precondition Failed status. Currently, validation is performed for the resources Customer and Contract. This validation will be extended to other resources in the future.

Timestamp Format

Our API expects and returns timestamps in the ISO 8601 format (YYYY-MM-DDTHH:MM:SS.sssssssZ).

Features/Add-ons

Billwerk offers various functionalities to manage your subscriptions. Some of this functionality is available only after activation by our support team. Please contact support if you would like to use the endpoint marked with [Feature] discriminator