Shoprite EDI REST Web Service

Technical Implementation Guide

Release Date November 2015

Date	Version	Description	Changes Made	Author
20/08/2015	1.0	Draft	New document	Ian Zeeman
29/09/2015	2.0	Final	Amendments	Ian Zeeman

Table of Contents

1 Purpose of this document........................................................................................................... 3

2 Introduction to EDI?.................................................................................................................... 3

2.1 What Is Edi?.......................................................................................................................... 3

2.2 Why Use Edi?........................................................................................................................ 3

2.3 EDI Business Cycles.............................................................................................................. 4

A typical EDI business cycle may be as follows:............................................................................ 4

3 Introduction to Shoprite EDI messaging...................................................................................... 5

3.1 Required EDI Development..................................................................................................... 5

3.1.1 Purchase Orders................................................................................................................ 6

3.1.2 Debit Credit Advice (claims)................................................................................................ 6

3.1.3 Invoice............................................................................................................................... 7

3.1.4 Despatch Advice (also referred to as Advanced Shipping Notice or ASN)............................. 7

3.2 Electronic (auto) download user accounts................................................................................ 7

4 Shoprite Restful Service Information........................................................................................... 8

4.1 Environments......................................................................................................................... 8

Appendix A: Web Service Introduction................................................................................................ 11

SOAP......................................................................................................................................... 11

Representation State Transfer (REST).......................................................................................... 12

JavaScript Object Notation (JSON).............................................................................................. 12

Appendix B: Fault Codes..................................................................................................................... 14

Appendix C: Glossary of Terms........................................................................................................... 17

1 Purpose of this document

Shoprite is currently busy with a large-scale SAP Retail implementation with a number of business processes such as ordering, receiving and shipping being impacted. In support of this implementation it has become a priority to have all Suppliers using a common language for Electronic Data Interchange (EDI). As a result Shoprite has chosen to use GS1 document standards for orders, claims, e-invoicing and Advanced Shipping Notice (ASNs). This initiative will facilitate a more streamlined business process between Shoprite and its vendors.

As a result of the above requirements an Electronic Exchange Programme (eXP) has been launched and tasked with delivering the necessary EDI capabilities for Shoprite. The purpose of this document is to provide vendors with sufficient information for them to be able to develop or modify any necessary infrastructure to enable EDI with Shoprite using standard GS1 message formats.

2 Introduction to EDI?

For vendors who are not interacting with Shoprite using EDI, below is a brief introduction to EDI.

More information can be obtained from:

http://www.gs1.org/edi-xml/functional-user-guide/3-2/edi-trade-messages

2.1 What Is Edi?

EDI is commonly defined as the application-to-application transfer of business documents between computers. Many businesses choose EDI as a fast, inexpensive, and safe method of sending purchase orders, invoices, shipping notices, and other frequently used business documents.

EDI is quite different from sending electronic mail messages or sharing files through a network. The transfer of EDI files requires that the computer applications of both the sender and receiver (referred to as "trading partners") agree upon the format of the documents.

When using EDI, it's not necessary for the trading partners to have identical document processing systems. The trading partner sending a document converts their proprietary document formats into agreed upon standards such as those defined by the GS1 organization. The receiving party in turn translates the standard format back into the proprietary format their internal systems may require.

2.2 Why Use Edi?

With high volumes of transactions, large inventories and numerous suppliers, the retail industry is one of the areas for high return on investment with EDI. Large retailers are often EDI "hubs" forcing suppliers ("spokes") to accept purchase orders electronically in EDI format. Vendor Managed Replenishment Systems (VMRS) allow vendors to supply retailers automatically, based on electronic reports of product sales. This process eliminates purchase orders and reduces inventory and retail "stock out" problems.

Quick response is a process that uses real-time transactions to trigger replenishment responses in the

supply chain for manufacturers or retailers. This improves inventory turns, product allocation and

replenishment times and helps retailers avoid running out of important stock.

Enterprise Resource Planning (ERP) software solutions address interactions between the various functions

Such as Sales, Distribution, Manufacturing, Materials, Finance, Human Resources, and Maintenance. They

provide a common, consistent system for capturing data organization wide, with minimum redundancy.

Throughout the process, bar codes may be used to capture product and process identification and often

are used to provide input to processes that produce data for EDI systems.

EDI is a tremendous cost- and time-saving system. Since the transfer of information from computer to computer is automatic, there is no need to re-key information. With no data entry, the chance for error drops to near zero.

EDI is also a method of improving customer service as the quick transfer of business documents and marked decrease in errors allow you to fill orders faster.

2.3 EDI Business Cycles

A typical EDI business cycle may be as follows:

1. A buyer has a need for merchandise and creates a Request for Quote (RFQ) document.
2. The seller responds with a Quote providing the price and other pertinent information as to how the request would be fulfilled.
3. Upon acceptance of the quote, the buyer sends a purchase order document to the seller requesting goods at the quoted prices.
4. The seller responds acknowledging that the goods can be delivered at the prices specified and in the time frame indicated.
5. The seller ships the goods and sends a shipping notice (ASN) providing details regarding the carrier, product identification, dates, and other relevant information about the shipment.
6. The seller sends an invoice document, billing the buyer for the goods.
7. The buyer notifies his bank that payment is to be made (payment order) and uses another form of the same document (remittance advice) to inform the seller that payment is being made.

Figure 1: Typical business cycle.

3 Introduction to Shoprite EDI messaging

As a first release Shoprite will make available the following EDI trade messages via it’s B2B portal using REST web services (see Appendix A for further web service info):

· Order – Request for the purchase of goods and services from a trading partner

· Invoice – Request for payment of goods or services supplied by a trading partner

· Debit Credit Advice (claims) – Notice to a trading partner of a monetary adjustment being applied to the amounts owed for goods or services purchased from a trading partner

· Despatch Advice (ASN) – Pre-announcement of the contents of a shipment destined for a buyer

Figure 2: Shoprite EDI business process.

3.1 Required EDI Development

1. If you are not yet using the Shoprite Supplier portal, register for EDI interaction with Shoprite via the B2B portal. Link: https://supplier.shopriteholdings.co.za
2. Open the Shoprite external IP address (NAT) on your firewall so that your systems can connect to the Shoprite system.
3. Modify your ERP system to call the Shoprite web services to retrieve or post messages.
4. Call the relevant services - orders, claims, invoice, ASN.
5. Receive messages from or post messages to the shoprite services.
6. Insert messages into your ERP system.
7. Perform any error handling based on responses received from the services.

For example the orders/claim processes would work as follows:

1. Initiate a call to the Shoprite orders web service to request a batch of orders/claims using a supplied username and password.
2. Receive a list of orders/claims from the Shoprite service.
3. Insert these orders/claims into your ERP system.
4. If the insert is successful send an acknowledgement to the Shoprite service to confirm that the orders/claims were successfully processed.
5. Shoprite service responds with a list of orders/claims that were flagged as processed on the Shoprite system. For added confirmation you could confirm that these are the same orders/claims/ that you have posted into your system.
6. Terminate the call.

Should the process fail before step 5, the orders/claims will be made available again when next service call is initiated. Should you the vendor experience problems after step 6, a method call exists to reset batches of orders or claims.

The processes for Invoice and ASN submissions are much simpler.

1. From your ERP system initiate a call to the Shoprite invoice/ASN web service to submit documents using a supplied username and password.
2. Shoprite service responds with either a successful response or with an error message indicating why the document was not accepted.
3. Terminate the call.

Figure 3: Shoprite EDI B2B functional calls:

3.1.1 Purchase Orders

Purpose

The purchase order is a commercial document used to request a trading partner to supply products at a specified price and provides information such as product specifications and quantities. The purchase order document becomes a legally binding contract once the supplier accepts it.

3.1.2 Debit Credit Advice (claims)

Purpose

The Debit Credit Advice message provides an electronic advice to a trading partner that a monetary adjustment is being applied to the purchase of goods or services, resulting in a change to the monetary amount owed/due between the parties.

Claims can be instituted for:

· Goods being received damaged

· Goods being returned to the vendor

· Incorrect quantity of goods received

· Incorrect pricing being charged

3.1.3 Invoice

Purpose

The Invoice message is sent by the supplier to the customer claiming payment for goods or services supplied under conditions agreed by the seller and the buyer.

3.1.4 Despatch Advice (also referred to as Advanced Shipping Notice or ASN)

Purpose

The Despatch Advice as a pre-announcement of the goods being shipped and enables a shipper to provide information about the content of a shipment to a receiver.

3.2 Electronic (auto) download user accounts

Before any successful functional calls can be made, auto-download user accounts have to be created on the Shoprite Supplier Portal by the trading partner’s master user. Every trading partner that has been granted B2B access will have a master account configured. For agents downloading orders on behalf of a trading partner, it is the responsibility of the trading partners master user to create and maintain accounts for the agent.

For security purposes user account passwords are set to expire every 90 days while auto-download accounts are set to expire every 365 days. Notifications will be sent to user prior to expiry. For more information on the usage of the portal see the help guides provided on the portal. Account passwords can be maintained using the portal.

Portal information:

Supplier portal URL: https://supplier.shopriteholdings.co.za

B2B help desk: b2bhelpline@shoprite.co.za

4 Shoprite Restful Service Information

4.1 Environments

QA Environment:

QA external IP (NAT): 196.25.242.110

QA Base URL: https://b2b.shopriteholdingsqa.co.za/B2BWebAPISupplierServices/

QA B2B Rest Service Help URL: https://b2b.shopriteholdingsqa.co.za/B2BWebAPISupplierServices/Help

Production Environment:

PROD external IP (NAT): 196.25.242.118

PROD Base URL: https://b2b.shopriteholdings.co.za/B2BWebAPISupplierServices/

The above base URLs are used for the service and calls to the functionality exposed by the service are relative to that path. They follow the usual default pattern, that being [BASE_URL]/api/controller/action]. The “api ” segment above is extra to distinguish between MVC routes and the WebAPI routes for the service.

The Help page at [BASE_URL]/Help  summarises the API methods which will contain the current ones available to vendors. Clicking any of the links from the Help Page will present all details pertaining to the method being called – e.g. parameters accepted, response and request types with data samples. Clicking the “TEST” button will create a default request for processing.

For example testing an order round trip:

1. Get “new” orders (figure 1)

Via the URL @   https://b2b.shopriteholdingsqa.co.za/B2BWebAPISupplierServices/api/vendororder?vendorId=56205

Via the Help page @

https://b2b.shopriteholdingsqa.co.za/B2BWebAPISupplierServices/Help/Api/GET-api-VendorOrder_username_password_VendorKey

Click ‘Test’ button bottom right followed by

Click ‘Send’ button middle of page

2. Acknowledge Orders by order numbers  (figure 2)

Via the URL @   https://b2b.shopriteholdingsqa.co.za/B2BWebAPISupplierServices/api/vendororder?action=acknowledge&vendorId=56205 and valid Order numbers in request body using your own tool such as Fiddler

Via the Help Page @

https://b2b.shopriteholdingsqa.co.za/B2BWebAPISupplierServices/Help/Api/PUT-api-VendorOrder_action_username_password_VendorKey

3. Reset Orders by order numbers  (figure 3)

Via the URL @   https://b2b.shopriteholdingsqa.co.za/B2BWebAPISupplierServices/api/vendororder?action=reset&vendorId=56205 and valid Order numbers in request body using your own tool such as Fiddler

Via the Help Page @

https://b2b.shopriteholdingsqa.co.za/B2BWebAPISupplierServices/Help/Api/PUT-api-VendorOrder_action_username_password_VendorKey

See screenshots below for an order test example.

Figure 1 - Get Orders:

Figure 2 - Acknowledge orders:

Figure 3 - Reset Orders:

Appendix A: Web Service Introduction

SOAP

SOAP was originally part of the specification that included the Web Services Description Language (WSDL) and Universal Description, Discovery, and Integration (UDDI). It is used now without WSDL and UDDI. Instead of the discovery process described in the History of the Web Services Specification section below, SOAP messages are hard-coded or genereated without the use of a repository. The interaction is illustrated in the figure below.

SOAP provides the envelope for sending Web Services messages over the Internet/Internet and is part of the set of standards specified by the W3C.

The SOAP envelope contains two parts:

1. An optional header providing information on authentication, encoding of data, or how a recipient of a SOAP message should process the message.
2. The body that contains the message. These messages can be defined using the WSDL specification.

