52API ORDER
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 ORDER, commonly known as Order API, is a REST-based web API. It's typically used with retail systems like 52ViKING for:
-
Integration between web and physical stores
-
Sales through web and in-store purchases
-
As the basis for click & collect
It provides features such as:
-
Consistent order handling
-
Orders delivered via omnichannel controller down to individual store controllers
-
Creation of new orders
-
Adding and changing of order lines and calculation
-
Payment registration (via Payment Gateway)
-
Registering of complete order – calculated by external system
-
Viewing of order status and receipt ID
Order API is part of the 52MASTERPRICER suite of APIs.
Order API uses these HTTP status codes as return codes:
-
200 OK
On GET request with successful reply.
On POST request with successful reply.
-
204 No Content
Default return code for POST request with no reply data
-
400 Bad Request
Returned if request is wrong or if request is missing information.
-
404 Not Found
Returned if request fails, for example because of missing content.
-
ISO-8859-1
-
UTF-8
In this case, the system exposes individual resources for each method. The following is a short walk-through of the resources.
-
WebOrderNew
This method is used to have an order number assigned by 52ViKING that will be used as a parameter for subsequent web order methods. If the order number is controlled by another method, this resource is not used.
-
WebOrderOpen
This method is used to create new order. This method should be the first in a new order.
-
WebOrderLine
This method adds an article to the order. The function will not create a missing article by itself, but an error message will be returned. If the article exists, the system will calculate the price and eventually any discounts. A new or modified line can have effect on the calculation for the rest of the articles within the basket.
-
WebOrderClose
This method will close the order and enable the order to be paid at the till. The resource will return the necessary information to create a barcode containing the order number.
-
WebOrderPaid
This method will result in an automatic transfer to the electronic journal.
-
WebOrderCreate
This method takes the full order in one POST Message.
-
WebOrderTransaction
This method takes the full order in one POST message. For WebOrderCreate and WebOrderTransaction, discount calculations are made, as the web system is expected to do that. When the order has been created, the order is controlled for non-existing articles. If such are found, they will be created with the default values corresponding to the cfg-file. Both these calls can contain Article creation records as described.
-
WebOrderStatus
This method returns the payment status for saved orders saved by WebOrderCreate.
-
WebOrderReceiptld
This method is to be used when the webshop needs to know the transaction ID for the transaction. This ID can be used to recall the receipt for returning goods from the transaction. The barcode is used at the 52ViKING tills in the store.
XML tag ID |
Type |
52ViKING field |
Description |
<OrderNo> |
N 8 |
Ordnr |
Order ID (key) |
<ClientId> |
N 3 |
Client |
Client ID |
<Store> |
N 4 |
Forr |
Store ID |
<Reference> |
C 32 |
Ref |
Reference |
<Phone> |
C 12 |
Tlf |
Phone number |
<Mail> |
C 60 |
|
E-mail address |
<Rem1> |
C 50 |
bem1 |
Remarks |
<Rem2> |
C 50 |
bem1[1] |
Remarks |
<Rem3> |
C 50 |
bem2 |
Remarks |
<Rem4> |
C 50 |
bem2[1] |
Remarks |
<ZipCode> |
N 4 |
postnr |
Zip code |
<Deliverydate> |
N 8 |
levdat |
Delivery date |
<From> |
N 4 |
levmin |
Delivery time interval start |
<To> |
N 4 |
levmax |
Delivery time interval end |
<CustomerId> |
N 10 |
Kunr |
Customer ID |
<StaffId> |
N 10 |
persnr |
Employee ID |
<PaidAmount> |
N-7,2 |
betalt |
Approved amount |
<PaymentMethod> |
N 1 |
betm |
Payment method
|
<CardISO> |
N 19 |
cardnr |
Card ISO (10 digits) |
<AccountNo> |
N 19 |
cardnr |
Card number |
<Club> |
N 1 |
klub |
Club number/type (0-9) |
<BonusPoints> |
N 4 |
ptsant |
Used bonus points |
<BonusAmount> |
N-6,2 |
ptsval |
Bonus amount |
<ReservationId> |
N 4 |
resid |
Reservation ID |
<Channel> |
N 1 |
Skanal |
Sales channel value from 3-15 |
<ExtCustomerId> |
C32 |
Extcid |
External customer ID |
XML tag ID |
Type |
52ViKING field |
Description |
<OrderNo> |
N 8 |
ordnr |
Order ID (key) |
<SeqNo> |
N 10 |
seqnr |
Sequence ID (key) |
<ArticleNo> |
N 13 |
varenr |
Article number |
<Store> |
N 4 |
forr |
Store ID |
<Quantity> |
N-4 |
ant |
Number or articles ordered |
<Price> |
N 8,2 |
b1 |
Numeric |
<Discount> |
N 8,2 |
b2 |
Numeric |
<BottleDeposit> |
N-7,2 |
Fpris |
Price of linked article (such as, for example, bottle deposit) |
<TxtId> |
N 3 |
Txtnr |
Additional text |
<Text> |
C 50 |
Bem |
Remarks (2 lines) |
XML tag ID |
Type |
52ViKING field |
Description |
<OrderNo> |
N 8 |
Ordnr |
Order ID (key) |
<LinkId> |
N 8 |
Lbnr |
Sequence number (key) |
<SeqNo> |
N 10 |
Seqnr |
Sequence ID (key) |
<Store> |
C 0 |
|
|
<TxtId> |
N 3 |
Txtnr |
Additional text |
<Text> |
C 23 |
Bem |
Optional free text |
XML tag ID |
Type |
52ViKING field |
Description |
<OrderNo> |
N 8 |
Ordnr |
Order ID (key) |
<SeqNo> |
N 10 |
Seqnr |
Sequence ID (key) |
<ArticleNo> |
N 13 |
Varenr |
Article number |
<Store> |
N 4 |
Forr |
Store ID |
<Quantity> |
N-4 |
Ant |
Ordered quantity |
<Price> |
N 8,2 |
b1 |
Numeric |
Creation of article record.
XML tag ID |
Type |
52ViKING field |
Description |
<ArticleNo> |
N 13 |
Varenr |
Article number (key) |
<ReceiptText> |
N 30 |
txt |
Receipt text |
<ArticleGroup> |
N 6 |
vgrp |
Article group number |
<StaffDiscountCode> |
N 1 |
prabat |
Staff discount group |
<InternalArticleNo> |
N 13 |
intvnr |
Internal article number |
XML tag ID |
Type |
52ViKING field |
Description |
<OrderNo> |
N 12 |
ordnr |
Order ID (key) |
<SeqNo> |
N 8 |
seqnr |
Sequence ID (key) |
<ExchangeId> |
N 13 |
bytnr |
Exchange sticker ID |
Functions are divided into three groups:
Creates a new order.
URI |
/WebOrderNew? |
Method |
GET |
Querystring |
Store= Store that shall receive the order |
Example |
/WebOrderNew?Store=1 |
Accept |
text/xml application/json |
Returns |
200 OK |
Reply format |
text/xml application/json |
Reply body |
Reply is returned as XML or JSON with the following tags:
|
Reply:
<?xml version='1.0' encoding='ISO-8859-1'?>
<WebOrder>
<OrderReply>
<OrderNo>8</OrderNo>
</OrderReply>
</WebOrder>
Creates a new order.
URI |
/WebOrderOpen? |
Method |
POST |
Query string |
Store= Store that shall receive the order Order= Order number |
Example |
/WebOrderOpen?Store=1&Order=10019025 |
Content-Type |
text/xml application/xml |
Content |
The following tags are accepted:
|
Returns |
204 OK |
Content:
<?xml version="1.0" encoding="UTF-8"?>
<WebOrder>
<Order>
<Store>1</Store>
<OrderNo>10019025</OrderNo>
<ClientId>1</ClientId>
<Store>1</Store>
<Reference>22222222</Reference>
<ZipCode>8300</ZipCode>
<DeliveryDate>20130526</Deliverydate>
<From>1000</From> <To>1530<To>
</Order>
</WebOrder>
Creates new article that doesn't exist in the article table.
URI |
/WebOrderArticle? |
Method |
POST |
Query string |
Store= Store number where article must be created Order= Order number |
Example |
/WebOrderArticle?Store=1 |
Content-Type |
text/xml application/xml |
Content |
The following tags are accepted:
|
Returns |
204 OK |
Content:
<?xml version="1.0" encoding="UTF-8"?>
<WebOrder>
<Order>
<Store>1</Store>
<OrderNo>1</OrderNo>
<ClientId>1</ClientId>
<Article>
<ArticleNo>5701012046288</ArticleNo>
<ReceiptText>Test</ReceiptText>
<ArticleGroup>1234</ArticleGroup>
<StaffDiscountCode>1</ StaffDiscountCode>
<InternalArticleNo>1234567890</InternalArticleNo>
</Article>
</Order>
</WebOrder>
Adds or modifies lines that represent articles.
URI |
/WebOrderLine? |
Method |
POST |
Query string |
Store= Store that shall receive the order Order= Order number |
Example |
/WebOrderLine?Store=1&Order=8 |
Accept |
text/xml application/json |
Content-Type |
text/xml application/xml |
Content |
The following tags are accepted:
Optional:
|
Returns |
200 OK |
Reply format |
text/xml application/json |
Reply body |
Reply is returned as XML or JSON with the following tags:
Optional discount tag with the following tags:
Optional deposit t tag with the following tags:
Optional group discount with the following tags:
Remaining part of the order tag:
|
Content example:
<?xml version="1.0" encoding="UTF-8"?>
<WebOrder>
<Order>
<Store>1</Store>
<ClientID>1</ClientID>
<OrderNo>10019025</OrderNo>
<Line>
<SeqNo>0</SeqNo>
<ArticleNo>5701012046288</ArticleNo>
<Quantity>5</Quantity>
<Price>399</Price>
<Discount>0</Discount>
</Line>
</Order>
</WebOrder>
Reply example:
<?xml version='1.0' encoding='UTF-8'?>
<WebOrder>
<OrderReply>
<OrderNo>10019025</OrderNo>
<Line>
<SeqNo>363</SeqNo>
<id>5701012046288</id>
<text>Special order item</text>
<Quantity>5</Quantity>
<price>399.00</price>
<total>1995.00</total>
</Line>
<total>1995.00</total>
</OrderReply>
</WebOrder>
Adds, modifies, or deletes service line.
URI |
/WebOrderServiceLine? |
Method |
POST |
Query string |
Store= Store that shall receive the order Order= Order number |
Example |
/WebOrderServiceLine?Store=1&Order=8 |
Accept |
text/xml application/json |
Content-Type |
text/xml application/xml |
Content |
The following tags are accepted:
|
Returns |
200 OK |
Reply format |
application/xml application/json |
Reply body |
Reply is returned as XML or JSON with the following tags:
Remaining part of the order tag:
|
Content example:
<?xml version="1.0" encoding="UTF-8"?>
<WebOrder>
<Order>
<Store>1</Store>
<ClientID>1</ClientID>
<OrderNo>10019025</OrderNo>
<ServiceLine>
<SeqNo>0</SeqNo>
<ArticleNo>108</ArticleNo>
<Quantity>1</Quantity>
<Price>50</Price>
</ServiceLine>
</Order>
</WebOrder>
Reply example:
<?xml version='1.0' encoding='UTF-8'?>
<WebOrder>
<OrderReply>
<OrderNo>10019025</OrderNo>
<ServiceLine>
<SeqNo>363</SeqNo>
<id>108</id>
<text>Freight</text>
<antal>1</antal>
<price>50.00</price>
<total>50.00</total>
<Service/Line>
<total>1995.00</total>
</OrderReply>
</WebOrder>
Order conclusion for order to be paid at the till.
URI |
/WebOrderClose? |
Method |
GET |
Query string |
Store= Store that shall receive the order Order= Order number |
Example |
/WebOrderClose?Store=1&Order=10019025 |
Accept |
text/xml application/json |
Returns |
200 OK |
Reply body |
Reply is returned as XML or JSON with the following tags:
|
Reply example:
<?xml version="1.0" encoding="UTF-8"?>
<WebOrder>
<Order>
<Store>1</Store>
<ClientID>1</ClientID>
<OrderNo>10019025</OrderNo>
<PaidAmount>15793</PaidAmount>
<CardISO>457112</CardISO>
</Order>
</WebOrder>
<?xml version="1.0" encoding="UTF-8"?>
<WebOrder>
<Order>
<Store>1</Store>
<ClientID>1</ClientID>
<OrderNo>10019025</OrderNo>
<PaymentMethod>2</PaymentMethod>
<PaidAmount>15793</PaidAmount>
<AccountNo>457112</AccountNo>
</Order>
</WebOrder>
Order conclusion for order that's already paid.
URI |
/WebOrderPaid? |
Method |
POST |
Query string |
Store= Store that shall receive the order Order= Order number |
Example |
/WebOrderPay?Store=1&Order=10019025 |
Content-Type |
text/xml application/xml |
Content |
The following tags are accepted:
|
Returns |
204 OK No Content |
The tender type used, or the transaction that's created, must be defined in IT00 under tender method 1 via DIBS.
If CardISO isn't set, the transaction will be 23, otherwise it'll be 24.
Content example:
<?xml version="1.0" encoding="UTF-8"?>
<WebOrder>
<Order>
<Store>1</Store>
<ClientID>1</ClientID>
<OrderNo>10019025</OrderNo>
<PaidAmount>15793</PaidAmount>
<CardISO>457112</CardISO>
</Order>
</WebOrder>
Allows for payment of orders using any of the payment types defined in 52ViKING. This method is an alternative to WebOrderPaid.
Order conclusion – order payment.
URI |
/WebOrderPayment? |
Method |
POST |
Query string |
Store= Store that shall receive the order Order= Order number |
Example |
/WebOrderPayment?Store=1&Order=10019025 |
Content-Type |
text/xml application/xml |
Content |
The following tags are accepted:
Depending on the individual handling settings for the payment type, one or more of the additional information elements can be present:
|
Returns |
400 Bad request if additional information doesn't allow for transactional handling. 204 OK No Content |
Content example:
<?xml version="1.0" encoding="UTF-8"?>
<WebOrder>
<Order>
<Store>1</Store>
<ClientID>1</ClientID>
<OrderNo>10019025</OrderNo>
</Order>
<WebOrderPayment>
<TenderType>1</TenderType>
<PaidAmount>15793</PaidAmount>
<CardISO>457112</CardISO>
<WebOrderPayment>
</WebOrder>
Creation of a full order for order that must be paid at the till
URI |
/WebOrderCreate? |
Method |
POST |
Query string |
Store= Store that shall receive the order Order= Order number |
Example |
/WebOrderCreate?Store=1&Order=8 |
Content-Type |
text/xml application/xml |
Content |
The following tags are accepted: Tags mentioned under:
Article creation tags:
|
Returns |
204 OK |
Content example:
<?xml version="1.0" encoding="UTF-8"?>
<WebOrder>
<Order>
<Store>05801</Store>
<ClientID>101</ClientID>
<OrderNo>10019025</OrderNo>
<Reference>22222222</Reference>
<ZipCode>8300</ZipCode>
<Article>
<ArticleNo>5701012046288</ArticleNo>
<ReceiptText>Test</ReceiptText>
<ArticleGroup>1234</ArticleGroup>
<StaffDiscountCode>1</ StaffDiscountCode>
<InternalArticleNo>1234567890</InternalArticleNo>
</Article>
<Line>
<SeqNo>0</SeqNo>
<ArticleNo>5701012046288</ArticleNo>
<Quantity>5</Quantity>
<Price>399</Price>
<Discount>0</Discount>
</Line>
<Line>
<SeqNo>0</SeqNo>
<ArticleNo>8806071836072</ArticleNo>
<Quantity>2</Quantity>
<Price>6899</Price>
<Discount>0</Discount>
</Line>
</Order>
</WebOrder>
Creation of a full order for order that has been paid.
URI |
/WebOrderTransaction? |
Method |
POST |
Query string |
Store= Store that shall receive the order Order= Order number [ Receipt=yes ] [uuid = Universal Unique Identifier ] |
Example |
/WebOrderTransaction?Store=1&Order=8 |
Content-Type |
text/xml application/xml |
Content |
Accepted tags according to:
Furthermore, the following tags are accepted: Article with the following tags:
ExchangeSticker with the following tags:
|
Returns |
200 OK, a WebOrderReceipt will be returned 202 Accepted, the order is placed in a queue 204 OK, no reply will be returned 400 Bad request, an error reply will be returned. 404 Resource isn't available |
Receipt=yes will cause the resource to return a WebOrderReceipt reply.
Content example:
<?xml version="1.0" encoding="UTF-8"?>
<WebOrder>
<Order>
<Store>05801</Store>
<ClientID>101</ClientID>
<OrderNo>10019025</OrderNo>
<Reference>22222222</Reference>
<PaidAmount>15793</PaidAmount>
<CardISO>457112</CardISO>
<ZipCode>8300</ZipCode>
<Article>
<Store>1</Store>
<ArticleNo>5701012046288</ArticleNo>
<ReceiptText>Test</ReceiptText>
<ArticleGroup>1234</ArticleGroup>
<StaffDiscountCode>1</ StaffDiscountCode>
<InternalArticleNo>1234567890</InternalArticleNo>
</Article>
<Line>
<SeqNo>0</SeqNo>
<ArticleNo>5701012046288</ArticleNo>
<Quantity>5</Quantity>
<Price>399</Price>
<Discount>0</Discount>
</Line>
<Line>
<SeqNo>0</SeqNo>
<ArticleNo>8806071836072</ArticleNo>
<Quantity>2</Quantity>
<Price>6899</Price>
<Discount>0</Discount>
</Line>
<ExchangeSticker>
<SeqNo>0</SeqNo>
<ExchangeId>0215952820228</ExchangeId>
</ExchangeSticker>
<ExchangeSticker>
<SeqNo>0</SeqNo>
<ExchangeId>0215952820235</ExchangeId>
</ExchangeSticker>
</Order>
</WebOrder>
Error reply at HTTP status code 400:
<?xml version='1.0' encoding='ISO-8859-1'?>
<ErrorReport>
<error>
<status>
<recordType>Line</recordType>
<statusText>not updated</statusText>
</status>
<block>5</block>
<code>14</code>
<file></file>
<key>22 0</key>
<field>varenr</field>
<data>abc4711</data>
<text>non-valid field content</text>
</error>
</ErrorReport>
This method should be used in conjunction with the CalculateBasket method in Basket API.
OrderBasket is called when the basket is ready to be sent to the shop, from where further handling will take place. The design of this method is such that details and vouchers input can be taken directly from the CalculateBasket output.
Inquiry for order status.
URI |
/WebOrderStatus? |
Method |
GET |
Query string |
[ Store= Store that shall receive the order ] Order= Order number |
Example |
/WebOrderStatus?Store=1&Order=10019025 |
Accept |
text/xml application/json |
Returns |
200 OK |
Reply body |
Reply is returned as XML or JSON with the following tags:
|
If you omit Store=, status will be taken from the commerce server itself, otherwise status will be taken from the store controller.
Reply example:
<?xml version='1.0' encoding='UTF-8'?>
<WebOrder>
<OrderReply>
<OrderNo>10019025</OrderNo>
<status>2</status>
<text>paid</text>
<DeliveryStatus>2</DeliveryStatus>
<DeliveryStatusText>completed</DeliveryStatusText>
</OrderReply>
</WebOrder>
If there's an error, this answer is sent instead:
<?xml version='1.0' encoding='ISO-8859-1'?>
<ErrorReport>
<error>
<status>
<recordType>Line</recordType>
<statusText>not updated</statusText>
</status>
<block>5</block>
<code>14</code>
<file></file>
<key>220</key>
<field>varenr</field>
<data>abc4711</data>
<text>non-valid field content</text>
</error>
</ErrorReport>
Inquiry for order status.
URI |
/WebOrderReceiptId? |
Method |
GET |
Query string |
Store= Store that shall receive the order Order= Order number |
Example |
/WebOrderReceiptId?Store=1&Order=10019025 |
Accept |
text/xml application/json |
Returns |
200 OK |
Reply body |
Reply is returned as XML or JSON with the following tags:
|
Reply example:
<?xml version='1.0' encoding='ISO-8859-1'?>
<WebOrder>
<OrderReply>
<OrderNo>1001925</OrderNo>
<StoreNo>1</StoreNo>
<SessionNo>87</SessionNo>
<TillNo>999</TillNo>
<ReceiptNo>32</ReceiptNo>
<Date>20131119</Date>
<ReceiptBarcode>000011311199990032</ReceiptBarcode>
</OrderReply>
</WebOrder>
Version |
Date |
Change |
Author |
---|---|---|---|
2.2 |
2021-05-31 |
Following review, removed comparison with the previously used method= method. Fixed XML tag IDs that had previously been cut off. |
MOM |
2.1 |
2021-04-06 |
Transfer to Fiftytwo help & knowledge center. Applied layout changes, added introduction text, introduced copyable examples in online versions, performed minor language optimizations (including changing some article descriptions in response examples from Danish to English), and changed revision history sorting to display most recent changes at top of table. |
MOM |
2.0 |
2020-01-06 |
Layout |
MIE |
1.9 |
2019-06-13 |
Added couponid for discount and discountamount for coupon. |
BER |
1.8 |
2019-04-26 |
Added support for multiple coupons in OrderBasket |
BER |
1.7 |
2018-05-24 |
Added fixedorder and barcode to OrderBasket request |
BER |
1.6 |
2017-12-29 |
Added OrderBasket method |
BER |
1.5 |
2017-07-10 |
Added fields Channel and ExternalCustomerId to order header |
BER |
1.4 |
2017-05-29 |
Added field definitions |
PEH |
1.3 |
2017-05-19 |
Layout |
PHJ |
1.2 |
2016-03-09 |
Added type information to examples |
PEH |
1.1 |
2015-07-13 |
Layout reformatting |
PEH |
1.0 |
2015-09-12 |
Change history introduced |
APE |
© 2024 Fiftytwo A/S • Disclaimer
Last update: 29 November, 2024 13:22:48 CET
Share this page with your colleagues: