# Vendor API v2

This document describes the usage of the anybill vendor REST API V2.

# Bill Api

# Endpoints

The bill controller offers two routes which can be used to add bills into the anybill system:

  • POST bill/user/{userId}
  • POST bill

The bill/user/{userId}-route can be used to add a bill for a registered user. This is the case if the QR-Code provided by the app gets scanned at POS. For a better description of the structure of the QR-Code have a look here.

The bill-route can be used to add an anonymous bill. This is the case if the customer does not scan his QR-Code at the POS. This route enables the vendor to issue a digital receipt to the customer. A JSON-Object which contains a url retrieve the receipt will be returned.

Example:

{ "url": "https://path-to-receipt.anybill.de/{receiptId}" }

As seen in the open api specification, the respective store from which the receipt is to be issued must have already been added via the Store API or the anybill Partner Portal.

# Detailed Endpoint Description

for Staging Environment: SwaggerUI(opens new window)
for Production Environment: SwaggerUI(opens new window)

# Description of possible values

For better understanding some values are descibed below.

Values for enumerations like QuantityType, PriceModifier or TenderType can be the integer value or the string equivalent, whereas integers are prefered. The descriptions always show the integer value and the string equivalent/meaning of the value.

# Possible QuantityType values:

The quantity type describes the type of quantity of the line item. For bananas, whose price is often measured by weight, you would choose 1 (kilogram) and for t-shirts that are sold per unit you would choose 0 (count).

Name Value
Count 0
Kilogram 1
Lbs 2
Meters 3
Inches 4
Liter 5
CubicMeters 6
SquareMeters 7

Example 1:

qantityType: "Count"

Example 2:

quantityType: 3

# TenderTypes

The tender type describes the legal tender used in the tender object. The type used should be specified more with the detailedType-property. E.g. for a payment with visa the tender type should be 3 (credit card) and detailed type should be "Visa". The detailed type should be human readable and will be displayed for the user.

# Possible TenderType values:

Name Value
Miscellaneous 0
Cash 1
DirectDebit 2
CreditCard 3
OnlinePayment 4
GiftCard 5
BankTransfer 6
Check 7
LoyaltyCard 8

Example 1:

tenderType: "Cash"

Example 2:

tenderTypeId: 8

For every tender type, except for miscellaneous, additional details can be provided in the paymentDetails-property. For the cash tender type the CashPaymentDetails-object can be optionally used. Any details given, that do not match the correct tender type will be ignored.

Tender of type Check
{
  "TenderType": "Check",
  "CurrencyCode": "EUR",
  "Amount": 112.90,
  "PaymentDetails": {
    "Drawee": "The person in whose favour the cheque",
    "Payee": "Person who receives payment",
    "DateOfIssue": "Date and Time in iso 8601",
    "Drawer": "The one who has written out the cheque",
    "SortCode": "",
    "AccountNumber": ""
  }
} 
Tender of type BankTransfer
{
  "TenderType": "BankTransfer",
  "DetailedType": "Bank XY Transfer",
  "CurrencyCode": "EUR",
  "Amount": 112.90,
  "PaymentDetails": {
    "PurposeOfUsage": "Some usage description",
    "Iban": "DE 1234",
    "bic": "1342",
    "accountHolderName": "MS Pos GmbH",
    "accountNumber": "1234",
    "bankName": "Bank Name",
    "bankAddress": "Some Address",
    "sortCode": "1234",
    "routingNumber": "abcd",
    "ifscCode": "1234",
    "routingCode": "abcd",
    "terminalId": "1234",
    "terminalText": "Some for Example Legal Text from the terminal",
    "transactionNumber": "abcd"
  }
} 
Tender of type Cash
{
  "TenderType": "Cash",
  "CurrencyCode": "EUR",
  "Amount": 112.90,
  "PaymentDetails": {
    "AmountGiven": 120.00,
    "AmountReturned": 17.10
  }
} 
Tender of type CreditCard
{
  "TenderType": "CreditCard",
  "DetailedType": "Visa",
  "CurrencyCode": "EUR",
  "Amount": 112.90,
  "PaymentDetails": {
    "CardNumber": "123456",
    "BankName": "Some Bank",
    "TerminalId": "1234",
    "TerminalText": "Some for Example Legal Text from the terminal",
    "TransactionNumber": ""
  }
} 
Tender of type DirectDebit
{
  "TenderType": "DirectDebit",
  "CurrencyCode": "EUR",
  "Amount": 112.90,
  "PaymentDetails": {
    "SepaCreditorId": "",
    "SepaMandateReference": "",
    "CardNumber": "",
    "BankName": "",
    "TerminalText": "Some for Example Legal Text from the terminal"
  }
} 
Tender of type GiftCard
{
  "TenderType": "GiftCard",
  "CurrencyCode": "EUR",
  "Amount": 112.90,
  "PaymentDetails": {
    "InitialBalance": 200.00,
    "RemainingBalance": 87.10,
    "DateOfExpiry": "Date and Time in iso 8601"
  }
} 
Tender of type LoyaltyCard
{
  "TenderType": "LoyaltyCard",
  "DetailedType": "Shop XY Card",
  "CurrencyCode": "EUR",
  "Amount": 112.90,
  "PaymentDetails": {
    "Name": "MS-Pos Loyalty Card",
    "AccountNumber": "21341234",
    "PointsUsed": 11290.0,
    "PointsLeft": 1293403.0,
    "PointsGained": 32.0
  }
} 
Tender of type OnlinePayment
{
  "TenderType": "OnlinePayment",
  "DetailedType": "Paypal",
  "CurrencyCode": "EUR",
  "Amount": 112.90,
  "PaymentDetails": {
    "SenderAccountName": "CSymeoudakis@mspos.net",
    "RecipientAccountName": "tobias.gubo@anybill.de",
    "TransactionId": "1293403"
  }
} 

# Terminal text

The TerminalText attribute is available on every card tender type. It has to be filled with the payment information text which is provided by the terminal. This is an example of the terminal text:

Terminal text example

Terminal-ID :   61400710
TA-Nr 000584    BNr 0062

     Kartenzahlung
    Visa kontaktlos
          Visa

EUR 10,00
 
PAN     ############2515
Karte 0
EMV-AID   A0000000031010
VU-Nr             123456
Genehmigungs-Nr   123456
Datum 19.02.20 15:38 Uhr
EMV-Daten
0000000000/0000///

# Possible CurrencyCode values:

To specify the currency, the 3-digit ISO 4217(opens new window) standard is used. Any currency codes that do not match the standard will result in a invalid response.

Example:

currencyCode: "EUR"

# Display a discount:

A discount can be set to each line item individually. The optional properties discountValue, priceModifier and unitOriginalGrossPrice can be used to describe the discount.

Possible Values for priceModifier:

Name Value Description
None (default) 0 No discount gets applied.
Percentage 1 A discount of a specific percentage gets applied. E.g. 20 %
Monetary 2 The line item gross unit price is reduced by a certain amount. E.g. reduced by 2€ based on the original price per unit.
MonetaryReplacement 3 The line item price is reduced to a certain price. E.g. original price: 4€ price now: 3€

Example 1:

unitOriginalGrossPrice: 100.0
unitGrossPrice: 80.0
priceModifier: 1
discountValue: 20

=> A 20 % discount was applied to this line item.

Example 2:

unitOriginalGrossPrice: 2.99
unitGrossPrice: 2.39
priceModifier: 2
discountValue: 0.60

=> A 0.30 € discount was applied to this line item.

Example 3:

unitOriginalGrossPrice: 14.99
unitGrossPrice: 9.99
priceModifier: 3
discountValue: 5

=> The price of this line item was reduced from 14.99 € to 9.99 €.

# Discount for whole bill

To discount a bill fill the discounts array property of the bill. It is possible to apply multiple discounts for a bill. Each discount should provide the following information:

  • name: The name of the discount as shown to the user.
  • value: The subtracted amount in the actual currency. Required.
{
  "lineItems": [...],
  "date": "2020-06-19T06:03:37.900Z",
  "totalGrossAmount": 2.70
  ...
  "discounts": [
     {
        "name": "10% off",
        "value": 0.30
     }
  ]
} 