Representation State Transfer (REST)

Representation State Transfer (REST) appeals to developers because it has a simpler style that makes it easier to use than SOAP. It also less verbose so that less volume is sent when communicating.

REST is a style of architecture based on a set of principles that describe how networked resources are defined and addressed. It is important to note that REST is a style of software architecture as opposed to a set of standards. As a result, such applications or architectures are sometimes referred to as RESTful or REST-style applications or architectures. REST has proved to be a popular choice for implementing Web Services.

An application or architecture considered RESTful or REST-style is characterized by:

• State and functionality are divided into distributed resources
• Every resource is uniquely addressable using a uniform and minimal set of commands (typically using HTTP commands of GET, POST, PUT, or DELETE over the Internet)
• The protocol is client/server, stateless, layered, and supports caching

This is essentially the architecture of the Internet and helps to explain the popularity and ease-of-use for REST.

JavaScript Object Notation (JSON)

While both SOAP and REST use XML for interchange, JavaScript Object Notation (JSON) uses a subset of JavaScript. JSON uses name/value pairs which are similar to the tags used by XML. Like XML, JSON provides resiliance to changes and avoids the brittleness of fixed record formats.

.

In the below example, on the left is the XML tag of "<state>" with the value of "MN." while on the right are the pairs for JSON. Note that the name/value pairs do not need to be in a specific order.

Appendix B: Fault Codes

Common Codes:

Code	Description	Reason & Solution
301	The user account is locked	There have been too many incorrect login attempts for this user. After 3 incorrect login attempts, the account is locked. Refer to the help desk for further assistance.
302	The user account is closed (no longer active)	The user account has been made inactive. Solution: Use the website to activate the user.
303	The password for this account has expired.	Currently, passwords for all users (including machine users) expire after 1 month. Current solution: use the website to update the password. See error 312 below.
306	That method does not exist	There are currently only two methods. Please note that XML is case sensitive.
308	The password or username is invalid	The username being used does not exist, or the password associated with that username is incorrect. Note: 3 incorrect login attempts cause the account to be locked (see error 301)
309	Invalid Request	There was a problem with the request. Either it was not sent, or the request was not a valid XML file or the XML parser on the server had a problem.
312	The password age has not been reset	Passwords expire after 30 days and are reset whenever a call to 'getNetOrders' is made. This error indicates that this failed. Consult the helpdesk.
313	The xml version is incorrect	A valid xml version will be: Version 1 – original xml layout Version 2 – pack size tag moved to item level
314	Acknowledgement Error – please try again	The order acknowledgement was not successful. Try again or consult the helpdesk.
399	An undefined error has occurred.	This is used to trap any errors that do not fit into the above categories. Please refer this to the helpdesk

Order specific codes:

Code	Description	Reason & Solution
304	There was an error in retrieving the orders list[getNewOrders]	There was an internal error in retrieving the list of orders. Refer this to the help desk.
305	There are no new orders	This is not a fault.
307	There was an error in updating the order status[ackOrders]	After receiving the list of orders, the Shoprite system had a problem with updating the order status. Expect these orders when you request the next set of orders. Solution: Attempt again or use the website with the machine username and password to mark the selected orders as viewed (be careful to select the correct orders). If the problem persists, contact the help desk to log a fault.
310	The MaxOrders value was not an integer in the range …	The MaxOrders value in the header was not a valid numeric value. The error message also indicates the defaulted min and maximum that the server will allow to be transferred.
311	No Orders were updated	This indicates that none of the orders that were updated. There are two scenatios: 1)the OrdersList was invalid 2)the OrdersList has already been updated. Solutions: confirm that the orders need to be updated and check that the OrdersList is valid.

Claim specific codes:

