# Partner Platform API v3
This page describes use cases and endpoints around the anybill Partner Platform API.
# Bill Api
The bill controller contains three endpoints which can be used to retrieve bills.
# Endpoints
- GET
bill/{billId}
- GET
bill/
- GET
bill/{billId}/pdf
# Detailed Endpoint Description
- For Staging Environment: SwaggerUI (opens new window)
- For Production Environment: SwaggerUI (opens new window)
# Bill Object
WARNING
The exact description of the bill model can be found in the swagger documentation.
The bill object is based on the dfka standard. As root object of the bill it links to five different categories of data:
- Cash register Contains data about the cash register. Currently only the serial number of the cash register is in the object.
- Head Contains common data of the head of a bill. E.g. invoice number, date, seller or buyer information.
- Data Contains the most important information for the buyer. The items he has bought and the value of the shopping cart.
- Security Data to secure the receipt via TSE.
- Misc Optional additional data.
For better understanding some attributes are descibed below.
# Lines
There are three types of lines. The type of the line is determined with the type
-discriminator in the extension of the line. Possible discriminators:
default
or no value (null
) for default linestext
for text only linesdiscount
for discount line
# Default line
The default line represents an item or service that was sold. You can add useful information in the additionalText
.
# Text line
The text line can be used to add text in between other lines. This can be as easy as a product group seperation or further useful information.
# Discount line
The discount line displays a discount that is applied to the whole receipt.
# Possible QuantityMeasure values:
The quantity measure describes the type of quantity of the line item.
Name | Value |
---|---|
Count | 0 |
Kilogram | 1 |
Lbs | 2 |
Meters | 3 |
Inches | 4 |
Liter | 5 |
CubicMeters | 6 |
SquareMeters | 7 |
# Possible CurrencyCode values:
For the currency, the 3-digit ISO 4217 (opens new window) standard is used.
# Discounts:
A discount can either be set to each line item individually or to the whole bill.
# Get bill
To retrieve a bill with an existing billId, use the GET /api/v3/bill/{billId}
endpoint.
# Detailed Endpoint Description
- For Staging Environment: SwaggerUI (opens new window)
- For Production Environment: SwaggerUI (opens new window)
# Get bills
To retrieve a list of bills, use the GET /api/v3/bill
endpoint. the body of the request needs a list of billIds.
GET /api/v3/bill
[
"3fa85f64-5717-4562-b3fc-2c963f66afa6",
"a2185f64-5717-4562-b3fc-2c963f66afb3"
]
The response returns a list of Bills. If a BillId could not be found, it will be ignored.
# Detailed Endpoint Description
- For Staging Environment: SwaggerUI (opens new window)
- For Production Environment: SwaggerUI (opens new window)
# Get bill as PDF
To retrieve the pdf of a bill, use the GET /api/v3/bill/{billId}/pdf
endpoint.
# Detailed Endpoint Description
- For Staging Environment: SwaggerUI (opens new window)
- For Production Environment: SwaggerUI (opens new window)
# Category Api
The category controller contains two endpoints which can be used to retrieve categories.
# Endpoints
- GET
category
Get all categories - GET
category/{categoryId}
Get category
# Detailed Endpoint Description
- For Staging Environment: SwaggerUI (opens new window)
- For Production Environment: SwaggerUI (opens new window)
# Onboarding Api
The onbaording controller contains two endpoints which can be used to create a new customer automatic from the POS systems. The seconds endpoint can be used to check if the customer finished the onboarding.
# Endpoints
POST
onboarding
Send master data to the anybill system for automatic onboardingGET
onboarding/vendorCustomerId/{vendorCustomerId}
Customer is activatedIf the customer finished the onboarding successfull, the HTTP status code
200 Ok
is returned with aCustomerActivatedDto
response.
{
"type": "activated",
"customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
- If the customer did not finish the onboarding, the HTTP status code
200 Ok
is returned with aCustomerNotActivatedDto
response. This means that the customer can not send receipts via the bill endpoints.
{
"type": "notActivated",
"customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
# Detailed Endpoint Description
- For Staging Environment: SwaggerUI (opens new window)
- For Production Environment: SwaggerUI (opens new window)
# Test Api
The Test Controller contains an endpoint that allows developers to send a push notification for testing purposes. Push notifications can be sent for the following types:
- WarrantyNotification - Warranty reminder push notification is sent out
Body Parameters for the warranty notification
{
"type": "WarrantyNotification",
"deviceToken": "<device_token>"
}
- FinoSyncNotification - Fino account must be synced push notification is sent out
Body Parameters for the warranty notification
{
"type": "FinoSyncNotification",
"deviceToken": "<device_token>",
"bankId": "<bank_id>"
}
# Detailed Endpoint Description
- For Staging Environment: SwaggerUI (opens new window)
- For Production Environment: SwaggerUI (opens new window)
WARNING
This endpoint is for developer testing purposes only.
# User Api
For your user to access their anybill bills they first and foremost need an anybill account. Many organizations do not want their users to first create a dedicated anybill account to get started. That's where the anybill Partner Platform API comes into play!
We provide an endpoint that lets you (as an organization) create anonymous anybill users. Anonymous anybill users do not require to fill out a form with login information and so forth. Instead, you can create an anonymous anybill user on behalf of your user and give them access to the anybill services without much hassle. With these anybill users you are able to talk to our anybill App Api which provides most of our basic functionality like adding bills.
# Basic Workflow
The workflow for creating an anonymous anybill user works as following:
- Request anonymous anybill account using the anybill Partner Platform API from your backend.
- An anonymous anybill account is returned.
- Return this anonymous anybill account to your client application.
- Use the anybill App API using the anonymous anybill account login information provided.

# Create an anonymous account
To create an anonymous anybill account call the POST /api/v3/user
endpoint.
If the optional property loyaltyCards
is provided in the requests body, multiple loyalty cards will be created for the user. The loyalty cards will be associated to the vendor creating the user and containing the provided barcodes. The property loyaltyCards
can contain multiple loyalty cards for one user. Loyalty cards can be managed with the /api/v3/user/{userId}/loyaltycard
endpoints.
# Detailed Endpoint Description
- For Staging Environment: SwaggerUI (opens new window)
- For Production Environment: SwaggerUI (opens new window)
POST /api/v3/user - request body
{
"loyaltyCards": [
{
"code": "<barcode>",
"name": "<name of loyalty card>"
}
],
"firstname": "<first name of user>",
"lastname": "<last name of user>",
"externalId": "<external id user>"
}
POST /api/v3/user - response
{
"id": "9632d033-b25d-47c0-8aa9-85babec64969",
"accessToken": "*****",
"refreshToken": "*****",
"expiresIn": "86400"
}
The response consists of a anybill AppUser id
, accessToken
, refreshToken
and expiresIn
for authentication.
The access_token is 86400 seconds (24 hours) valid and can be updated with the refresh_token, which is valid for 90 days.
WARNING
If only the id
was returned, no AccessToken could be requested. In this case a token must be requested independently via GET /api/user/{userId}/token
.
WARNING
The returned anonymous AppUser is bound to your organization. Only your organization is allowed to delete AppUser created from your organization.
# Deleting an anonymous account
If your anybill account is not needed anymore you can delete it using the DELETE /api/user/{userId}
endpoint.
# Detailed Endpoint Description
- For Staging Environment: SwaggerUI (opens new window)
- For Production Environment: SwaggerUI (opens new window)
# Getting user information of an user
You can use the GET /api/v3/user/{userId}
endpoint to query information about a specific user.
The response contains information of the anybill user.
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"email": "string",
"firstname": "string",
"lastname": "string",
"birthday": "2021-05-27T09:59:58.167Z",
"gender": "string"
}
# Detailed Endpoint Description
- For Staging Environment: SwaggerUI (opens new window)
- For Production Environment: SwaggerUI (opens new window)
# Deleting an anonymous account
Requests a new authentication token for an anonymous app user using the GET /api/user/{userId}/token
endpoint.
# Detailed Endpoint Description
- For Staging Environment: SwaggerUI (opens new window)
- For Production Environment: SwaggerUI (opens new window)
# Get appUsers QR-Code data
Gets JSON data to display a appUsers QR code at a POS using the GET /api/user/{userId}/qr
endpoint.
The response contains JSON data for the QR code.
{
"userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"actions": [
"string"
]
}
# Detailed Endpoint Description
- For Staging Environment: SwaggerUI (opens new window)
- For Production Environment: SwaggerUI (opens new window)
# Changelog
Changes to the V3 Api will be documented here.
# 2022-04-01
- Added new documenation for the onboarding endpoints.