# Returning a line item:

If you want to return a bills line item the following steps are necessary:

  • Given an existing bill A with a line item A1.
  • Create a new bill B with an extra line item B1 which represents the returned line item A1.
  • Set the property returnBarcodeReference of line item B1 to the value of property returnBarcode of bill A.
  • Save bill B.

A line item is then displayed as "returned" in bill B.

Example

Bill A:

{
  "storeId": "8192538C-CC23-488B-B35B-0F16BE1B8F43",
  "bill": {
      "date": "2020-06-20T13:00:00+00:00",
      "returnBarcode": "123",
      "lineItems": [
         { "name": "A1", "quantity": 1, "unitGrossPrice": 1.00 },
         { "name": "A2", "quantity": 3 }
      ]
   } 
}

Bill B:

{
  "storeId": "8192538C-CC23-488B-B35B-0F16BE1B8F43",
  "bill": {
      "date": "2020-06-20T15:00:00+00:00",
      "lineItems": [
         {
            "name": "B1",
            "quantity": 1,
            "unitGrossPrice": -1.00,
            "returnBarcodeReference": "123" // see returnBarcode of Bill A
         }
      ]
   } 
}

# Store Api

These endpoints are used to manage the stores of a vendor. This can also be done on the anybill Partner Portal.
The most important usecase of these endpoints is to enable larger companies to automate the process of syncing store details.

# Endpoints

  • GET store
  • POST store
  • GET store/{id}
  • DELETE store/{id}
  • GET store/{id}/history

# Detailed Endpoint Description

for Staging Environment: SwaggerUI(opens new window)
for Production Environment: SwaggerUI(opens new window)

# Category Api

These endpoints list all categories which are available to categorize the line items and the bill.

# Endpoints

  • GET category
  • GET category/{id}

# Detailed Endpoint Description

for Staging Environment: SwaggerUI(opens new window)
for Production Environment: SwaggerUI(opens new window)

# Category FAQ

# Can I add my own Category?

For now, the answer is unfortunately no. The problem with own categories is that we have to display the categories with icons in a unified manner inside the app. However, we are working on the functionality that our API automatically matches the provided line items to the categories by using the ean number. This way no categories have to be provided. Stay tuned!

# Smart Couponing Api

With the anybill Smart Couponing Api all sorts of coupons can get activated digitally and directly at the Point of Sale. Therefore we provide the following endpoints:

# Endpoints

  • GET coupon/{userId}

# Detailed Endpoint Description

for Staging Environment: SwaggerUI(opens new window)
for Production Environment: SwaggerUI(opens new window)

# The anybill Smart Coupon

The following chart shows how a smart coupon is returned by our backend as response. anybill smart couponing

Download as Microsoft Visio File

Download as PDF

# Coupon

The base class of the coupon. The properties conditions and scopes consist of an array of links which can be the basic operators and and or. With these links the activation and scope logic is built.

# Activation Condition

This abstract class is parent of all available conditions.
The activation conditions define under which conditions the coupon gets activated.

ValueCondition

Is true if the value of the shopping cart is grater then the given value.

ContainsGtinCondition

Is true if the shopping cart contains each LineItem with the given minQuantity.

ContainsPosArticleIdCondition

Is true if the shopping cart contains each LineItem matching the given posCategoryIds with the given minQuantity.

ContainsCategoryCondition

Is true if the shopping cart contains each LineItem within the given gs1-Categories with the given minQuantity.

ContainsCategoryCondition

Is true if the shopping cart contains each LineItem within the given Pos-Categories with the given minQuantity.

# Discount

This abstract class is parent of all available discounts.

PercentDiscount

Reduces the line items price matching the scope by the given percent amount.

ValueDiscount

Decreases all line items prices matching the scope by the given amount in total.

AddFreePosArticlesDiscount

Adds the line items with the given Pos Article Ids with the given quantity to the shopping cart.

AddFreeGtinArticlesDiscount

Adds the line items with the given Gtins with the given quantity to the shopping cart.

# Scope

This abstract class is parent of all available scopes.
The scopes define on which line items the discount gets applied.

ShoppingCartScope