Code	Description	Reason and Solution
304	There was an error in retrieving the xml document	An internal error has occurred on the server. Refer this to the help desk.
305	There are no new claims	Not a fault, but a message to inform the client that there are no un-SOAP’ed claims.
306	That method does not exist	There are currently only 3 method calls that can be used. Remember that XML is case sensitive.
307	Could not extract the list of claim numbers	The ClaimsList must be a comma separated string of claim numbers. Ensure that the tags exist in the SOAP packet and that they are spelt correctly.
310	The maxClaims value is not a valid integer in the range…	The maxClaims value in the header was not a valid numeric value. The error message also indicates the default min and max that the server will allow to be transferred.
311	No claims were updated. This could mean that the claimsList parameter was invalid, or that the claims were not previously requested by the logged in user	This means that no claims have been updated on the server. Check: 1. that the claimsList is valid 2. that the same user account is being used to both fetch and acknowledge claims NOTE: Acknowledged claims will be included in the response irrespective of whether the acknowledgement took place in this transmission or a previous transmission.
315	The claims were not reset – please try again	The resetting was not successful. Try again or consult the help desk.
316	There was an error while creating the document header	An internal server error occurred when appending the document header to the document. Refer to the help desk.

Invoices specific codes:

Code	Description	Reason & Solution
305	There are no new orders	This is not a fault.
307	There was an error in updating the order status[ackOrders]	After receiving the list of orders, the Shoprite system had a problem with updating the order status. Expect these orders when you request the next set of orders. Solution: Attempt again or use the website with the machine username and password to mark the selected orders as viewed (be careful to select the correct orders). If the problem persists, contact the help desk to log a fault.
309	Invalid Request	There was a problem with the request. Either it was not sent, or the request was not a valid XML file or the XML parser on the server had a problem.
310	The MaxOrders value was not an integer in the range …	The MaxOrders value in the header was not a valid numeric value. The error message also indicates the defaulted min and maximum that the server will allow to be transferred.
311	No Orders were updated	This indicates that none of the orders that were updated. There are two scenatios: 3)the OrdersList was invalid 4)the OrdersList has already been updated. Solutions: confirm that the orders need to be updated and check that the OrdersList is valid.

Despatch Notices (ASN) specific codes:

Code	Description	Reason & Solution
304	There was an error in retrieving the orders list[getNewOrders]	There was an internal error in retrieving the list of orders. Refer this to the help desk.
305	There are no new orders	This is not a fault.
307	There was an error in updating the order status[ackOrders]	After receiving the list of orders, the Shoprite system had a problem with updating the order status. Expect these orders when you request the next set of orders. Solution: Attempt again or use the website with the machine username and password to mark the selected orders as viewed (be careful to select the correct orders). If the problem persists, contact the help desk to log a fault.
310	The MaxOrders value was not an integer in the range …	The MaxOrders value in the header was not a valid numeric value. The error message also indicates the defaulted min and maximum that the server will allow to be transferred.
311	No Orders were updated	This indicates that none of the orders that were updated. There are two scenatios: 5)the OrdersList was invalid 6)the OrdersList has already been updated. Solutions: confirm that the orders need to be updated and check that the OrdersList is valid.

Appendix C: Glossary of Terms

Advance Ship Notice (ASN): An electronic version of a printed packing slip that tells a buyer that goods have been shipped, how they have been packed items and the estimated arrival time. Also referred to as a Delivery Notice or Dispatch Advice.

Business Partner: The entity with which EDI business documents are exchanged. This may be either the sender or the receiver of information in EDI.

Business to Business (B2B): The practice of buying and selling between companies through the use of electronic transactions.

Delivery Notice (or Despatch Advice): Alternate term for an ASN

GLN: Global Location Number, is the ID Key used to identify locations and legal entities. Locations can be a physical place such as a warehouse, a storage cabinet or even a specific shelf within a store. They can be a legal entity such as a company, or division of a company; or they can be a function that takes place within a legal entity, such as the accounting department of a company or the paediatrics ward of a hospital.

GTIN: Global Trade Item Number is used to uniquely identify trade items which are products and services that are priced, ordered or invoiced at any point in the supply chain. Each trade item that is different from another is llocated its own separate GTIN.

GRN: Goods Received Note. A document raised by a customer receiving goods to confirm what has been received, so that invoices may be approved for payment.

Invoice: A request for payment that communicates to a buyer the specific items, price, and quantities delivered that must be paid for by the buyer. Payment terms will usually accompany the billing information.

Purchase Order: A document issued by a buyer to a seller that details the terms of sale under which the buyer will purchase the seller’s goods.

Purchase Order Acknowledgment: Confirmation to the buyer that the supplier will be filling the purchase order as requested.

END OF DOCUMENT