# 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

# 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 lines
  • text for text only lines
  • discount 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

# 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

# Get bill as PDF

To retrieve the pdf of a bill, use the GET /api/v3/bill/{billId}/pdf endpoint.

# Detailed Endpoint Description

# 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

# 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 onboarding

  • GET onboarding/vendorCustomerId/{vendorCustomerId} Customer is activated

  • If the customer finished the onboarding successfull, the HTTP status code 200 Ok is returned with a CustomerActivatedDto 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 a CustomerNotActivatedDto 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

# 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

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:

  1. Request anonymous anybill account using the anybill Partner Platform API from your backend.
  2. An anonymous anybill account is returned.
  3. Return this anonymous anybill account to your client application.
  4. Use the anybill App API using the anonymous anybill account login information provided.
anonymous anybill users workflow

# 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

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

# 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

# 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

# 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

# Changelog

Changes to the V3 Api will be documented here.

# 2022-04-01

  • Added new documenation for the onboarding endpoints.

← Webhooks →