Discount gets applied for all line items in the shopping cart.

GtinScope

Discount gets applied for all line items in the shopping cart matching the given Gtins.

PosSoftwareArticleScope

Discount gets applied for all line items in the shopping cart matching the given Pos Software Article Ids.

CategoryScope

Discount gets applied for all line items in the shopping cart within the matching Gs1 categories.

PosSoftwareCategoryScope

Discount gets applied for all line items in the shopping cart within the matching Pos Software Categories.

This abstract class is parent of all available scopes.
The logic for the activation condition and the scope can be built by using the two available link operators and and or.

linkElements:
a List of Elements which can be of type ActivationCondition or Scope.

linkChildren:
a List of Links for nesting the logic.

# Examples

Example 1

5 € discount on the total shopping cart if the purchase value is over 30 €

{
   "validFrom":"2020-04-04T00:00:00+01:00",
   "validTo":"2020-04-11T23:59:59+01:00",
   "couponText":"5€ Rabatt bei über 30 € Einkaufswert",
   "printTextOnReceipt":false,
   "conditions":[
      {
         "type":"AndLink",
         "linkElements":[
            {
               "valueGreaterThan":30.0,
               "type":"ValueCondition",
               "negate":false
            }
         ]
      }
   ],
   "scopes":[
      {
         "type":"AndLink",
         "linkElements":[
            {
               "type":"ShoppingCartScope"
            }
         ]
      }
   ],
   "discounts":[
      {
         "discountValue":5.0,
         "type":"ValueDiscount"
      }
   ]
}

Example 2

Buy 3 Pay 2

{
   "validFrom":"2020-04-04T00:00:00+01:00",
   "validTo":"2020-04-11T23:59:59+01:00",
   "couponText":"Kaufe 3 zahle 2",
   "printTextOnReceipt":false,
   "conditions":[
      {
         "type":"AndLink",
         "linkElements":[
            {
               "articleIds":null,
               "minQuantity":2.0,
               "type":"ContainsPosArticleIdCondition",
               "negate":false
            }
         ]
      }
   ],
   "scopes":[
      {
         "type":"AndLink",
         "linkElements":[
            {
               "posSoftwareArticleIds":[
                  "ArticleId 1"
               ],
               "type":"PosSoftwareArticleScope"
            }
         ]
      }
   ],
   "discounts":[
      {
         "posSoftwareArticleIds":[
            "ArticleId 1"
         ],
         "quantity":1.0,
         "type":"FreeArticleDiscount"
      }
   ]
},

Example 3

15 % discount on an certain product group

{
   "validFrom":"2020-04-04T00:00:00+01:00",
   "validTo":"2020-04-11T23:59:59+01:00",
   "couponText":"15 % auf eine Warengruppe",
   "printTextOnReceipt":false,
   "conditions":[
      {
         "type":"AndLink",
         "linkElements":[
            {
               "valueGreaterThan":0.0,
               "type":"ValueCondition",
               "negate":false
            }
         ]
      }
   ],
   "scopes":[
      {
         "type":"AndLink",
         "linkElements":[
            {
               "posSoftwareCategoryIds":[
                  "ProductGroup 1"
               ],
               "type":"PosSoftwareCategoryScope"
            }
         ]
      }
   ],
   "discounts":[
      {
         "discountPercentage":15.0,
         "type":"PercentDiscount"
      }
   ]
}

# 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 be set automatically for all requests in the collection. Choose the environment and you are good to go.

# Migration information from v1

Some general migration information:

  • UserId is not part of the AddBillDto anymore. It is now part of the bill route if needed.
  • Some properties of the AddBillDto moved to the LegalInformationDto.
  • LineItemDto has a lot more properties.
  • LineItemDto some property names changed to better reflect the value.
  • TenderDto has other TenderTypeDto and new detailed tender type to support more tender types and give some more flexibility. See description above.
  • StoreDto shortName and longName changed to displayName and legalName

# Changelog

Changes to the V2 Api will be documented here.

2020-03-01 Added coupons to bill.

2020-03-01 Preview deployed to staging environment. Only small adjustments done.

2020-02-27 Initial Preview