52API SAVE RECEIPT

This topic is primarily for administrators and other people who manage a Fiftytwo solution

This topic is about an API for on-premise use. To learn about Fiftytwo cloud-based APIs, go to https://api.fiftytwo.com/ .

52API SAVE RECEIPT, commonly known as Save receipt API, is typically used with retail systems like 52ViKING to give external partners or tools the ability to store receipts on a 52ViKING server, typically a 52ViKING store controller. It provides features such as:

  • Upload receipts
  • Store receipts
  • Validate data format
  • Convert receipts to a transaction format that the 52ViKING store controller can handle

The API currently uses the normal till engine to convert incoming receipts to TTs (transactions).

Save receipt API defines a single endpoint: /api/v1/SaveReceipt

To upload a receipt, use the endpoint to post an XML document that adheres to ReceiptBasket.xsd.

Basic flow through Save receipt API:

In the diagram, the two services TT Service and SC Service are components/services that run outside the API itself and pick up receipts that have, respectively, been uploaded and converted to TTs. The final export to external systems, such as a client's AX or SAP ERP, follows the usual flow for 52ViKING receipts and isn't documented as part of this API.

Error handling isn't included in the diagram. Whenever an error occurs, for example because a non-valid data format is uploaded, the process will stop with a record of what went wrong, either in the form of a reply to the caller, setting the receipt status, or an entry in internal logs.

Attribute

Type

Description

tendertype

integer

Tender ID from 52ViKING (VB12 menu)

amount

decimal

Amount paid with gift card

giftcardno

integer

Gift card number

reference

string

Additional generic information

 

Attribute

Type

Description

tendertype

integer

Tender ID from 52ViKING (VB12 menu)

amount

decimal

Amount paid with card

cardiso

integer

Card number (possibly masked)

reference

string

Additional generic information

 

Attribute

Type

Description

tendertype

integer

Tender ID from 52ViKING (VB12 menu)

amount

decimal

Amount paid with account

accountno

integer

Account number

reference

string

Additional generic information

 

Attribute

Type

Description

chain

integer

Chain ID

store

integer

Store ID

terminal

integer

Till number as defined in VB01 or VIK_TNR

receiptno

integer

Receipt number in 52ViKING session

orderid

integer

Order ID (if receipt was created from an order)

receipttime

dataTime

ISO-formatted date and time on receipt

Example:
receipttime="2021-03-30T15:15:47:26"

 

Attribute

Type

Description

id

integer

Customer ID / account number

type

integer

Customer type:

  • 0: Staff

  • Higher than 0: Normal customer

subtype

integer

Customer subtype

clublist

integer list

Comma-separated list of club IDs that customer belongs to.

Each ID is an integer.

 

Attribute

Type

Description

id

integer

External account number

type

integer

Customer type as specified by external system

 

Attribute

Type

Description

number

integer

Article's EAN

quantity

decimal

Number or articles bought.

Can be non-integer, for example for weight-variable articles.

totalprice

decimal

Total price for all articles (unit price × quantity)

description

string

Article description

unitprice

decimal

Price of single article of the type in question

agerestricted

(any)

If set to any non-zero or non-false value, require check of customer's age

 

Attribute

Type

Description

percent

decimal

Percent rate for VAT group

amount

decimal

Total VAT amount

 

Attribute

Type

Description

discountGroup

integer

Discount ID

family

integer

Discount family for basic discounts

offerid

string

Offer ID specified for discount group in VK01

campaignid

string

Campaign ID specified for discount group in VK01

couponid

string

Voucher ID if a voucher triggered the discount

 

Version

Date

Change

Author

1.4

2021-06-11

Transfer to Fiftytwo help & knowledge center.

Changed title from SaveReceipt API, applied layout changes, and added introduction text.

MOM

1.3

2021-02-24

Changed formatting of attribute descriptions.

PEH

1.2

2020-11-20

Added attribute descriptions.

SKA

1.1

2020-11-17

Creation of original document.

SKA