The anybill API

Getting Started

For integrating anybill into a POS software system a few simple steps are required:

1. Have a look at the legal requirements
   For information about legal requirements click here.

2. Integrate authentication
   Each POS software provider receives a clientId assigned to him and credentials for every vendor. Have a look at the authentication documentation for more information.

3. Integrate the Bill endpoint
   There are four options for sending bills digitally:

Display of a QR Code on a customer display (preferred solution)
	By scanning the QR-Code from a customer- or terminal display the user can receive the receipt directly by using an App or the smartphone camera and will then get directed to an website where the receipt can be downloaded as a PDF. Therefore the receipt data has to be sent to the bill endpoint of the Vendor API. It will return a link which then has to be displayed with an QR-Code on the terminal or customer display.
With an enabled Bank card
	The new Vendor API v3 is able to send an receipt directly to a user by using the banking card as an identifier. Therefore the POS System has to send every receipt to the bill endpoint of the Vendor API. anybill then can identify the user and will match the receipt to the user account.
With the existing Loyaltycard of the retailer
	Every existing loyalty card system of a retailer can be enriched with all the anybill features e.g. digital receipts. Therefore the loyalty card ID has to be sent to the bill endpoint of the Vendor API.
Scan of the QR Code in an app
	The receipt is transferred by reading the user ID out of the QR-Code which is displayed in an App. The user ID will be sent to the api together with the receipt data via thebill endpoint.

4. Create a Screen for showing the receipt with a QR Code on a customer display
   Note the Template for the Customer Display.

5. Integrate Store Management
   To automatically manage and sync all stores of an vendor the Store API can be used.

6. Integration Review
   After finishing the integration, anybill will review it.
   More information about the review

Retry Policy Guidelines

To ensure the reliable and consistent delivery of digital receipts, we recommend that all partners implement a robust retry policy when interacting with our API. This policy helps manage temporary network issues and ensures that receipts are processed successfully.

When to Retry

• Retry on 5XX Status Codes:

  • These status codes indicate temporary server issues:
    • 500: Internal Server Error
    • 502: Bad Gateway
    • 503: Service Unavailable
    • 504: Gateway Timeout
  • Implement a retry mechanism for these codes using an exponential backoff strategy with jitter to avoid overwhelming our servers.

• Do Not Retry on 4XX Status Codes:

  • These status codes indicate client-side errors and should not trigger retries:
    • 400: Bad Request
    • 401: Unauthorized
    • 403: Forbidden
    • 404: Not Found
    • 409: Conflict

Retry Strategy

• Exponential Backoff with Jitter:
  • Start with a base delay of 1 second.
  • Use an exponential backoff formula: wait_time = base_delay * (2^retry_attempt) * random(0.5, 1.5).
  • Cap the maximum delay at 30 seconds.
  • Retry up to 3 to 5 times before logging the final failure.

Idempotency

Ensure that all receipt submission requests are idempotent, meaning that multiple retries of the same request should not result in duplicate receipts or inconsistent state.

Logging

We recommend logging each retry attempt, capturing the response status code, the time of the attempt, and the reason for the retry. This will assist in troubleshooting and improving integration reliability.

By following these guidelines, you can help ensure smooth and efficient interaction with our API, minimizing disruptions and enhancing the overall user experience.

Postman

A Postman collection can be found here. There are also Environments for Staging and Production

To acquire an access_token first set your credentials for the following collection variables:

• username
• password
• client_id

After your credentials are set, send a request with the GetToken request. The acquired access token will automatically be set for all requests in the collection. Choose the environment and you are good to go.

License

The anybill vendor API v3 data model builds upon the DFKA e.V. EKaBS-Json-Scheme. This scheme is licenced under the Creative Commons Licence CC BY-SA 4.0.

This results in the following rights for the user: The EKaBS-JSON schema and the documentation may be reproduced, redistributed, modified and used in any form as long as the reference to the DFKA e.V. as licensor is kept and modifications are only passed on under the same conditions.