7 Integration
This section describes the integration through RIB, batches, and web services.
Retail Integration Cloud Service (RICS) - based Integration
Customer Orders
-
Customer Order Create is used for Customer Orders that are a type of Web Order integrated through a message (FulfilOrdDesc). These integrations are used for the customer order from the Order Management System (OMS).
-
The Customer Order Create failure message (FulfilOrdCfmDesc) is a message that will be sent out to external system when we get a Customer Order that comes into the system through the RIB and fails due to validation issues such as an invalid item. The purpose of the create failure is so other systems will know it has failed when it came in and that it is not being processed.
-
The Stock Order Status message (SOStatusDesc) will be sent out with an SI upon reserving inventory for the customer order.
Picking
-
A Stock Order Status message (SOStatusDesc) is sent out with a type of SI upon reserving inventory. This happens when more is picked than what was on the order due to tolerances. This could also occur when a substitute item is added during the picking process.
-
The Stock Order Status message (SOStatusDesc) with a type of SD will be published to un-reserve the original items inventory when a substitute item has been added during picking.
-
A Stock Order status message (SOStatusDesc) is sent out with a type of PP when picking is completed.
-
Item Substitutes are sent to EICS from the merchandising system through the item message (ItemDesc).
Deliveries
-
An ASN Out message (ASNOutDesc) is sent out upon dispatching of the Delivery. This will be done for pick-ups and for shipments.
-
The Stock Order Status message (SOStatusDesc) with a type of PP will be published for the pick quantity in the scenario that more was delivered than what was picked.
-
The Stock Order Status message (SOStatusDesc) with a type of SI will be published for the reserved quantity. This will occur when more was delivered than what was reserved. This can happen when picking was not required, the reservation occurs upon receipt of a delivery, and the full amount had not been received, therefore not reserved.
Reverse Picking
-
Customer Order Cancellations (FulfilOrdRef) will come into EICS from external system such as an OMS through the RIB. This service will perform all the validations to determine if it should create a reverse pick and whether or not that reverse pick should be auto completed.
-
Customer Order Cancellation Confirmation (FulfilOrdRef) is a message to send to OMS upon completing of the system-generated reverse pick.
-
Stock Order Status message (SOStatusDesc) with a type of SD will be published for the reserved quantity to un-reserve the inventory for the reverse pick for system-generated picks.
-
Stock Order Status message (SOStatusDesc) with a type of PU will be published for the reverse picked quantity to un-pick the inventory for system-generated picks.
Multi Leg
The following integrations are in addition to the standard integrations that already exist such as receipt message, and so on:
-
The Stock Order Status message (SOStatusDesc) with a type of SI will be published for the reserved quantity.
-
The Stock Order Status message (SOStatusDesc) with type of PP will be published for the picked quantity.
RIB Payloads
RIB payloads are used to communicate information to external systems through RIB Integration.
RIB Payload | Description |
---|---|
FulfilOrdDesc |
RIB payload that contains information about a new web order type of fulfillment order to be created in. |
FulfilOrdCfmDesc |
RIB payload sent from EICS that contains fulfillment order information when that order creating in EICS failed |
FulfilOrdRef |
RIB payload that contains information about a fulfillment order cancelation. It is sent to EICS to convey a cancelation request and sent from EICS to convey actual cancellations. |
SOStatusDesc |
Sent from EICS to convey changes in item status for a specific fulfillment order. Such changes of status include (un)reservation and (un)picking. |
ASNOutDesc |
Sent from EICS to convey a delivery for specified fulfillment order. |
Purchase Orders and Vendor Deliveries
MERCHANDISING publishes the Purchase Orders created for the direct store deliveries using RIB messages. EICS subscribes to these messages and stores them in the EICS database to enable receipt against Purchase Orders.
MERCHANDISING publishes the unit cost of the item at the item/supplier/country level for EICS to use in the receiving process.
EICS publishes the receipts done against the Purchase Order to the merchandising system (Receiving message).
EICS publishes the DSD receipts created in EICS without a Purchase Order to the merchandising system (DSDReceipts and DSD Deals messages).
EICS publishes the receiver unit adjustment done for the deliveries that are already confirmed (receiving message).
EICS is also capable of subscribing to the vendor EDI ASNs through RIB using the ASN In message format.
RIB payloads are used to communicate information from EICS to external systems and from external system to EICS through RIB Integration.
RIB Payload (Subscriber) | Description |
---|---|
PORef |
RIB payload that contains reference level information of a purchase order.This payload is used for removal of purchase orders. |
PODesc |
RIB payload that contains detailed information of a purchase order.This payload is used for creation and modification of purchase orders. |
ASNInRef |
RIB payload that contains reference level information of an ASN. This payload is used for removal of an ASN. |
ASNInDesc |
RIB payload that contains detailed information about the ASN. This payload is used for creation of a direct delivery (document type= 'P') or a warehouse delivery (document type= 'D'). EICS consumes this payload from warehouse when source and/or destination for ASN is a warehouse system. |
RIB Payload | Description |
---|---|
ReceiptDesc |
RIB payload that contains detailed information of the direct delivery receipt. This is published when the purchase order is not null. EICS also consumes this payload for warehouse receiving. |
DSDReceiptDesc |
RIB payload that contains detailed information of the direct delivery receipt. This is published when the purchase order is null. |
SOStatusDesc |
RIB payload sent from EICS to convey changes in item status for a specific fulfillment order. EICS also consumes this payload from warehouse for stock movements originating at the warehouse. |
InvAdjustDesc |
RIB payload that contains information about destination of the adjustment and an InvAdjustDtl. |
Inventory Adjustments
Inventory adjustments integrate to MERCHANDISING at the item level using the RIB. EICS creates the adjustments and groups them together by a header with multiple items, but for integration purposes they are published out at an item level.
Inventory adjustments are published for all manual and external system generated adjustments where the Publish indicator for the reason code is checked. Adjustments are also published for other types of transactions in EICS where the merchandise system is expecting an adjustment for stock on hand updates, for example, receiving a DSD with damaged goods. An adjustment is created behind the scenes only for publishing purposes to notify the merchandising system to move the goods into the unavailable bucket. These system type adjustments are not considered an adjustment within EICS; however, they are published as such for integration purposes.
EICS subscribes to inventory adjustment messages from warehouse systems and updates the warehouse inventory buckets in EICS.
RIB payloads are used to communicate to external systems through RIB Integration.
The following table shows the list of RIB Payloads available for inventory adjustments.
RIB Payload | Description |
---|---|
InvAdjustDesc |
RIB payload that contains information about destination of the adjustment and an InvAdjustDtl. |
InvAdjustDtl |
Contains detailed information about the item adjustment. |
Items
Items come to EICS from a merchandising system through the RIB (items, item loc messages). EICS also gets information about items associated to a supplier through the RIB. Extended attributes are not received or sent on RIB payloads.
RIB Payload | Description |
---|---|
ItemDesc |
This payload contains information about an item. It contains a wide variety of information about the item including suppliers, UPCs, ticketing information, image information, UDAs, and related items |
ItemLocDesc |
This payload contains information about an item at a specific location. |
ItemSupDesc |
This payload contains information about an item for a specific supplier. |
ItemSupCtyDesc |
This payload contains information about an item for a specific supplier within a specific country. |
Stock Counts
Stock counts generate inventory adjustment when completed.
RIB payloads are used to communicate to external systems through RIB.
RIB Payload | Description |
---|---|
InvAdjustDesc |
RIB payload that contains information about destination of the adjustment and an InvAdjustDtl. |
InvAdjustDtl |
Contains detailed information about the item adjustment. |
EICS does not integrate using a web service to any other Oracle Retail products for stock counts.
Transfers
The Transfer Shipping allows for creating shipment, dispatching shipment, canceling shipment, creating container, approving container, adjusting container, and canceling the container.
The Transfer Receiving dialog allows for confirming receipt, copying misdirected container, receiving container and detailed receiving.
This section covers creating transfer documents which are then included in a transfer shipment and dispatched to another store, warehouse, or finisher.
Transfer Creation
Transfer documents can be created in the following ways:
-
Requesting store can create a transfer request.
-
Sending store can initiate a transfer by creating a transfer.
-
Merchandising can create a transfer request.
Each transfer document will have one or more items.
Transfer Messages
EICS will publish messages to Merchandising when the following happen:
-
Transfer is rejected.
-
Transfer is approved.
-
Transfer quantity is updated from the shipment.
Transfer Shipment Creation
Transfer Shipment describes the containers and the items for the shipment taking place. The shipment may be for one or more transfer documents if the transfer is going to the same destination. Dispatching a shipment will update the transfer document.
The user can create a shipment without referencing existing transfers or can create a new transfer on fly (Ad hoc transfer) based on the shipment information.
Transfer Receiving
This transaction captures a delivery that took place from a warehouse, store, or finisher to the store receiving the delivery. It describes the containers and the items of the delivery that should be received by the store. Receiving a container of the delivery will update the transfer document.
Figure 7-1 Transfer Request Flow
![Transfer Request Flow Transfer Request Flow](img/intg_transfrrequestflow.png)
Figure 7-2 Transfer Create Flow
![Transfer Create Flow Transfer Create Flow](img/intg_tranfrcreateflow.png)
Figure 7-3 Transfer Shipment Creation Flow
![Transfer Shipment Creation Flow Transfer Shipment Creation Flow](img/intg_transfrshipcreateflow.png)
Figure 7-4 Transfer Receiving Process Flow
![Transfer Receiving Process Flow Transfer Receiving Process Flow](img/intg_transfrrcvprocessflow.png)
Transfer Doc
RIB Payload | Description |
---|---|
SODesc |
This message is received from external systems when a stock order/transfer has been created |
SOStatusDesc |
This message is received from external systems when a stock order/transfer has been modified. |
SORef |
This message is received from external systems when a stock order/transfer has been deleted. |
Transfer Shipment
RIB Payload | Description |
---|---|
ASNOutDesc |
This message is sent to external systems when the transfer shipment is dispatched. |
ManifestCloseVo |
This message is received from an external system to indicate physical shipment has been accepted. This will attempt to auto-close the transfer shipment if all items are shipped. |
ManifestDesc |
This message is sent to an external system when manifesting is activated, and a transfer shipping container is confirmed. |
ShipInfoDesc |
This message is sent to an external system when pre-shipment notifications are active, and a transfer shipment is either submitted or dispatched (without previously being submitted). |
SOStatusDesc |
This message is sent to an external system when a transfer shipment container is saved with shipping quantities. It is also sent when a transfer shipment container is canceled but had shipping quantities. Increase and decrease of quantities is indicated by the SI or SD codes. |
Transfer Receiving
RIB Payload | Description |
---|---|
ASNInDesc |
Sent from external system to indicate a delivery is tracking place. It creates a transfer delivery record within EICS when a store location is involved. |
ReceiptDesc |
Sent to external system when a transfer delivery is confirmed. Sent from external warehouse system when a transfer delivery is received at the warehouse. |
Vendor Return
RTV Creation
RTVs can only be created by a request from MERCHANDISING:
Each vendor return will have one or more items.
RTV Shipment
Each RTV shipment will tie back to a single vendor return document.
RTV shipment can be created in two ways:
-
From an externally initiated approved vendor return document.
-
Creation of ad hoc vendor return shipment which will create an approved vendor return on the fly.
Each vendor return shipment will have one or more containers; each container in turn will have one or more items.
EICS may publish messages when the following happens:
-
RTV shipment container is updated, and saved (Return To Vendor Publish)
-
RTV shipment is cancelled or rejected (Return To Vendor Publish)
-
RTV shipment is dispatched (Return to Vendor Publish and Ship Info Desc Publish, if dispatched without submitting)
-
RTV shipment is submitted (Ship Info Desc Publish)
-
RTV shipment container is confirmed (RTV manifesting, if configured)
-
RTV shipment is submitted (Pre-shipment notification, if configured)
Figure 7-5 RTV Creation Flow
![RTV Creation Flow RTV Creation Flow](img/intg_rtvcreationflow.png)
Figure 7-6 RTV Shipment Flow
![RTV Shipment Flow RTV Shipment Flow](img/intg_rtvshipflow.png)
Figure 7-7 RTV Shipment Submit and Dispatch Flow
![RTV Shipment Submit and Dispatch Flow RTV Shipment Submit and Dispatch Flow](img/intg_rtvshipsubmitflow.png)
Figure 7-8 RTV Shipment Dispatch Flow
![RTV Shipment Dispatch Flow RTV Shipment Dispatch Flow](img/intg_rtvshipdispatchflow.png)
The following payloads are used in RTV operations.
RIB Payload | Description |
---|---|
RTVReqDesc |
This payload is sent from an external system to indicate a request for a vendor return. It creates or updates a vendor return document within EICS. It contains a series of RTVReqDtl. |
RTVReqDtl |
This payload contains the detailed information about the items on the vendor return. |
RTVReqRef |
This payload contains reference information about a vendor return when an external system wishes to attempt to cancel the return. |
RTVDesc |
This payload is sent from EICS to external systems when an RTV shipment is dispatched. This payload is sent from external warehouse system for vendor returns originating at warehouse. |
Web Services
EICS provides a large range of web services to manage the processing of information that is controlled within EICS. Each web service covers a topical area of functionality within EICS and contains numerous operations within to accomplish this functionality. This document is only meant as an outline or summary into using EICS web services and assumes the user has access to the fully documented APIs through the publishing of the web services themselves.
Note:
The WSDL files are available to download from My Oracle Support (MOS) Document 2614551.1.
Security Considerations
The SOAP web services provided by EICS are secured by Policy A using Oracle WebLogic WS-Policy configurations defined in the xml files included in Oracle WebLogic:
-
Policy A
-
Description: Message must be sent over SSL and requires authentication of a plain text UsernameToken.
-
Configuration: Wssp1.2-2007-Https-UsernameToken-Plain.xml
-
Customers should create IDCS or OCI IAM user and the user should be assigned integration_users IDCS or OCI IAM application role to access the web-service endpoints.
See Oracle Retail Enterprise Inventory Cloud Service Security Guide and Oracle Retail Enterprise Inventory Cloud Service User Guide - Security chapter.
For REST web service security see REST WEB Services Security Considerations later in this guide.
Functionality
This document is intended to be used by someone who has read and understands all the functional areas and business functionality described in the Oracle Retail EICS User Guide and Oracle Retail EICS Administration Guide.
Available Web Services
The following list contains a summary of the web services available in EICS.
Web Service | Description |
---|---|
This service is used to manage the locking of data within EICS. Data needs to be locked to be updated securely. |
|
This service is used to manage fulfillment order deliveries (outgoing shipment to customers). It allows the creation, cancellation, and dispatch of deliveries. |
|
This service is used to manage fulfillment order picking within EICS. It allows the creation, deletion, and confirmation of a pick to complete a fulfillment order. |
|
This service is used to manage fulfillment order reverse picking within EICS. It allows the creation, update, deletion, and confirmation of a reverse pick. |
|
This service is used to manage inventory adjustments within EICS. It allows the creation, update, cancellation, and confirmation of inventory adjustments. |
|
This service is used to manage item baskets within EICS. It allows the creation, update, and removal of item baskets. |
|
This service is used to create, read, update, approve, cancel and lookup store orders. |
|
This service processes external point-of-sale transactions updating the inventory accordingly. A point-of-sale is considered an externally managed transaction (internally and externally managed transaction are covered later in this document). |
|
This service is used to create or update a product group. |
|
This service is used to create, update, or cancel a product group schedule. |
|
This service is used to create, update, or delete a replenishment gap. |
|
This service is used to create, update, or delete a RFID facility zone. It is also used to refresh inventory and to process RFID events. |
|
This service is used to create, update, cancel or confirm a shelf adjustment. |
|
This service is used to create, update, cancel or confirm a shelf replenishment. |
|
This service is used to retrieve the details of a stock count or a stock count child (section of stock count). |
|
This service is used to retrieve information about stores such as store detail, associated stores, or transfer zones. |
|
This service is used to manage fulfillment orders within EICS. It allows for the cancellation and rejection of orders and items. |
|
This service is used to lookup information about inventory positions and has several different operations to do so. |
|
This service is used to create, update, or delete ISN data in EICS. |
|
This service is used to create, update, generate or read a UINs. |
|
This service is used to lookup various information about an item within the store. |
|
This service is used to lookup prices about items within a store. |
|
This service is used to create new notifications within the system. |
|
This service is used to close documents based on shipped container information. |
|
This service is used to retrieve shipment reasons codes to use when creating shipments. |
|
This service is used to create tickets and lookup ticket formats. |
|
This service is used to create, update, and request a transfer, which describes the intent to ship items to another store or to a warehouse. It is also used to approve or reject that request. It can be used to directly create, update, approve, cancel, or close an actual transfer. |
|
This service is used to update, receive, or confirm a transfer delivery (delivery arriving from another store or warehouse). It is also used to create, update, receive, cancel, or confirm the containers on that delivery. |
|
This service is used to create, update, submit, or dispatch a transfer shipment (shipment going out to another store or warehouse). It is also used to create, update, cancel, or confirm the containers on that shipment. |
|
This service is used to update, receive, reject, or confirm a vendor delivery (delivery arriving from a supplier). It is also used to create, update, cancel, or confirm the containers on that delivery. |
|
This service is used to create, update, approve, cancel, or close a vendor return document, which describes the intent to ship items to a supplier. |
|
This service is used to create, update, open, submit, cancel submit or dispatch a vendor shipment (outgoing shipment to a supplier). It is also used to create, update, cancel, submit, or confirm the containers on that shipment. |
Web Services Basic Design Principles
Empty Response
In the cast that a web service does not return any information (an empty list), the external system needs to understand that this is a valid response that indicates no item, transaction or queried information was found or retrieved. For example, performing a lookup in which the search criteria entered matched no input.
Error Return Key
Errors returned through a web service will be in the form of a key. This key should be translated into correct language and verbiage by the external system. EICS will not do this translation or provide English verbiage for the encountered web service error.
Boolean Data Type
If a Boolean is the data type on the interface to EICS, and no value is provided, EICS will default the value to False.
Configured System Options in EICS
Web services apply system configurations to the request that are coming in through the web service but assumes that all input validation that requires user interaction to confirm has been completed by the consumer of the web service (the third party system). This system configuration user-interaction option will be assumed to have been confirmed during the web service processing. In case the system option is a fixed restriction that does not require user interaction, and the input fails this restriction, the web service will return an error. For example:
-
Shipping inventory when inventory is less than 0 can be allowed by the user of EICS. The web service assumes that the third party application did prompt the user or that their business always allows the user to do this activity.
-
Adding a non-ranged item requires both a system configuration option to be enabled and the user to confirm the process. If the system configuration does not allow it, the web service will block the transaction and return an error. If the system configuration does allow adding non-ranged items, it is automatically assumed that a user confirmed its addition, and the web service adds the item.
-
Allowing Receiver Unit Adjustments are dependent on a period of time. If a receiver unit adjustment were to come into EICS after that period, it would automatically be rejected, and the web service would return an error regardless of presentation or confirmation of user done by the external system.
Internally Managed vs Externally Managed
Internally Initiated
Internally initiated indicates the EICS was responsible for the original creation of the transaction being processed. A web service that creates a new transaction within EICS to be managed creates an internally initiated transaction.
Externally Initiated
Externally initiated indicates that another system created the transaction, has information about it, and notifies EICS of its creation through a notification system, not by requesting EICS create new information. EICS might manage the data after the notification but did not create the data.
Internally Managed
Internally managed data is information in which EICS is responsible for tracking its state and processing its life cycle. Our deliveries and shipments are primary examples of this. They may be externally initiated or internally initiated, but either way, they are internally managed. EICS is responsible for approving, picking, packing, manifesting, and dispatching the system and internally manages that process.
Externally Managed
Externally managed data is information that EICS does not process or track and is simply informed about after the externally managed data is complete. Point-of-sale transactions are a perfect example of this. We do not manage the sale, but once it is complete, EICS is notified and adjusts the inventory accordingly.
Web Services
EICS web services are intended for integration to allow a system using those services to control the flow and processing within EICS. Our web services are primarily designed (almost all of them) to internally manage the information. The services are intended to be used real time with the steps such as approving, picking, and dispatching occurring with real time access to EICS web services while the process is happening.
EICS web services are not designed for externally managed information. If a system is controlling the state managements itself and not informing EICS until later, this will produce out-of-sync inventory. For example, if you create a shipment, pack the shipment, and send it out and then a day later use the web service, to create, update, and dispatch the shipment, all dates and processing of inventory movements will be tagged with the later date as if they occurred real time when the web service is used.
The point-of-sale service is an externally managed service, where the timestamp on the service can be any date and EICS handles the logic of dating things according to that timestamp. Inventory Adjustment also has an "adjustment date" which represents the time the adjustment took place and so the movement of inventory can be controlled externally.
Web Service Operation Basic Design Standards
This section discusses the general approach and design standards for naming and intent regarding operations within a web service.
Lookup
Lookup operations take either an identifier of a set of criteria and find all the relevant records associated to it. A thin or light view of the data being asked for is returned giving reference to information you can do further interrogation on.
Read
Read operations take an identifier and return all relevant information to it. It may only be one level, however. For example, reading a transfer shipment returns only all the information at the shipment level and does not read information at the container or item level. Usually, the entity that contains items will also retrieve the items. Reading a container will return the container information and the item information within.
Create
Create usually inserts and generates something new and returns an identifier, reference, or handle to that information. Create normally does not take a great deal of information, such as items or anything, but rather gives you a set of IDs that then lets you update the transaction with that reference.
Save or Update
Save or update is used to modify the data usually without changing state on the transaction. The save or update operation is used to add items, remove items, edit attributes, change quantities and all the other tasks one does during a process.
Approve, Cancel, Confirm or Dispatch
Activities that change state take in a simple identifier and then process that state change. To dispatch a shipment, you pass in a reference only to the shipment and it becomes shipped, updating the inventory. This means all changes are done through the save operations prior to making the state change.
Interpreting Validation Errors
If some data could not be processed, the web service will return a fault or a validation fault. The general form that a fault will take is to be a series of problem detail nodes containing a key and value that describes the fault. The first problem detail node will have the key ERROR and the value will be a description of the error type such as INVALID_INPUT. This will be followed by a series of nodes where the KEY is an object class name (ex: Transfer) and the value is its identifier (ex: 123) describing the hierarchy of data the error took place in. For example, a transfer container fault would have two nodes (Transfer:123) and then (TransferCarton:456). If a specific attribute is known, the final node in any problem detail series is will have the key ATTRIBUTE and the value will be the name of the attribute of the error (ex: ITEM_ID:A5X).
Problem Detail Name | Value |
---|---|
ERROR |
This describes the error (for example: INVALID_INPUT) |
ATTRIBUTE |
Identifies the specific attribute that had an error. |
EICS follows the same business rules when processing information from a web service as it does from any of its clients, so the same business rules and functionality that exist in the User's Guide also exists for the web service. Understanding the basic functionality will help interpret why the validation or processing error occurred.
Common Error Codes
The following codes are paired as values to the ERROR Key:
Error Code | Description |
---|---|
ACTIVITY_LOCK_NOT_GRANTED |
Indicates that a requested activity lock on a piece of data was not granted. |
DUPLICATE_INPUT |
Indicates the service would create a duplication of input that should be unique. |
INVALID_DATE_RANGE |
Indicates the end date of a date range is prior to the start date. |
INVALID_INPUT |
Indicates that the input is invalid. This error is usually followed by object and attribute information. |
INVALID_ITEM |
Indicates the item does not exist in the system. |
INVALID_STATE_FOR_UPDATE |
Indicates the transaction or data specified is not in a state that allows it to be updated (such as canceled). |
INPUT_MISMATCH |
Indicates the input to the web service has been altered incorrectly when compared to existing data. For example, the store identifier is different on the web service request than the currently existing transaction. |
INPUT_TOO_LARGE |
Indicates the input in the web service is larger than is allowed in the transaction date. |
ITEM_NOT_RANGED |
Indicates the item has not been activated in the location for which the request is made. |
MULTIPLE_STORE |
Indicates a batch of input data (such as a point-of-sale transaction) was for more than one store in a single web service call. |
TIMEZONE_NOT_GMT |
Indicates the time input of the web services was not in GMT. |
UOM_MISMATCH |
Indicates a mismatch of unit of measure information between the input and currently existing data that does not allow the information to be accurately merged. |
Validation Error (Fault Example)
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns0:Fault xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.w3.org/2003/05/soap-envelope">
<faultcode>ns0:Server</faultcode>
<faultstring>VALIDATION_ERROR</faultstring>
<detail>
<ns0:ValidationWSFaultException xmlns:ns0="http://www.oracle.com/retail/integration/services/exception/v1">
<ns0:shortErrorMessage>VALIDATION_ERROR</ns0:shortErrorMessage>
<ns0:BusinessProblemDetail>
<ns0:problemDescription>VALIDATION_ERROR</ns0:problemDescription>
<ns0:ProblemDetailEntry>
<ns0:name>ERROR</ns0:name>
<ns0:value>INVALID_INPUT</ns0:value>
</ns0:ProblemDetailEntry>
<ns0:ProblemDetailEntry>
<ns0:name>ShlfAdjRef</ns0:name>
<ns0:value>1</ns0:value>
</ns0:ProblemDetailEntry>
<ns0:ProblemDetailEntry>
<ns0:name>ATTRIBUTE</ns0:name>
<ns0:value>shelfAdjustmentId</ns0:value>
</ns0:ProblemDetailEntry>
</ns0:BusinessProblemDetail>
</ns0:ValidationWSFaultException>
</detail>
</ns0:Fault>
</S:Body>
</S:Envelope>
Business Error (Fault Example)
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns0:Fault xmlns:ns0="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://www.w3.org/2003/05/soap-envelope">
<faultcode>ns0:Server</faultcode>
<faultstring>BUSINESS_ERROR</faultstring>
<detail>
<ns0:ValidationWSFaultException xmlns:ns0="http://www.oracle.com/retail/integration/services/exception/v1">
<ns0:shortErrorMessage>BUSINESS_ERROR</ns0:shortErrorMessage>
<ns0:BusinessProblemDetail>
<ns0:problemDescription>BUSINESS_ERROR</ns0:problemDescription>
<ns0:ProblemDetailEntry>
<ns0:name>ERROR CODE</ns0:name>
<ns0:value>ADJUSTMENT_NOT_FOUND</ns0:value>
</ns0:ProblemDetailEntry>
</ns0:BusinessProblemDetail>
</ns0:ValidationWSFaultException>
</detail>
</ns0:Fault>
</S:Body>
</S:Envelope>
Web Services
Web services available in EICS:
ActivityLock
The following operations are available within the ActivityLock web service.
Operation | Description |
---|---|
lookupActivityLock |
Retrieves information about one or more activity locks that match the input criteria. |
readActivityLock |
Retrieves detailed information about a single lock using its identifying reference. |
createActivityLock |
Created an activity lock on a transaction. |
deleteActivityLock |
Deletes an activity lock thereby releasing processing on a transaction. |
Standard Usage
An activity lock is a record indicating the user, time, and a piece of information (a transaction) that should be considered "locked". All server processing validates that the accessing user has a lock on the information before updating, notifying the current user if someone else has modified the information while they were locked and preventing the stale update.
Developers should create locks on information prior to performing update calls and delete locks when the update if finished. For example, create a lock on inventory adjustment with ID 123 with the ActivityLock service, then use saveInventoryAdjustment
in the Inventory Adjustment service with Adjustment 123, and then delete the activity lock using the ActivityLock service. If you do not gain the lock, you will receive an error when attempting to save an inventory adjustment.
FulfillmentOrderDelivery
The following operations are available within the FulfillmentOrderDelivery web service.
Operation | Description |
---|---|
lookupFulfillmentOrderDeliveryHeaders |
Retrieves summary information for fulfillment order deliveries that match the search criteria input. |
readFulfillmentOrderDeliveryDetail |
Reads the complete detailed information about a fulfillment order including items and quantities. |
createFulfillmentOrderDelivery |
Creates a new fulfillment order delivery including items and quantities in an in-progress status to be further worked on. |
cancelFulfillmentOrderDeliverySubmission |
Cancels the fulfillment order review and moves it back into in-progress status for further work. |
dispatchFulfillmentOrderDelivery |
Dispatches the fulfilment order delivery completing the delivery and updating the inventory. |
submitFulfillmentOrderDelivery |
Submits the fulfillment order delivery for review prior to dispatching. |
updateFulfillmentOrderDelivery |
Updates a fulfillment order delivery including items and quantities. This operation requires an activity lock. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the fulfillment order delivery. |
Standard Usage
A user can create a delivery by using createFulfillmentOrderDelivery
references the fulfillment order to make a delivery for. The user can then use updateFulfillmentOrderDelivery
to fill in all the quantities that are going to be shipped and finally use dispatchFullfillmentOrderDelivery
to indicate that the order has been shipped out, which moves the inventory appropriately.
FulfillmentOrderPick
The following operations are available within the FulfillmentOrderPick web service.
Operation | Description |
---|---|
lookupFulfillmentOrderPickHeaders |
Retrieves summary information for fulfillment order picks that match the search criteria input. |
readFulfillmentOrderPick |
Reads the complete detailed information about a fulfillment order pick including items and quantities. |
confirmFulfillmentOrderPick |
Confirm the fulfillment order pick which allows it to move on to the delivery cycle. |
deleteFulfillmentOrderPick |
Deletes a fulfillment order pick. |
createFulfillmentOrderPickByFulfillmentOrder |
Generate a pick based on the information in a fulfillment order. |
createFulfillmentOrderPickByBin |
Generate a pick based on a number of bins selecting orders as needed to fill the bins. |
updateFulfillmentOrderPick |
Update the item and quantity information about a pick. This operation requires an activity lock. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the fulfillment order pick. |
Standard Usage
Picking is used to reserve or set aside quantities for a later delivery. The user can create a pick for an order using createFulfillmentOrderPickByFulfillmentOrder
or create a bin to places multiple orders in with createFulfillmentOrderPickByBin
. The picked quantities can be updated through the updateFullfillmentOrderPick
operation and when the pick is finished, it can be finalized with confirmFulfillmentOrderPick
which sets assigned the goods as reserved in inventory.
FulfillmentOrderReversePick
The following operations are available within the FulfillmentOrderReversePick web service.
Operation | Description |
---|---|
lookupReversePickHeaders |
Retrieves summary information for fulfillment order reverse picks that match the search criteria input. |
lreadReversePickDetail |
Reads the complete detailed information about a fulfillment order reverse pick including items and quantities. |
createReversePick |
Creates a new fulfillment order reverse pick for the specified fulfillment order. |
deleteReversePick |
Deletes a fulfillment order reverse pick. |
updateFulfillmentOrderReversePick |
Updates the items and quantities on a fulfillment order reverse pick. This operation requests an activity lock. |
confirmReversePick |
Confirms the fulfillment order reverse pick completing the process and assigning the inventory back to a location within the store system. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the fulfillment order reverse pick. |
Standard Usage
Reverse Picking is used to take reserved quantities and place them back into available inventory. The user can create a reverse pick with createReversePick
. The quantities to return can be updated through the updateFulfillmentOrderReversePick
operation and when the reverse pick is ready, it can be finalized with confirmReversePick
which moves reserved inventory back into available inventory.
InventoryAdjustment
The following operations are available within the InventoryAdjustment web service.
Operation | Description |
---|---|
lookupInventoryAdjustmentReason |
Retrieve a complete list of adjustment reasons that can be used when updating or saving an inventory adjustment. Reason codes are attached to each line item. |
lookupNonSellableQuantityType |
Retrieve a complete list of non-sellable quantity types. These codes indicate the reason that unavailable inventory in unavailable. |
lookupInventoryAdjustmentHeader |
Retrieve summary information about inventory adjustment transactions based on the search criteria sent. |
readInventoryAdjustmentDetail |
Retrieve the complete detailed information about an inventory adjustment, including its item information, based on a unique reference/id. |
saveInventoryAdjustment |
Creates or updates the information about an inventory adjustment in the data store. You can alter information about items and quantities using this operation. This operation requires having an activity lock. |
confirmInventoryAdjustment |
Confirms the inventory adjustment, updating all the inventory positions, and closing the adjustment. |
saveAndConfirmInventoryAdjustment |
Performs the functionality of saveInventoryAdjustment and immediately thereafter performs the confirmInventoryAdjustment functionality. See those operations. |
cancelInventoryAdjustment |
Cancel an inventory adjustment. This can only be done prior to the inventory adjustment being confirmed. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the inventory adjustment. |
Standard Usage
A new inventory adjustment can be created using the saveInventoryAdjustment
operation. Alternatively, the user can lookupInventoryAdjustmentHeader
to find a specific inventory adjustment to work on. Either way, saveInventoryAdjustment
can be used to update the information on an open adjustment. The lookupInventoryAdjustmentReasons
will retrieve the reasons codes that need to be assigned to items when you update an adjustment. When the adjustment contains all the information you need, the confirmInventoryAdjustment
operation will finalize the inventory adjustment and shift the inventory appropriately.
ItemBasket
The following operations are available within the Item Basket web service.
Operation | Description |
---|---|
lookupItemBasketHeaders |
Retrieve a list of item basket headers based on search criteria which contain summary information about the item basket. |
lookupItemBasketTypes |
Retrieve a complete list of item basket types to use when creating a new item basket. |
createItemBasket |
Creates a new item basket. |
readItemBasket |
Retrieve the complete detailed information about an item basket based on an identifier. |
deleteItemBasket |
Cancels an item basket. The basket will no longer be usable and will be marked for eventual purge from the data store. This operation requires an activity lock. |
saveItemBasket |
Updates an item basket. This operation requires an activity lock. |
copyItemBasket |
Creates a new item basket with the same information as an existing item basket. |
confirmItemBasket |
Moves the item basket to a completed state and allows it to be used within logic throughout the system. This operation requires an activity lock. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the item basket. |
Standard Usage
A new item basket can be created using the saveItemBasket
operation. Alternatively, the user can lookupItemBasketHeader
and readItemBasket
to find a specific item basket to work on. Either way, saveItemBasket
can be used to update the information on an item basket. When the item basket contains all the information you need, the confirmItemBasket
operation will finalize the item basket and make it available to use in other areas of the system.
OrderRequest
The following operations are available within the Order Request web service.
Operation | Description |
---|---|
lookupOrderRequestHeader |
Retrieves store order request headers based on the query criteria. |
readOrderRequest |
Retrieves detailed information about a store order request. |
createOrderRequest |
Creates a new store order request. |
updateOrderRequest |
Updates an existing store order request. |
approveOrderRequest |
Approve a store order request. |
cancelOrderRequest |
Cancels a store order request. |
lookupDeliveryTimeSlot |
Retrieves delivery time slots. |
lookupOrderContext |
Retrieves contexts available for store order requests. |
lookupOrderArea |
Retrieves store order request areas that could be used for restriction. |
lookupCustomAttributeAdmins |
Retrieves all the custom attributes admins configured for store order requests. |
Standard Usage
A new store order can be created using the createOrderRequest
operation. The information about store order can be read by readOrderRequest
. The store order can be updated using updateOrderRequest
and can be approved using approveOrderRequest
or can be canceled using cancelOrderRequest
. The lookupOrderRequestHeader
is used to find the store orders.
POSTransaction
The following operations are available within the POSTransaction web service.
Operation | Description |
---|---|
processPOSTransactions |
Processes a point-of-sale transaction or transactions through an asynchronous process. This is designed to optimize the processing at 500 PosTrnItm (across any number of transactions). |
Standard Usage
POS may integrate its transactions to EICS using this web service. The service processes point-of-sale transactions through an asynchronous process. This service has a default limit of 1000 total PosTrnItms, though they may be distributed between any number of actual PosTrn transactions. Exceeding this limit causes a web service fault to occur. However, the web service is optimized for speed at greater than 400 and less than 500 total PosTrnItms per service call. These transactions may belong to multiple store identifiers. The processing operation validates the input, parses the payload information, creates a POSTransaction object within EICS, and stores these records to be processed later. See Sales Integration for additional information.
REST Web Service
A REST web service for POSTransaction exists and is the preferred service to use in order to process point-of-sale transactions (see REST WEB Services). This SOAP based web service will be deprecated and eventually removed.
ProductGroup
The following operations are available within the ProductGroup web service.
Operation | Description |
---|---|
lookupProductGroupHeader |
Retrieves list of summary information about a product group that match the search criteria input. |
readProductGroup |
Retrieves the detailed information about a single product group based on its unique reference. |
saveProductGroup |
Creates or updates a product group. The input contains all the detailed information about the product group. An activity lock is needed for this operation. |
Standard Usage
With this web service, the user can create or update the contents of a product group, a collection of items associated with a certain type of grouping, such as stock counts. The user can find the product group with lookupProductGroupHeader
, read in the entire product group with readProductGroup
and then, if the group is still open, update the contents of the product group with saveProductGroup
.
ProductGroupSchedule
The following operations are available within the ProductGroupSchedule web service.
Operation | Description |
---|---|
lookupProductGroupScheduleHeader |
Retrieves list of summary information about a product group schedule that match the search criteria input. |
readProductGroupSchedule |
Retrieves the detailed information about a single product group schedule based on its unique reference. |
saveProductGroupSchedule |
Creates or updates a product group. The input contains all the detailed information about the product group schedule. An activity lock is needed for this operation. |
cancelProductGroupSchedule |
Cancels the product group schedule. |
Standard Usage
With this web service, the user can create or update the contents of schedule, which uses a product group to generate activity within EICS. The user can find the schedule with lookupProductGroupScheduleHeader
, read in the entire schedule with readProductScheduleGroup
and then, if the schedule is still open, update the contents of the schedule with saveProductGroupSchedule
.
ReplenishmentGap
The following operations are available within the ReplenishmentGap web service.
Operation | Description |
---|---|
lookupReplenishmentGapHeaders |
Retrieves list of summary information about replenishment gaps that match the search criteria input |
readReplenishmentGap |
Retrieves the detailed information about a single replenishment gap based on its unique reference. |
saveReplenishmentGap |
Creates a new replenishment gap or updates the detailed information about a replenishment gap. If update, this operation requires an activity lock. |
deleteReplenishmentGap |
Deletes a replenishment gap. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the replenishment gap. |
Standard Usage
With this web service, the user can create or update the contents of replenishment gap list which can then be used in creation of shelf replenishment within EICS. A new replenishment gap list can be created using saveReplenishmentGap
. The user can update existing replenishment gap list with saveReplenishmentGap
, find replenishment gap lists with lookupReplenishmentGapHeaders
, read in the entire replenishment gap list with readReplenishmentGap
and delete a replenishment gap list with deleteReplenishmentGap
.
RfidInventory
The following operations are available within the RfidInventory web service.
Operation | Description |
---|---|
deleteRfidZone |
Deletes a zone within a facility. A zone cannot be deleted if RFID tags still exist within the zone. |
lookupRfidZones |
Returns details about all the zones within a particular facility. |
processRfidEvents |
Processes Radio-Frequency-Identification based events. |
saveRfidZone |
Creates or updates the details of a facility zone. |
Standard Usage
With this web service, the user can create or update RFID zones within EICS. A new RFID zone can be created using saveRfidZone
. The user can update an existing RFID zone with saveRfidZone
, find RFID zones with lookupRfidZones
and delete a RFID zone with deleteRfidZone
. The user can process RFID based events using processRfidEvents
.
ShelfAdjustment
The following operations are available within the ShelfAdjustment web service.
Operation | Description |
---|---|
lookupShelfAdjustmentHeaders |
Retrieves list of summary information about shelf adjustments that match the search criteria input. |
readShelfAdjustment |
Retrieves the detailed information about a single shelf adjustment gap based on its unique reference. |
saveShelfAdjustment |
Creates a new shelf adjustment or updates the detailed information about a current shelf adjustment. If update, this operation requires an activity lock. |
confirmShelfAdjustment |
Confirms a shelf adjustment completing the workflow and moving inventory positions. |
cancelShelfAdjustment |
Deletes a shelf adjustment. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the shelf adjustment. |
Standard Usage
Shelf adjustments are used to adjust the shop-floor or backroom stock in case of any discrepancy. A new shelf adjustment can be created using saveShelfAdjustment
. The user can update existing shelf adjustment with saveShelfAdjustment
, find shelf adjustments with lookupShelfAdjustmentHeaders
, read in the entire shelf adjustment with readShelfAdjustment
, cancel a shelf adjustment with cancelShelfAdjustment
and confirm a shelf adjustment with confirmShelfAdjustment
.
ShelfReplenishment
The following operations are available within the ShelfReplenishment web service.
Operation | Description |
---|---|
lookupShelfReplenishmentHeaders |
Retrieves list of summary information about shelf replenishments that match the search criteria input. |
readShelfReplenishment |
Retrieves the detailed information about a single shelf replenishment gap based on its unique reference. |
createShelfReplenishment |
Creates a new shelf replenishment. |
updateShelfReplenishment |
Updates the detailed information about a current shelf replenishment. This operation requires an activity lock. |
confirmShelfReplenishment |
Confirms a shelf replenishment completing the workflow and moving inventory positions. |
cancelShelfReplenishment |
Deletes a shelf replenishment. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the shelf replenishment. |
Standard Usage
Shelf replenishment is used to replenish shop-floor stock from backroom or delivery bay. A new shelf replenishment can be created with createShelfReplenishment
. The user can find shelf replenishments with lookupShelfReplenishmentHeaders
, read in the entire shelf replenishment with readShelfReplenishment
, update the shelf replenishment with updateShelfReplenishment,
confirm the shelf replenishment with confirmShelfReplenishment
and cancel the shelf replenishment with cancelShelfReplenishment
.
StockCount
The following operations are available within the StockCount web service.
Operation | Description |
---|---|
lookupStockCountHeaders |
Retrieves list of summary information about a stock count that match the search criteria input. |
readStockCountDetail |
Retrieves the detailed information about a single stock count based on its unique reference. This contains a list of summary information about the child counts. |
readStockCountChild |
Retrieves the detailed information about a single stock count child. |
activateStockCount |
This activates are starts the stock counting process including taking a snapshot of current inventory positions. |
completeStockCountChild |
Completes the counting or recounting of a stock count child, depending on which phase the stock count is in. This process will calculate discrepancies and move the child to the next phase. |
updateCountQuantities |
Updates the counted or recounted quantity fields for a stock count child based on the current phase of the stock count. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the stock count. |
Standard Usage
The stock count web services are design primarily to export information for third party counting. You first lookup the headers, choose your stock count, and then retrieve all the details for the stock count. These details do not contain item information but rather a list of child count references. You can use these references to grab the full details of a child count which includes items and quantities, and then update those quantities.
REST Web Service
A StockCount REST web service exists that allows for the snapshot of a stock count (see REST WEB Services).
Store
The following operations are available within the Store web service.
Operation | Description |
---|---|
lookupAutoReceiveStore |
Retrieves all stores that allow auto-receiving of inventory from the input store. |
lookupAssociatedStore |
Retrieves all stores that are associated to the input store. They are sometimes called buddy stores. |
lookupStoresInTransferZone |
Retrieves all stores in the same transfer zone as the input store. |
readStoreDetail |
Retrieves the detailed information about a single store from the input unique reference. |
Standard Usage
The Store web service is used to retrieve information about stores. There are no updates. They are used to determine such information as whether you can ship to certain stores (such as those in transfer zones).
StoreFulfillmentOrder
The following operations are available within the StoreFulfillmentOrder web service.
Operation | Description |
---|---|
lookuFulfillmentOrdersHeaders |
Retrieves summary information for fulfillment orders that match the search criteria input. |
readFulfillmentOrderDetail |
Reads the complete detailed information about a fulfillment order including items and quantities. |
createFulfillmentOrderDetail |
Creates a new fulfillment order with detailed information, including items and quantities. |
cancelFulfillmentOrderDetail |
Cancels quantities on a fulfillment order. This may cancel the entire order or just reduce or cancel quantities for specific items. |
rejectFulfillmentOrder |
Rejects the fulfillment order indicating that the store will be unable to fulfill that order. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the fulfillment order. |
Standard Usage
Unlike some of the other web services, fulfillment order is not managed within EICS. Instead, EICs manages the picking and delivery, but the order itself is managed by an external order management system.
Oracle Retail Order Broker (OB) calls SIOCS for inventory availability.
Web services are supplied to find and read the details of a fulfillment order, but updates are not allowed. Instead, the external system uses createFulfillmentOrderDetail
to notify EICS of a new order to ship, cancelFulfillmentOrderDetail
to reduce or cancel quantities (note that they cannot be increased) or call rejectFulfillmentOrder
to notify EICS that the order has been rejected.
StoreInventory
The following operations are available within the StoreInventory web service.
Operation | Description |
---|---|
lookupAvailableInventory |
Retrieves basic availability information for multiple items at multiple locations. Only transaction-levels items are processed (UPCs are not allowed) and only current inventory is returned. The service supports up to 200 items at 150 locations. |
lookupAvailableInventoryAllStores |
Retrieves basic availability information for a single item at all store locations. Only transaction-levels items are processed (UPCs are not allowed) and only current inventory is returned. |
lookupAvailableInventoryAllWarehouses |
Retrieves inventory information for a single item at multiple warehouses. Only transaction-level items are processed, and only current inventory is returned. |
lookupInventoryInStore |
Retrieves a broad set of inventory information for several items at several stores, broken down into various inventory groupings. |
lookupInventoryInTransferZone |
Retrieves a broad set of inventory information for items within the specific transfer zone, broken down into various inventory groupings. |
lookupInventoryForBuddyStores |
Retrieves a broad set of inventory information for associated or buddy stores, broken down into various inventory groupings. |
lookupFutureInventory |
Retrieves the future inventory information (such as inbound, ordered quantities and expected dates) for an item and store location. |
Standard Usage
The StoreInventory is meant to retrieve inventory position information. Available inventory lookups are much smaller and quicker to respond than full inventory lookups. Future inventory is separated from current positions as it is much more time consuming to retrieve. Those who access the web services should consider the purpose before choosing which operation to use.
REST Web Service
An InventoryInquiry REST web service exists for inventory lookup and is the preferred service to use in order to retrieve inventory information (see REST WEB Services). This SOAP based web service will be deprecated and eventually removed.
StoreInventoryISN
The following operations are available within the StoreInventoryISN web service.
Operation | Description |
---|---|
lookupIsnTypes |
Returns a complete list of Item Scan Number types. |
lookupIsn |
Returns details about matching Item Scan Numbers in store inventory. |
createIsn |
Create a new Item Scan Number without changing store inventory. |
updateIsn |
Updates an existing Item Scan Number without changing store inventory. |
deleteIsn |
Deletes an Item Scan Number without changing store inventory. |
lookupCustomAttributeAdmins |
Retrieves all the custom attribute admins configured for ISNs. |
Standard Usage
This web service is used to create, update, or delete ISN in store inventory. An item scan number is any number meant to be scanned to find an item, and potentially a Unique Identification Number, that is not already an item, UPC, UIN, VPN, or other value. Items Scan Numbers are only used to find information and are not tracked as inventory.
StoreInventoryUIN
The following operations are available within the StoreInventoryUIN web service.
Operation | Description |
---|---|
createUIN |
Create a new UIN without changing store inventory. |
generateUIN |
Generate new UINs without changing store inventory. |
lookupUINDetails |
Returns details about all the UINs in store inventory for a particular item and store. This is limited to 1000 UINs for a particular item and store. |
readUINDetail |
Returns details about a UIN in store inventory. A UIN reference is not unique, so this may return detailed information for UINs across multiple items. |
updateUIN |
Updates an existing UIN without changing store inventory. |
Standard Usage
This web service is used to create, generate, update, find, or read UINs in store inventory.
StoreItem
The following operations are available within the StoreItem web service.
Operation | Description |
---|---|
lookupItemHeaderByItem |
Retrieves list of summary information about an item that match the item-based search criteria input. |
lookupItemHeaderBySource |
Retrieves list of summary information about an item that match the source or location-based search criteria input. |
lookupItemHeaderByUDA |
Retrieves list of summary information about an item that match the UDA (User Defined Attribute)-based search criteria input. |
lookupItemHeaderByInventory |
Retrieves list of summary information about an item that match the inventory-based search criteria input. |
lookupItemCfa |
Retrieve a list of custom flexible attributes for the specified item and store. |
lookupItemUda |
Retrieve a list of user defined attributes for the specified item and store. |
readItemDetail |
Retrieves the complete detailed information a single item based on its unique reference. |
lookupRelatedItem |
Retrieves a list of summary information about items related to the item used as input criteria. |
saveItemImage |
Inserts a new display image or QR code image for the specified item. The service returns immediately, and the information is processed asynchronously. |
Standard Usage
This web service is used to find items and retrieve information about items. The only exception is the ability to create new image-based information about an item.
StoreItemPrice
The following operations are available within the StoreItemPrice web service.
Operation | Description |
---|---|
lookupItemPriceHeader |
Retrieve a summary list of item price information based on input criteria. This only retrieves information known to EICS and has no access to a pricing system. |
readItemPrice |
Retrieves the full details a single item price record based on its unique reference. |
lookupItemPriceOnEffectiveDate |
Retrieves the item price of an item for a specific date. |
Standard Usage
This web service is used to retrieve information about prices that are known to EICS. Integration with pricing systems updates EICS information about item prices on a continual basis. These web services give a view into EICS information only.
StoreNotification
The following operations are available within the StoreNotification web service.
Operation | Description |
---|---|
createNotification |
Creates a new notification within the system. These notifications are displayed in the client applications. |
Standard Usage
This web service is designed for external system that handle related activities to EICS. With this web service, they can send notifications into EICS of activity that needs to take place based on something that has occurred in another system.
StoreShipmentManifest
The following operations are available within the StoreShipmentManifest web service.
Operation | Description |
---|---|
closeManifest |
Closes the manifest shipments. |
Standard Usage
This web service is designed to close manifest shipments. All manifest shipments matching the input criteria, such like carrier code, and carrier service code will be closed.
StoreShipmentReason
The following operations are available within the StoreShipmentReason web service.
Operation | Description |
---|---|
lookupAllShipmentReasons |
Retrieves all the shipment reasons configured for store shipments. |
Standard Usage
This web service exists to allow customers to retrieve information about shipment reasons that can be assigned to line items on outgoing shipments. The shipment based web services taking the code identifier and thus, you will need to read in these shipment reasons to be able to select and apply valid reason codes.
StoreTicket
The following operations are available within the StoreTicket web service.
Operation | Description |
---|---|
createTickets |
Create a new group of up to 999 tickets to be managed and printed. |
lookupTicketFormats |
Retrieves available ticket formats for the criteria specified. |
Standard Usage
The createTickets
operation is used to create a new group up to 999 tickets to be managed and printed. The ticket formats can be retrieved using lookupTicketFormats
operation based on the criteria specified.
StoreTransfer
The following operations are available within the StoreTransfer web service.
Operation | Description |
---|---|
lookupTransferHeader |
Retrieve a summary list of transfers that matches the input criteria. |
lookupTransferContext |
Retrieves all the transfer context options available to assign to a transfer. |
readTransfer |
Retrieves the detailed information about transfer, including its items and quantities, based on a unique reference. |
createTransferRequest |
Creates a brand new transfer request (Location 1 requesting a transfer from Location 2). |
saveTransferRequest |
Updates a transfer request allowing user to change items and quantities. This must be done prior to requesting it, which finalizes the transfer request. This requires an activity lock. |
createTransfer |
Generates a new transfer that you can add details to. The saveTransfer method must be used to update details such as items and quantities of the transfer. |
saveTransfer |
Updates a previously approved transfer item and quantity details. This operation requires an activity lock. |
saveTransferApproval |
Updates items and quantities on a transfer in requested status that is currently in the process of being approved but has not yet been approved. This operation requires an activity lock. |
requestTransfer |
Updates the status to Requested, finally the transfer request. This allows the opposite location to view the new request for transfer of goods. This operation requires an activity lock. |
approveTransfer |
Approves a transfer request converted the transfer request into an approved transfer. This operation requires having an activity lock. |
rejectTransfer |
Rejects a transfer in request status which prevents the transfer request from becoming a transfer. This operation requires having an activity lock. |
cancelTransfer |
Cancels an approved transfer. This operation requires having an activity lock. |
closeTransfer |
Closes a processed or partially processed transfer finalizing the state of the transfer. This operation requires having an activity lock. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the transfer. |
Standard Usage
The process is started by one store creating a transfer request from a shipping store using createTransferRequest
. The requesting store can continue modifying the transfer request using saveTransferRequest
until it is ready to notify the shipping store, when it then uses the requestTransfer
to send the request to the shipping store. The shipping store can then begin picking items for the transfer and updating the transfer using the saveTransferApproval
operation. When all the quantities the shipping store are willing to ship are determined, the shipping store uses approveTransfer
to finalize the approval of the transfer. Alternatively, they can choose to reject the transfer using rejectTransfer
. It is possible for a shipping store to create a transfer document without going through the request and approval process by using createTransfer
and saveTransfer
.
TransferDelivery
The following operations are available within the TransferDelivery web service.
Operation | Description |
---|---|
lookupTransferDeliveryHeaders |
Retrieves basic information about one or more transfer deliveries that match the criteria specified. This operation is used to find a delivery arriving at the store. |
readTransferDeliveryDetail |
Retrieves the entire set of information about a transfer delivery header based on the identifier you pass to it. |
updateTransferDelivery |
Updates the header information on a transfer delivery. This operation requires an activity lock. |
receiveTransferDelivery |
Receives all the currently open and active containers on a transfer delivery by defaulting quantities into all the unreceived items. This does not move inventory, only defaults quantities. This operation requires an activity lock. |
confirmTransferDelivery |
Confirms a transfer delivery receiving the goods into inventory and updating all the inventory positions. This moves the transfer delivery to a completed status. This operation requires an activity lock. |
lookupTransferDeliveryContainerHeaders |
Retrieves summary information about every container on a transfer delivery based on the unique delivery reference. |
readTransferDeliveryContainerDetail |
Reads the entire details of a container including items and quantities based on a unique container reference. |
createTransferDeliveryContainer |
Generates a new container on the transfer delivery and returns a reference to use so that items and quantity can be added later. |
updateTransferDeliveryContainer |
Updates the items and quantities on a transfer delivery container. This operation requires an activity lock. |
receiveandConfirmTransferDeliveryContainer |
It first defaults receiving quantity on the items within the container and then executes the same locking as the confirmTransferDeliveryContainer. This operation requires an activity lock. |
confirmTransferDeliveryContainer |
Confirms a transfer delivery container as received and updates all the inventory positions. This operation requires an activity lock. |
cancelTranferDeliveryContainer |
Cancels a transfer delivery container moving it to missing status. Changes cannot be made to a canceled container. |
openTransferDeliveryContainer |
Re-opens an already confirmed container moving it back into in-progress status. |
lookupTransferDeliveryOrders |
Retrieves any customer orders associated with the transfer delivery based on the delivery's unique reference. |
lookupMisdirected TransferDeliveryContainers |
Retrieves summary information about containers that may have been misdirected based on a set of search criteria as input into the operation. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the transfer delivery. |
Standard Usage
After reading a transfer delivery using lookupTransferDeliveryHeader
, you can read the header detail with readTransferDelivery
or container list with lookupTransferDeliveryContainers
. You can then use updateTransferDelivery
to update header attributes and updateTransferDeliveryContainer
to update items and quantities in the container. To quickly receive the quantities, receiveTransferDeliveryContainer
automatically fills in quantities, and when quantities are entered confirmTransferDeliveryContainer
finalizes the container (and if appropriate configurations and business rules apply) immediately updates the inventory. If receiveTransferDelivery
or confirmTransferDelivery
is used, then all containers will either be received or confirmed respectively.
TransferShipment
The following operations are available within the TransferShipment web service.
Operation | Description |
---|---|
lookupTransferShipmentHeader |
Retrieves basic information about one or more transfer shipments that match the criteria specified. This operation is used to find a shipment. |
readTransferShipmentDetail |
Retrieves the entire set of information about a transfer shipment header based on a unique reference. |
createTransferShipment |
Creates a new and empty transfer shipment and returns a reference to the shipment. |
saveTransferShipment |
Updates the information on a transfer shipment header. |
submitTransferShipment |
Submits the transfer shipment for review before final dispatch. |
cancelSubmittedTransferShipment |
Cancels the submission of the transfer shipment for review. |
dispatchTransferShipment |
Dispatches a transfer shipment. This moves the shipment to dispatched state and updates the inventory. A transfer shipment cannot be modified after dispatch. Dispatch should occur only after all containers are confirmed. |
cancelTransferShipment |
Cancels a transfer shipment. |
lookupTransferShipmentContainer |
Finds all the containers on a specific shipment and retrieves basic identification information about each container. |
readTransferShipmentContainer |
Reads the specific and complete contents of a container. |
createTransferShipmentContainer |
Creates a new transfer shipment container on the shipment and returns a reference to it. |
saveTransferShipmentContainer |
Updates the information about a transfer shipment container including adding and removing items and quantities. |
confirmTransferShipmentContainer |
Confirms that a transfer shipment container is ready for shipment and marks the container as no longer editable. |
cancelTransferShipmentContainer |
Cancels a transfer shipment container on the shipment. |
openTransferShipmentContainer |
Re-opens a confirmed container on a shipment prior to the shipment being dispatched so that changes can be made to the container. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the transfer shipment. |
Standard Usage
To create a shipment for a transfer document, lookup the transfer shipment using lookupTransferShipmentHeader
. If it does not exist, you may create one for the document using createTransferShipment
. Create a container on the shipment using createTransferShipmentContainer
and update the container with items and quantities using saveTransferShipmentContainer
. Confirm the container using confirmTransferShipmentContainer
. Repeat the process for each container as needed. Once all containers are confirmed, if configured to require submittal, submit the shipment using submitTransferShipment
and finally, dispatch the shipment using dispatchTransferShipment
. Dispatching the shipment finalizes the shipment and relieves the inventory.
VendorDelivery
The following operations are available within the VendorDelivery web service.
Operation | Description |
---|---|
lookupVendorDeliveryHeaders |
Retrieves basic information about one or more vendor deliveries that match the criteria specified. This operation is used to find a delivery from a supplier. |
lookupPurchaseOrderHeaders |
Retrieves basic information about one or more purchase orders that match the criteria specified. |
readVendorDeliveryDetail |
Retrieves the entire set of information about a vendor delivery header based on a unique reference. |
createVendorDelivery |
Generate a new vendor delivery heaver and returns a referenced to the delivery. |
updateVendorDelivery |
Updates the information on a vendor delivery header. This does not include containers, items, or quantities. This operation requires an activity lock. |
receiveVendorDelivery |
Updates the quantities on a vendor delivery filling in any unreceived items within the containers of the delivery with a default value. It "receives" missing quantities, but no inventory positions are updated. This operation requires an activity lock. |
confirmVendorDelivery |
Confirms the vendor delivery updating inventory positions and completing the delivery. This operation requires an activity lock. |
rejectVendorDelivery |
Rejects the vendor delivery placing it in rejected status. This operation requires an activity lock. |
cancelVendorDelivery |
Cancels the vendor delivery placing it in canceled status. This operation requires an activity lock. |
lookupVendorDeliveryContainerHeaders |
Retrieves summary information about every container on a vendor delivery based on the unique delivery reference. |
readVendorDeliveryContainerDetail |
Reads the entire details of a container including items and quantities based on a unique container reference. |
createVendorDeliveryContainer |
Generates a new container on the vendor delivery and returns a reference to use so that items and quantity can be added later. |
updateVendorDeliveryContainer |
Updates the items and quantities on a vendor delivery container. This operation requires an activity lock. |
confirmVendorDeliveryContainer |
Confirms a vendor delivery container as received and updates all the inventory positions. This operation requires an activity lock. |
cancelVendorDeliveryContainer |
Cancels a vendor delivery container moving it to missing status. Changes cannot be made to a canceled container. |
openVendorDeliveryContainer |
Open Vendor delivery container. This will re-open a container after receipt allowing it to be received again. |
lookupVendorDeliveryOrders |
Retrieves any customer orders associated with the vendor delivery based on the delivery's unique reference. |
lookupVendorDeliveryAdjustments |
Retrieves any external receipt adjustments that exist for the delivery based on the specified unique reference. |
cancelSubmitVendorDeliveryContainer |
Opens a submitted container for further updates, moving the status to in-progress. |
submitVendorDeliveryContainer |
Moves the status of the container to submitted and prevents further updates. The container may still be confirmed. No inventory positions are updated via this operation. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the vendor delivery. |
Standard Usage
After reading a vendor delivery using lookupVendorDeliveryHeader
, you can read the header detail with readVendorDelivery
or container list with lookupVendorDeliveryContainers
. Use updateVendorDelivery
to update header attributes and updateVendorDeliveryContainer
to update items and quantities in the container. To quickly receive the quantities, receiveVendorDeliveryContainer
automatically fills in quantities, and when quantities are complete confirmVendorDeliveryContainer
finalizes the container and if appropriate configurations and business rules apply, immediately updates the inventory. If receiveVendorDelivery
or confirmVendorDelivery
is used, then all containers will either be received or confirmed respectively. Re-opening a container can be done using openVendorDeliveryContainer
. To prevent further updates to the container without confirming it, use submitVendorDeliveryContainer
. Submitted container can be re-opened and moved to in-progress status for further updates using cancelSubmitVendorDeliveryContainer
.
VendorReturn
The following operations are available within the VendorReturn web service.
Operation | Description |
---|---|
lookupVendorReturnHeader |
Retrieves basic information about one or more vendors return documents that match the criteria specified. |
readVendorReturnDetail |
Retrieves the entire set of information about a vendor return, including items and quantities, based on a unique reference. |
saveVendorReturn |
Updates the entire set of information about a vendor return, including items and quantities. This operation requires an activity lock. |
approveVendorReturn |
This marks an in-progress vendor return as approve for shipment. This operation requires an activity lock. |
cancelVendorReturn |
Cancels a vendor return indicating no further items and quantities should be shipped for the return. |
closeVendorReturn |
Closes a vendor return document moving it from in-progress to canceled, rejected, or complete status depending on the state of shipped quantities. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the vendor return. |
Standard Usage
The user may access lookupVendorReturnHeader
to find vendor returns to deal with. Once the proper vendor return is found, readVendorReturnDetail
will retrieve all the details of the vendor return including items and quantities. The saveVendorReturn
operation is then used to update quantities that are expected to ship. Once the vendor return reaches its final state, the operation approveVendorReturn
will approve the return and get it ready for shipment.
VendorShipment
The following operations are available within the VendorShipment web service.
Operation | Description |
---|---|
lookupVendorShipmentHeaders |
Retrieves basic information about one or more vendor shipment headers that match the criteria specified. |
lookupReturnContext |
Retrieves all the context options that are available to assign to a vendor return shipment. |
readVendorShipmentDetail |
Retrieves the detailed information about a vendor return header based on a unique reference. It does not include information about containers or items. |
saveVendorShipment |
Creates a new vendor shipment header if not identifying reference is set or updates the vendor shipment header information if a unique reference is sent as part of the date. When used as an update, an activity lock is needed. |
submitVendorShipment |
Submits the vendor shipment for review before final dispatch. |
cancelVendorShipmentSubmission |
Cancels the submission of the vendor shipment for review. |
cancelVendorShipment |
Cancels a vendor shipment. This moves the shipment to canceled status. Changes cannot be made to a canceled shipment. |
dispatchVendorShipment |
Dispatches a vendor shipment. This moves the shipment to dispatched state and updates the inventory. A vendor shipment cannot be modified after dispatch. Dispatch should occur only after all containers are confirmed. This operation requires an activity lock. |
closeVendorShipment |
Closes a vendor shipment using business logic to determine its final state. It cancels the shipment of remaining quantities. Changes cannot be made after a shipment is closed. |
lookupVendorShipmentContainerHeaders |
Retrieves summary information about all containers within a vendor shipment based on the unique reference of the shipment. |
readVendorShipment ContainerDetail |
Reads the specific details, including items and quantities, about a container specified by its unique reference. |
saveVendorShipmentContainer |
Update the details of a container, including items and quantities. This operation requires an activity lock. |
confirmVendorShipmentContainer |
Confirms that the container is ready for shipment. A confirmed container cannot be modified. This operation requires an activity lock. |
cancelVendorShipmentContainer |
Cancels a container on the shipment removing it from the shipment. |
openVendorShipmentContainer |
Opens a confirmed container placing it back into in-progress status so that items can be added or removed from the container. |
lookupCustomAttributeAdmins |
Retrieves the custom attribute administration information that describes what customized attributes are available on the vendor shipment. |
Standard Usage
To create a shipment for a vendor return document, lookup the vendor shipment using lookupVendorShipmentHeader
. If it does not exist, create one using createVendorShipment
. Next, create a container on the shipment using createVendorShipmentContainer
. Update the container with items and quantities using saveVendorShipmentContainer
. Confirm the container using confirmVendorShipmentContainer
. Repeat the process for each container as needed. Once all containers are confirmed, if configured to require submit, then submit using submitVendorShipment
or dispatch the shipment using dispatchVendorShipment
. Dispatching the shipment finalizes the shipment and relieves the inventory.
Enterprise Documentation
Full web service API documentation can be found at:
https://docs.oracle.com/cd/E82085_01/160/RIB%20Integration%20Guide/Output/ServiceTOC.html
REST WEB Services
Web services are intended for integration to allow a system using those services to control the flow and processing of data within EICS. There are multiple types of data involved in this integration. Data that is managed by other systems and needs to get into our system, but that EICS does not manage. This includes such concepts as item, stores, and point-of-sale transaction. Data that is managed by EICS includes such ideas as inventory adjustments, transfers, deliveries, and stock counts. Some services will provide ability for external data to get into EICS, some are intended to be used real time such as approving, picking, and dispatching shipments.
REST WEB Services Security Considerations
The REST web services provided by EICS are secured using OAuth2 tokens and require SSL.
The supported OAuth2 security requires a token requested for the client_credentials grant with the EICS integration scope (for example, rgbu:siocs:integration).
Note that the scope name differs for each environment.
Please see the REST Web Service OAuth2 Requests for details on requesting tokens.
REST WEB Services Basic Design Principles
Requests and Responses
When making requests and processing responses from REST web services it is important for the client to handle headers correctly.
The client should always use Accept for the appropriate content type when making requests.
The client should always check the response status code and Content-Type header before processing a response body.
When reading a payload from the response body, the Content-Length header must be used safely and securely along with the Content-Type.
This is important even for error responses. It is possible for errors to occur outside of the REST API layer, which may produce different content for the error. In these cases, it is common to get text or HTML content for the response body.
API Versioning
Accept-Version
The REST end points have an optional API versioning feature allowing the client to specify an API version to be accepted.
This may be used by the client to ensure that no calls may be made to a web service that uses an incorrect version number.
For example: Accept-Version: 22.1.301
If the web service does not support this API version, then the server will produce a 400 Bad Request error response.
Content-Type
application/json
The content type of both REST input and returned output is application/json.
In the case that no content is included, a content type may not be assigned.
When handling REST service responses, the client must always check the returned Content-Type and Content-Length before processing the payload.
JSON Validation
When consuming a REST service end point that requires a request payload as JSON, the client is responsible for verifying that the JSON is valid. If invalid data is sent in a request, there may be a server error processing the JSON or it may ignore some fields if the JSON is valid but does not map correctly to the API payload definition.
Always make sure that the client sends valid JSON that is designed to satisfy the API payload definition.
Synchronous vs Asynchronous
Each service API will be defined as synchronous or asynchronous. Both perform JSON validation as described above. If the API is synchronous, the remaining data validation and live updating of the data will take place immediately and the call will be rejected if any business errors occur. If the API is asynchronous, the data is set aside to be processed later and the REST service is successfully returned noting that the data has been accepted. In the case of asynchronous processing, business error and failed data recovery is monitored and the dealt with outside of the REST web service.
Configured System Options In EICS
Web services apply system configuration to the request that are coming in through a web service but assumes that all in-put validation that requires user interaction to confirm has been completed by the third party system prior to accessing the service. It operates as if the user confirmed any activity. However, if a system option is a fixed restriction that does not require user interaction, and the input fails the restriction, this is always considered an error.
Examples of configurations being applied include:
Shipping inventory when inventory is less than 0 can be allowed by a user of EICS. The web services assumes that the application accessing the service did prompt the user or that their business always allows the user to this activity.
Adding a non-ranged item requires both a system configuration option to be enabled and the user to confirm the addition of the item. If the system configuration does not allow it, the web service will block the transaction and return an error (un-less processing asynchronously). If the system configuration does allow adding non-ranged items, it will automatically assume that a user confirmed this addition and processing will allow the addition of the item.
Allowing Receiver Unit Adjustments is dependent on a period of time. If a receiver unit adjustment were to come into EICS after that period of time, it would automatically be rejected, and the web service would return an error regardless of presentation or confirmation of user done by the external system.
External vs Internal Attributes
EICS web services are EICS centric and track information from an internal application point-of-view. This has ramifications on three types of data: identifiers, dates, and users.
Almost all paths and information will contain an identifier. In almost all cases, this will be an EICS internal identifier generated without our system. If external identifiers also exist for the date, they will be defined as such in the information. For example, you might encounter transferId and externalTransferId as attributes. In some cases, an API only takes an internal identifier, and you may need to use lookup APIs to retrieve an internal identifier using an external identifier as search criteria.
Timestamps are captured at the time an event occurs within EICS as part of EICS's internal tracking and state management. For example, we capture the timestamp when a shipment is created, last updated, and when it is dispatched. These timestamps occur at the time this occurred within EICS. When a REST service is called to create a transaction, such as a shipment, the create timestamp of the shipment will be the moment that service is called. If the shipment is dispatched using the web service, the dispatch date will be the moment that service is called. So if an external system dispatched a shipment two days earlier, and is just now calling the web service, it will not capture the external dispatch time. In some places, you will encounter a date that can be entered as part of the input information (for example, an externalDispatchDate, or simple a transactionTimestamp). If it is part of the input information, then it will be captured as that attribute defined in the API.
The user responsible for actions is often captured as part of transaction information with EICS. Some examples might be the user that created the data, the user the last updated it, or perhaps the user that approved it. In these cases, the user is considered an internal user as is assigned the current session user at the time the activity takes place. When accessing the REST service, the session user captured as the create user internally will likely be a secured user used to authenticate the web service and not the user that manipulated the information in an external system. If external users are to be captured by the data, there will be independent attribute fields such as externalCreateUser that capture the identity of a user in an external system.
Hypertext Transfer Protocol Status Codes
The following information documents the HTTP status codes that Oracle returns via web services calls.
Success Codes
Successful codes are returned whenever the accessing client call was made without any error in the form or content.
Code | Description |
---|---|
200 OK |
The information supplied by the customer was in a correct form. This code is returned when reading a resource or querying information about an existing resource or schema. This response code is used when the access is synchronous. |
202 Accepted |
The information supplied by the customer as in a correct form. This code is returned when access is asynchronous. |
204 No Content |
The information supplied by the customer was in a correct form. The request was successful but the API itself never provides information as a response. |
Client Failure Codes
Client failure codes indicate the client made an error in their service access and must correct their code or its content to fix the failure.
Code | Description |
---|---|
400 Bad Request |
If this code is returned, it indicates the customer made a call with invalid syntax or violated the defined properties of the input information. Detailed information may be returned that further identifies the error. |
401 Unauthorized 403 Forbidden |
If either of these codes are returned, it indicates the access to service was denied. This may occur if no OAuth2 token was provided, or the token had expired, or the identity the token was generated for did not have sufficient access. |
404 Not Found |
If this code is returned, it indicates the customer made an erroneous access call against a resource or schema that is not defined. |
405 Method Not Allowed |
If this code is returned, it indicates that the wrong HTTP method was used to make the call. Please check the API. |
406 Not Acceptable |
If this code is returned, it indicates the wrong Accept header value was used to make the call. Please check the API. |
409 Too Many Requests |
If this code is returned, it indicates that the web service has received too many service requests recently. This may indicate a cloud issue requiring support to ad-dress or the client is making too many calls too frequently and a solution may be required to avoid the issue. |
System Failure Codes
System failure codes are returned whenever the processing server encounters an unexpected or severe failure.
Code | Description |
---|---|
500 Internal Server Code |
A server error occurred that did not allow the operation to complete. |
502 Bad Gateway 503 Service Unavailable 504 Gateway Timeout |
If any of these codes are returned, it indicates an issue with the network or cloud services, which may occur due to either client or cloud networking or infrastructure issues, such as outages. |
JSON Error Element and Error Codes
If an error occurs in the form of the content, or during processing of the content, an HTTP error code will be returned along with a series of JSON Error Elements as described here.
Example Error
HTTP Response: 400 Bad Request
{
"errors": [
{
"code": 7,
"description": "Missing Attribute",
"dataElement": "storeId",
"referenceElement": "transactionId",
"referenceValue": "1236"
},
{
"code": 11,
"description": "Element Too Large",
"dataElement": "transactionId",
"dataValue": 128,
"referenceElement": "transactionId",
"referenceValue": "1236"
}
]
}
Error Attribute Definintions
Attribute | Definition |
---|---|
Code |
A numeric code indicates the issue. See Integration Error Codes table. |
Description |
The name of the error or issue. |
DataElement |
The name of an attribute or element of the JSON structure that failed. |
DataValue |
The value of the attribute or element that failed, or a piece of information about the element that failed (such as a maximum value). |
ReferenceElement |
The name of an attribute or element that will help further identify the data element. Most often the containing element one level above the failed elements (such as a transaction header). |
ReferenceValue |
The value of the attribute or element that will help further identify the data element. |
Integration Error Codes
The following table contains a listing of the error codes that can be found within returned error information.
Code | Name | Issue |
---|---|---|
1 |
Business Error |
A business processing error prevent the service from completing. |
2 |
Date Range Error |
The date range has a problem (usually indicates end date is earlier than start date in a date range. |
3 |
Duplicate Error |
Indicates duplicate element within the data is not permitted. |
4 |
Forbidden |
Access is not allowed to the service. |
5 |
Internal Server Error |
A severe error occurred with the service attempting to process the request. |
6 |
Invalid Input |
Most often this indicates that input was included that is not allowed or not needed, however it also doubles a kind of catch-all category. |
7 |
Invalid Format |
An input was in an invalid format (most often a date string in a query parameter not being in a valid date format). |
8 |
Invalid Status |
A transaction or entity is not in a valid status to proceed with the request. |
9 |
Missing Path Element |
A path element defining the path of the resource URL was not present. |
10 |
Missing Attribute |
A required attribute was missing on the input to the service. |
11 |
Not Found |
A data element in the input could not be found in the system (most often an invalid identifier). |
12 |
No Data Input |
No input exists for a service that requires input. |
13 |
No Query Input |
No query input exists at all for a query that requires at least one input. |
14 |
Element Too Large |
An input was too large (exceeded maximum count or maximum size). |
15 |
Results Too Large |
The results of the service were too large to return. |
Error Code Data Elements
The following table contains a listing of likely or possible data elements that would be matched with a code. Data element and value may not be returned in all cases.
Code | Name | Data Element | Data Value |
---|---|---|---|
1 |
Business Error |
Business exception name/key |
Data Value |
2 |
Date Range Error |
Date element name |
Value of date |
3 |
Duplicate Error |
Duplicate element name |
Duplicated Value |
4 |
Forbidden |
N/A |
- |
5 |
Internal Server Error |
N/A |
- |
6 |
Invalid Input |
Element name |
Value of element |
7 |
Invalid Format |
Element name |
Value of element |
8 |
Invalid Status |
Element name |
Status of element |
9 |
Missing Path Element |
Missing element |
- |
10 |
Missing Attribute |
Required element name |
- |
11 |
Not Found |
Element not found |
Value of element not found |
12 |
No Data Input |
Missing element |
- |
13 |
No Query Input |
N/A |
- |
14 |
Element Too Large |
Element name |
Allowed size limit |
15 |
Results Too Large |
N/A |
- |
Item Inventory
This service retrieves information about item inventory.
Service Base URL
The Cloud service base URL follows the format:
https://<external_load_balancer>/<cust_env>/siocs-int-services/api/inventory
API Definitions
API | Description |
---|---|
Find Available Inventory |
Search for available inventory information by multiple items and multiple locations. |
Find Inventory |
Searches for standard inventory information by multiple items and multiple locations. |
Find Expanded Inventory |
Searches for expanded inventory information by multiple items at a single store. |
Find Future Inventory |
Searches for future inventory delivery information by a sin-gle item and a single store. |
Find Inventory In Buddy Stores |
Searches for inventory information at buddy stores by single input store and multiple items. |
Find Inventory In Transfer Stores |
Searches for inventory information at transfer zone stores by single input store and multiple items. |
API: Find Available Inventory
Searches for available inventory quantity about an item in requested locations. Only transaction-level items are processed and only current available inventory is returned. The multiplied combination of items and locations within the input criteria cannot exceed 10,000. Invalid items or locations will not cause this API to fail. Inventory is returned for any item and locations found and is not returned invalid or not found items or locations.
API Basics
Endpoint URL |
{base URL}/available |
Method |
POST |
Successful Response |
200 OK |
Processing Type |
Synchronous |
Input |
Criteria |
Output |
List of items |
Max Response Limit |
10,000 |
Input Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
itemIds |
List of Strings |
Yes |
A list of items to retrieve available inventory for. |
locationIds |
List of Longs |
Yes |
A list of location identifiers to retrieve available inventory for. |
locationType |
Integer |
Yes |
A location type: See Location Type |
Example Input
{
"itemIds": [
"100637156",
"100637172",
"100653105"
],
"locationIds": [
5000,
5001,
5005
],
"locationType": 1
}
Output Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
itemId |
String |
Yes |
The item identifier. |
locationId |
Long |
Yes |
The location identifier. |
locationType |
Integer |
Yes |
The location type: See Location Type. |
availableQuantity |
BigDecimal |
Yes |
The amount of available inventory. |
unitOfMeasure |
String |
Yes |
The unit of measure of the available inventory. |
estimatedPack |
Boolean |
Yes |
True if this is an estimated pack quantity, false otherwise. |
Example Output
[
{
"itemId": "100637113",
"locationId": 5000,
"locationType": 1,
"availableQuantity": 200.0000,
"unitOfMeasure": "EA",
"estimatedPack": false
},
{
"itemId": "100637113",
"locationId": 5001,
"locationType": 1,
"availableQuantity": 200.0000,
"unitOfMeasure": "EA",
"estimatedPack": false
},
}
Additional Data Definitions
Location Type
Value | Definition |
---|---|
1 |
Store |
2 |
Warehouse |
API: Find Inventory
Query lookup of detailed inventory information about a multiple item in multiple stores. The multiplied combination of items and locations within the input criteria cannot exceed 10,000. Invalid items or locations will not cause this API to fail. Inventory is returned for any item and locations found and is not returned invalid or not found items or locations.
API Basics
Endpoint URL |
{base URL}/positions |
Method |
POST |
Successful Response |
200 OK |
Processing Type |
Synchronous |
Input |
Criteria |
Output |
List of inventory of item at stores |
Max Response Limit |
10,000 |
Input Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
itemIds |
List of Strings |
Yes |
A list of items to retrieve inventory for. |
storeIds |
List of Longs |
Yes |
A list of store identifiers to retrieve inventory for. |
sellingUnitOfMeasure |
Boolean |
- |
True indicates an attempt to use the selling unit of measure of the item, false indicates to use the standard unit of measure. If conversion cannot take place, it defaults back to standard unit of measure. |
Example Input
{
"itemIds": [
"100637156",
"100637172",
"100668091"
],
"storeIds": [
5000,
5001,
5002
],
"sellingUnitOfMeasure": true
}
Output Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
itemId |
String |
Yes |
The item identifier. |
storeId |
Long |
The store identifier if the item is ranged to a store. |
|
ranged |
Boolean |
Yes |
True if the item is ranged to the store, false otherwise. |
estimated |
Boolean |
Yes |
True if the quantities are estimated, false otherwise. |
unitOfMeasure |
String |
Yes |
The unit of measure of the quantities. |
caseSize |
BigDecimal |
Yes |
The default case size of the item. |
quantityStockOnHand |
BigDecimal |
Yes |
The stock on hand quantity. |
quantityBackroom |
BigDecimal |
Yes |
The quantity located in the back room area. |
quantityShopfloor |
BigDecimal |
Yes |
The quantity located on the shop floor. |
quantityDeliveryBay |
BigDecimal |
Yes |
The quantity located in the delivery bay. |
quantityAvailable |
BigDecimal |
Yes |
The available to sell quantity. |
quantityUnavailable |
BigDecimal |
Yes |
The unavailable to sell quantity. |
quantityNonSellable |
BigDecimal |
Yes |
The total non-sellable quantity. |
quantityInTransit |
BigDecimal |
Yes |
The quantity currently in transit. |
quantityCustomerReserved |
BigDecimal |
Yes |
The quantity reserved for customer orders. |
quantityTransferReserved |
BigDecimal |
Yes |
The quantity reserved for transfers. |
quantityVendorReturn |
BigDecimal |
Yes |
The quantity reserved for vendor returns. |
nonSellableQuantities |
List of Non-Sellable Quantities |
- |
A collection containing the specific quantity in each non-sellable quantity type bucket. |
Non-Sellable Quantity Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
nonsellableTypeId |
Long |
Yes |
The non-sellable type unique identifier. |
quantity |
quantity |
Yes |
The quantity in this particular non-sellable type bucket. |
Example Output
[
{
"itemId": "100637156",
"storeId": 5000,
"ranged": true,
"estimated": false,
"unitOfMeasure": "EA",
"caseSize": 100.00,
"quantityStockOnHand": 10.0000,
"quantityBackroom": 10.0000,
"quantityShopfloor": 0.0000,
"quantityDeliveryBay": 0.0000,
"quantityAvailable": 10.0000,
"quantityUnavailable": 0.0000,
"quantityNonSellable": 0.0000,
"quantityInTransit": 0.0000,
"quantityCustomerReserved": 0.0000,
"quantityTransferReserved": 0.0000,
"quantityVendorReturn": 0.0000
},
{
"itemId": "100637172",
"storeId": 5000,
"ranged": true,
"estimated": false,
"unitOfMeasure": "EA",
"caseSize": 100.00,
"quantityStockOnHand": 10.0000,
"quantityBackroom": -10.0000,
"quantityShopfloor": 0.0000,
"quantityDeliveryBay": 0.0000,
"quantityAvailable": -10.0000,
"quantityUnavailable": 20.0000,
"quantityNonSellable": 20.0000,
"quantityInTransit": 0.0000,
"quantityCustomerReserved": 0.0000,
"quantityTransferReserved": 0.0000,
"quantityVendorReturn": 0.0000,
"nonSellableIdos": [
{
"nonsellableTypeId": 1,
"quantity": 15.0000
},
{
"nonsellableTypeId": 2,
"quantity": 5.0000
}
]
}
}
API: Find Expanded Inventory
Searches for expanded inventory information about multiple items within a single store.
API Basics
Endpoint URL |
{base URL}/{storeId}/expanded |
Method |
POST |
Successful Response |
200 OK |
Processing Type |
Synchronous |
Input |
Criteria |
Output |
List of inventory of items |
Max Response Limit |
2,500 |
Path Parameter Definitions
Attribute | Description |
---|---|
storeId |
The store identifier of the store to process items for. |
Input Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
itemIds |
List of Strings |
Yes |
A list of items to retrieve expanded inventory for. |
Example Input
{
"itemIds": [
"100637156",
"100637172",
"100695081"
]
}
Output Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
itemId |
String |
Yes |
The item identifier. |
storeId |
Long |
The store identifier if the item is ranged to a store. |
|
ranged |
Boolean |
Yes |
True if the item is ranged to the store, false otherwise. |
estimated |
Boolean |
Yes |
True if the quantities are estimated, false otherwise. |
unitOfMeasure |
String |
Yes |
The unit of measure of the quantities. |
caseSize |
BigDecimal |
Yes |
The default case size of the item. |
quantityStockOnHand |
BigDecimal |
Yes |
The stock on hand quantity. |
quantityBackroom |
BigDecimal |
Yes |
The quantity located in the back room area. |
quantityShopfloor |
BigDecimal |
Yes |
The quantity located on the shop floor. |
quantityDeliveryBay |
BigDecimal |
Yes |
The quantity located in the delivery bay. |
quantityAvailable |
BigDecimal |
Yes |
The available to sell quantity. |
quantityUnavailable |
BigDecimal |
Yes |
The unavailable to sell quantity. |
quantityNonSellable |
BigDecimal |
Yes |
The total non-sellable quantity. |
quantityInTransit |
BigDecimal |
Yes |
The quantity currently in transit. |
quantityCustomerReserved |
BigDecimal |
Yes |
The quantity reserved for customer orders. |
quantityTransferReserved |
BigDecimal |
Yes |
The quantity reserved for transfers. |
quantityVendorReturn |
BigDecimal |
Yes |
The quantity reserved for vendor returns. |
firstReceivedDate |
Date |
- |
The first date the item was received into stock. |
lastReceivedDate |
Date |
- |
The date the item last received inventory into stock. |
lastReceivedQuantity |
BigDecimal |
- |
Total amount of inventory received on the last date it was received. |
openStockCounts |
Integer |
- |
The number of stock counts open for the item at this store. |
lastStockCountType |
Integer |
- |
The type of stock count (see Additional Data Definition). |
lastStockCountApprovedDate |
Date |
- |
The date this item was last approved on a stock count at this store. |
lastStockCountTimeframe |
Integer |
- |
The stock count timeframe (see Additional Data Definition). |
uinProblemLine |
Boolean |
Yes |
True indicates it is UIN problem line item, false otherwise. |
lastRequestedQuantity |
BigDecimal |
- |
The quantity last requested for this item. |
lastUpdateDate |
Date |
Yes |
The timestamp of the last time this record was updated. |
nonSellableQuantities |
Collection of Non-Sellable Quantities |
- |
The specific quantities in each non-sellable quantity type bucket. |
Non-Sellable Quantity Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
nonsellableTypeId |
Long |
Yes |
The non-sellable type unique identifier. |
quantity |
quantity |
Yes |
The quantity in this particular non-sellable type bucket. |
Example Output
[
{
"itemId": "100637113",
"storeId": 5000,
"ranged": true,
"estimated": false,
"unitOfMeasure": "EA",
"caseSize": 100.00,
"quantityStockOnHand": 200.0000,
"quantityBackroom": 200.0000,
"quantityShopfloor": 0.0000,
"quantityDeliveryBay": 0.0000,
"quantityAvailable": 200.0000,
"quantityUnavailable": 0.0000,
"quantityNonSellable": 0.0000,
"quantityInTransit": 0.0000,
"quantityCustomerReserved": 0.0000,
"quantityTransferReserved": 0.0000,
"quantityVendorReturn": 0.0000,
"quantityLastReceived": 0.0000,
"quantityLastRequested": 0.0000,
"openStockCounts": 0,
"lastStockCountTimeframe": 3,
"uinProblemLine": false,
"lastUpdateDate": "2022-07-15T06:23:27-05:00"
},
{
"itemId": "100637121",
"storeId": 5000,
"ranged": true,
"estimated": false,
"unitOfMeasure": "EA",
"caseSize": 100.00,
"quantityStockOnHand": 200.0000,
"quantityBackroom": 180.0000,
"quantityShopfloor": 0.0000,
"quantityDeliveryBay": 0.0000,
"quantityAvailable": 180.0000,
"quantityUnavailable": 20.0000,
"quantityNonSellable": 20.0000,
"quantityInTransit": 0.0000,
"quantityCustomerReserved": 0.0000,
"quantityTransferReserved": 0.0000,
"quantityVendorReturn": 0.0000,
"quantityLastReceived": 0.0000,
"quantityLastRequested": 0.0000,
"openStockCounts": 0,
"lastStockCountTimeframe": 3,
"uinProblemLine": false,
"lastUpdateDate": "2022-07-15T06:23:27-05:00",
"nonSellableIdos": [
{
"nonsellableTypeId": 1,
"quantity": 15.0000
},
{
"nonsellableTypeId": 2,
"quantity": 5.0000
}
]
}
}
API: Find Future Inventory
Searches for future delivery records for a single store and single item.
API Basics
Endpoint URL |
{base URL}/{storeId}/{itemId}/future |
Method |
GET |
Successful Response |
200 OK |
Processing Type |
Synchronous |
Input |
None |
Output |
List of delivery records |
Max Response Limit |
N/A |
Path Parameter Definitions
Attribute | Description |
---|---|
storeId |
The store identifier to retrieve future inventory for. |
itemId |
The item identifier to retrieve future inventory for. |
Output Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
itemId |
String |
Yes |
The item identifier. |
storeId |
Long |
Yes |
The store identifier. |
deliveries |
List of deliveryIds |
- |
A list of delivery information if it exists. |
Delivery Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
sourceLocationType |
Integer |
Yes |
Item Location Type (see Additional Data Definition). |
sourceLocationId |
Long |
Yes |
The unique identifier of the source location of the delivery. |
deliveryType |
Integer |
Yes |
Item Delivery Type (see Additional Data Definition). |
expectedDate |
Date |
Yes |
The date the inventory is expected to arrive. |
quantityInbound |
BigDecimal |
Yes |
Amount of inventory inbound on the delivery. |
quantityOrdered |
BigDecimal |
Yes |
Amount of inventory on order. |
Example Output
{
"itemId": "100637121",
"storeId": 5000,
"deliveryIdos": [
{
"sourceLocationType": 1,
"sourceLocationId": 5001,
"deliveryType": 3,
"quantityInbound": 30.0000,
"quantityOrdered": 0.0000
}
]
}
Additional Data Definitions
Item Delivery Type
Value | Definition |
---|---|
1 |
Allocation |
2 |
Purchase Order |
3 |
Transfer |
- |
- |
Item Location Type
Value | Definition |
---|---|
1 |
Store |
2 |
Supplier |
3 |
Warehouse |
4 |
Finisher |
API: Find Inventory in Buddy Stores
Searches for inventory information at buddy stores by single input store and multiple items.
API Basics
Endpoint URL |
{baseUrl}/{storeId}/associated |
Method |
POST |
Successful Response |
200 OK |
Processing Type |
Synchronous |
Input |
List of items |
Output |
List of inventory records |
Max Response Limit |
N/A |
Path Parameter Definitions
Attribute | Description |
---|---|
storeId |
The store identifier to find buddy stores for. |
Input Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
itemIds |
List of Strings |
Yes |
A list of items to retrieve inventory for. |
sellingUnitOfMeasure |
Boolean |
- |
True indicates an attempt to use the selling unit of measure of the item, false indicates to use the standard unit of measure. If conversion cannot take place, it defaults back to standard unit of measure. |
Example Input
{
"itemIds": [
"100637156",
"100637172",
"100668091"
],
"sellingUnitOfMeasure": true
}
Output Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
itemId |
String |
Yes |
The item identifier. |
storeId |
Long |
The store identifier if the item is ranged to a store. |
|
ranged |
Boolean |
Yes |
True if the item is ranged to the store, false otherwise. |
estimated |
Boolean |
Yes |
True if the quantities are estimated, false otherwise. |
unitOfMeasure |
String |
Yes |
The unit of measure of the quantities. |
caseSize |
BigDecimal |
Yes |
The default case size of the item. |
quantityStockOnHand |
BigDecimal |
Yes |
The stock on hand quantity. |
quantityBackroom |
BigDecimal |
Yes |
The quantity located in the back room area. |
quantityShopfloor |
BigDecimal |
Yes |
The quantity located on the shop floor. |
quantityDeliveryBay |
BigDecimal |
Yes |
The quantity located in the delivery bay. |
quantityAvailable |
BigDecimal |
Yes |
The available to sell quantity. |
quantityUnavailable |
BigDecimal |
Yes |
The unavailable to sell quantity. |
quantityNonSellable |
BigDecimal |
Yes |
The total non-sellable quantity. |
quantityInTransit |
BigDecimal |
Yes |
The quantity currently in transit. |
quantityCustomerReserved |
BigDecimal |
Yes |
The quantity reserved for customer orders. |
quantityTransferReserved |
BigDecimal |
Yes |
The quantity reserved for transfers. |
quantityVendorReturn |
BigDecimal |
Yes |
The quantity reserved for vendor returns. |
nonSellableQuantities |
List of Non-Sellable Quantities |
- |
A collection containing the specific quantity in each non-sellable quantity type bucket. |
Non-Sellable Quantity Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
nonsellableTypeId |
Long |
Yes |
The non-sellable type unique identifier. |
quantity |
quantity |
Yes |
The quantity in this particular non-sellable type bucket. |
Example Output
[
{
"itemId": "100637156",
"storeId": 5000,
"ranged": true,
"estimated": false,
"unitOfMeasure": "EA",
"caseSize": 100.00,
"quantityStockOnHand": 10.0000,
"quantityBackroom": 10.0000,
"quantityShopfloor": 0.0000,
"quantityDeliveryBay": 0.0000,
"quantityAvailable": 10.0000,
"quantityUnavailable": 0.0000,
"quantityNonSellable": 0.0000,
"quantityInTransit": 0.0000,
"quantityCustomerReserved": 0.0000,
"quantityTransferReserved": 0.0000,
"quantityVendorReturn": 0.0000
},
{
"itemId": "100637172",
"storeId": 5000,
"ranged": true,
"estimated": false,
"unitOfMeasure": "EA",
"caseSize": 100.00,
"quantityStockOnHand": 10.0000,
"quantityBackroom": -10.0000,
"quantityShopfloor": 0.0000,
"quantityDeliveryBay": 0.0000,
"quantityAvailable": -10.0000,
"quantityUnavailable": 20.0000,
"quantityNonSellable": 20.0000,
"quantityInTransit": 0.0000,
"quantityCustomerReserved": 0.0000,
"quantityTransferReserved": 0.0000,
"quantityVendorReturn": 0.0000,
"nonSellableIdos": [
{
"nonsellableTypeId": 1,
"quantity": 15.0000
},
{
"nonsellableTypeId": 2,
"quantity": 5.0000
}
]
}
}
API: Find Inventory in Transfer Zone Stores
Searches for inventory at transfer zone stores by single input store and multiple items.
API Basics
Endpoint URL |
{baseUrl}/{storeId}/transferzone |
Method |
POST |
Successful Response |
200 OK |
Processing Type |
Synchronous |
Input |
List of items |
Output |
List of inventory records |
Max Response Limit |
N/A |
Path Parameter Definitions
Attribute | Description |
---|---|
storeId |
The store identifier to find transfer zone stores for. |
Input Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
itemIds |
List of Strings |
Yes |
A list of items to retrieve inventory for. |
sellingUnitOfMeasure |
Boolean |
- |
True indicates an attempt to use the selling unit of measure of the item, false indicates to use the standard unit of measure. If conversion cannot take place, it defaults back to standard unit of measure. |
Example Input
{
"itemIds": [
"100637156",
"100637172",
"100668091"
],
"sellingUnitOfMeasure": true
}
Output Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
itemId |
String |
Yes |
The item identifier. |
storeId |
Long |
The store identifier if the item is ranged to a store. |
|
ranged |
Boolean |
Yes |
True if the item is ranged to the store, false otherwise. |
estimated |
Boolean |
Yes |
True if the quantities are estimated, false otherwise. |
unitOfMeasure |
String |
Yes |
The unit of measure of the quantities. |
caseSize |
BigDecimal |
Yes |
The default case size of the item. |
quantityStockOnHand |
BigDecimal |
Yes |
The stock on hand quantity. |
quantityBackroom |
BigDecimal |
Yes |
The quantity located in the back room area. |
quantityShopfloor |
BigDecimal |
Yes |
The quantity located on the shop floor. |
quantityDeliveryBay |
BigDecimal |
Yes |
The quantity located in the delivery bay. |
quantityAvailable |
BigDecimal |
Yes |
The available to sell quantity. |
quantityUnavailable |
BigDecimal |
Yes |
The unavailable to sell quantity. |
quantityNonSellable |
BigDecimal |
Yes |
The total non-sellable quantity. |
quantityInTransit |
BigDecimal |
Yes |
The quantity currently in transit. |
quantityCustomerReserved |
BigDecimal |
Yes |
The quantity reserved for customer orders. |
quantityTransferReserved |
BigDecimal |
Yes |
The quantity reserved for transfers. |
quantityVendorReturn |
BigDecimal |
Yes |
The quantity reserved for vendor returns. |
nonSellableQuantities |
List of Non-Sellable Quantities |
- |
A collection containing the specific quantity in each non-sellable quantity type bucket. |
Non-Sellable Quantity Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
nonsellableTypeId |
Long |
Yes |
The non-sellable type unique identifier. |
quantity |
quantity |
Yes |
The quantity in this particular non-sellable type bucket. |
Example Output
[
{
"itemId": "100637156",
"storeId": 5000,
"ranged": true,
"estimated": false,
"unitOfMeasure": "EA",
"caseSize": 100.00,
"quantityStockOnHand": 10.0000,
"quantityBackroom": 10.0000,
"quantityShopfloor": 0.0000,
"quantityDeliveryBay": 0.0000,
"quantityAvailable": 10.0000,
"quantityUnavailable": 0.0000,
"quantityNonSellable": 0.0000,
"quantityInTransit": 0.0000,
"quantityCustomerReserved": 0.0000,
"quantityTransferReserved": 0.0000,
"quantityVendorReturn": 0.0000
},
{
"itemId": "100637172",
"storeId": 5000,
"ranged": true,
"estimated": false,
"unitOfMeasure": "EA",
"caseSize": 100.00,
"quantityStockOnHand": 10.0000,
"quantityBackroom": -10.0000,
"quantityShopfloor": 0.0000,
"quantityDeliveryBay": 0.0000,
"quantityAvailable": -10.0000,
"quantityUnavailable": 20.0000,
"quantityNonSellable": 20.0000,
"quantityInTransit": 0.0000,
"quantityCustomerReserved": 0.0000,
"quantityTransferReserved": 0.0000,
"quantityVendorReturn": 0.0000,
"nonSellableIdos": [
{
"nonsellableTypeId": 1,
"quantity": 15.0000
},
{
"nonsellableTypeId": 2,
"quantity": 5.0000
}
]
}
}
Service: POS Transaction
This service retrieves information about item inventory.
Service Base URL
The Cloud service base URL follows the format:
https://<external_load_balancer>/<cust_env>/siocs-int-services/api/postransactions
API: Import POS Transactions
POS may integration its transaction to EICS using this web service. The service imports and process point-of-sale transactions through an asynchronous process. The service has a default limit of 1000 total items, though they may be distributed across any number of transactions. Only one store is allowed across all the transaction sent in a single requires.
The web service is optimized for speed at greater than 400 items and less than 500 items per service call. The further above or below this optimized point, processing speed will be reduced and it may take longer for the sales to be recorded in inventory.
Since this import is asynchronous, only the form is validated prior to the data being captured and processed later. See Sales Integration for additional information about processing.
API Basics
Endpoint URL |
{base URL} |
Method |
POST |
Successful Response |
202 Accepted |
Processing Type |
Asynchronous |
Input |
List of transactions |
Output |
None |
Max Input Limit |
- |
Input Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
Transactions |
List of PosTransactions |
Yes |
A list of transactions to process. |
Pos Transaction Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
storeId |
Long |
Yes |
The unique identifier of the store that is the source of the transaction. |
transactionId |
String (128) |
Yes |
A unique identifier of the point-of-sale transaction. |
transactionTimestamp |
Date |
Yes |
The date and time of the transaction. |
customerOrderId |
String (128) |
- |
An external customer order identifier. This attribute is required for customer order related point-of-sale transactions. |
customerOrderComment |
String (512) |
- |
A comment associated to the customer order. |
externalUser |
String (128) |
- |
User information from the external point-of-sale system. |
items |
List of Items |
Yes |
A collection of items belonging to the transaction. |
Pos Transaction Item Data Definition
Attribute | Data Type | Required | Description |
---|---|---|---|
itemId |
String (25) |
Yes |
The transaction-level SKU number of the item. |
quantity |
BigDecimal |
Yes |
The quantity of the item transacted. |
unitOfMeasure |
String (4) |
Yes |
Unit of measure of the quantity. |
uin |
String (128) |
- |
The unique identifier number (serial number). If not empty, the quantity will overwritten with a quantity of one. |
epc |
String (256) |
- |
A complete SGTIN-96 EPC of the item. |
reasonCode |
Integer |
- |
A reason code associated to the line item. This field is required when non-sellable sub-level inventory tracking is active in the system. |
dropShip |
Boolean |
- |
True if this item is a drop ship, false if it is not. Drop ship sales do not impact stock positions. |
fulfillmentOrderId |
String (128) |
- |
If the transaction is associated to a customer order, this is the external fulfillment order identifier. |
fulfillmentOrderLineNumber |
Long |
- |
If the transaction is associated to a customer order, this is the line number of the order that this item transaction aligns with. |
reservationType |
Integer |
- |
If the transaction is a customer order, this is the type of reservation. See Reservation Type. |
transactionCode |
Integer |
Yes |
A code that indicates the transaction event that took place on the item. See Transaction Codes. |
comments |
String (512) |
- |
Comments associated to the line item. |
Example Input
{
"transactions":
[
{
"storeId": 5000,
"transactionId": 1236,
"transactionTimestamp": "2022-04-19T23:59:59-05:00",
"externalUser": "ABC",
"custOrderId": "1111",
"items":
[
{
"itemId": 5678,
"transactionCode": 5,
"reservationType": 1,
"fulfillOrderId": "2222",
"dropShip": false
}
]
}
]
}
Possible Business Exception Codes
In addition to the normal REST error codes, the following business data element may be returned when a business error occurs.
Business Exception Data Definition
Name | Definition |
---|---|
DUPLICATE_TRANSACTION |
One or more the transactions or transaction items are not unique. This will cause the entire request to be rejected. |
Additional Data Definitions
Reservation Type
Value | Definition |
---|---|
1 |
Web Order |
2 |
Special Order |
3 |
Pickup or Delivery |
4 |
Layaway |
5 |
On Hold |
Transaction Code
Value | Definition |
---|---|
1 |
Sale |
2 |
Return |
3 |
Void Sale |
4 |
Void Return |
5 |
Order New |
6 |
Order Fulfill |
7 |
Order Cancel |
Service: Stock Count
The stock count services handle tasks related to a stock count.
Service Base URL
The Cloud service base URL follows the format:
https://<external_load_balancer>/<cust_env>/siocs-int-services/api/stockcounts
API Definitions
API | Description |
---|---|
Snapshot Count |
Snapshots a stock count capturing the current stock on hand quantities. |
API: Snapshot Stock Count
Executes a snapshot of the stock count capturing the current stock on hand quantity of each item on the count. The process of doing a snapshot first determines whether the stock count needs a snapshot and only snapshots those stock counts or stock count children that need a snapshot. If the stock count or stock count child does not need a snapshot, the service is considered successful.
API Basics
Endpoint URL |
/{stockCountId}/snapshot |
Method |
POST |
Successful Response |
204 No Content |
Processing Type |
Synchronous |
Input |
None |
Output |
None |
Path Parameter Definitions
Attribute | Definition |
---|---|
stockCountId |
The internal identifier of the stock count header. |
Sales Integration
EICS integrates with POS systems and Sales Audit systems to ensure that the inventory positions are accurate. This is especially important where accurate up-to-date inventory positions are required to reduce customer disappointment when trying to locate items that appear in inventory or delays in filling customer orders.
POS is the primary source of sales, returns, void, and some customer order transaction information to EICS.
ReSA sends only modified or new POS transaction records to EICS.
POS systems integrated with EICS can do the transaction notifications using a web service.
Sales Audit systems can only communicate through a file import process.
Figure 7-9 POS and Sales Audit Integration
![POS and Sales Audit Integration POS and Sales Audit Integration](img/intg_possales.png)
The following features are part of this integration:
-
Real-time web service integration
-
Batch integration
-
Audited sales data integration
-
Automatic disposition processing for returns
Batch processing and ReSA processing are discussed elsewhere as are the store and system configurations that might determine how the sale is processes.
POS and Sales Audit Process Flow
The following figure shows how a POS, Retail Sales Audit, and EICS are integrated. A POS generates an RTLog containing all the POS transactions and sends it to the Oracle Retail Sales Audit system (ReSA). ReSA sends the audited modified or new transactions to EICS. ReSA also sends the POS transaction upload file to merchandising to update inventory.
Please note that Oracle Retail Xstore is interfaced with EICS to update the inventory transactions near real time only through web service. It does not use batch.
Non-Oracle POS systems can use a batch to import transactions directly into EICS. EICS also processes the POS transactions that have been changed or entered into the sales audit system and updates the inventory based on the delta.
Figure 7-10 POS and Sales Audit Process Flow
![POS and Sales Audit Process Flow POS and Sales Audit Process Flow](img/intg_possalesauditfw.png)
There are two reasons for POS to send sales data directly to EICS and not to the auditing system:
-
Real-time inventory updates to support Commerce Anywhere are critical. A possible round trip from POS to ReSA to EICS takes too long in the dynamic inventory environment of today.
-
POS is the application that owns sales data and ReSA owns audited data. Architecturally, it makes more sense to have data supplied by the owner of that data. POS sends sales data and ReSA sends audit changes to EICS.
Sales and Return Processing
As part of the sales processing, EICS updates the inventory depending on the nature of the transaction. The following are the supported transaction types for the sales processing: Sale, Return, and Post Void of these transactions. The audit system should not modify the post void transactions. A change to a void is not supported by EICS.
Customer Order Processing
In EICS, the Retail Sales Audit import process, POS Transaction import process, and POS Transaction web service process support the following types of customer orders.
-
For layaway and on hold, EICS supports create, update, cancel, and pickup/delivery. For external web order type, only pickup transactions performed in POS are sent to EICS.
-
Pickup transactions, both in-store and external, cannot be voided or modified by sales audit and if these transactions are modified by sales audit system, EICS just drops the transaction and does not process.
Note:
Current Xstore functionality is limited to only layaway and on hold orders. Web order processing is not supported in this release.
Item Disposition
POS can move inventory for return and post void transactions to ’unavailable’ or ’out of stock’. This is especially useful in some environments where items returned must be disposed of or must be reprocessed.
The external sale transaction coming into EICS may include a reason code that is mapped to the inventory adjustment reason codes in EICS. Point of Service maps the EICS reason codes, and the reason codes are sent to EICS in the web service or file extract for the return and post void transactions. EICS first processes the return or post void and updates stock on hand. Next, if the reason code exists, EICS checks this reason code with the one in inventory adjustment reason code table. If a valid match is found, EICS generates an inventory adjustment to notify external systems and execute the disposition instructions tied to the inventory adjustment reason code. Based on the disposition mapped to the reason code, EICS moves the returned inventory to not for sale or out of stock and updates the history trail. If sub-buckets are used, they are also updated if the movement is to not for sale.
If the reason code received is invalid/not present/mapped incorrectly, the system writes an error log and continues to process the stock on hand part of the transaction.
Drop Ship
When the sales records indicate the record is a drop ship, EICS does not perform any processing of this record since the drop ship process implies the inventory is shipped from a third-party location and not from the store.
Item Types
EICS only processes SKU or UPC numbers. GS1 databars, or any other smart barcodes such as VPLUs or Type-E barcodes, should have been extracted to their SKU or UPC number by the POS system.
In addition, EICS only updates inventory for stock holding items. Non-inventory items do not update any stock on hand and are not processed.
Items with the store pack inventory indicator turned off are automatically broken down and the inventory of the component items is updated.
Integration with Customer Order System
CustomerOrderAddressService
When shipping to customer during the fulfillment order workflow, EICS retrieves the address for the order delivery from an external order managements system. When viewing delivery address information within the client application, it also retrieves it from an external system. The web service is defined to connect to an OrderManagementService.
Service Operation | Description |
---|---|
queryCustomerOrderAddress |
Retrieves detailed address information for the order and customer information passed to it. |
CustomerOrderService
This service connects to OrderManagementService to manage customer orders. It includes operations to create a customer order, query for customer orders, pickup/cancel items from a customer order and return items from customer orders.
Service Operation | Description |
---|---|
requestNewCustomerOrderId |
Requests new customer order Id. |
cancelNewCustomerOrderId |
Cancels the new customer order id. |
createCustomerOrder |
Creates customer order. |
queryCustomerOrder |
Queries the customer order present in the system. |
PickupCustomerOrderItems |
Pickup items from the customer order. |
ReturnCustomerOrderItems |
Returns items from the customer order. |
UpdateReceipt |
Updates the receipt of customer order. |
Integration with Manifesting Systems
In order for access to an external manifesting system to take place, the customer must first setup Carrier Type as "Third Party" and the Carrier Service (Manifest Type) must be Parcel (P). Configuration controls whether manifesting is done for a transfer to store, finisher, or warehouse. In addition, configuration controls manifesting for a return to vendor shipment or a customer order delivery.
Carrier services with manifest type of "O" (Other) and "H" (Home Fleet) do not go through the manifesting system. When Manifest Type is "O," EICS prompts the user to enter the carrier address where the shipment is to be sent for fulfillment. Manifest Type of "H" is within the company and therefore, does not prompt the user for an address.
Some carriers require weight, dimension, or both values to be sent in the manifest payload. If so, the carrier's service should have either the weight indicator or carton dimension indicate set to active (or both) during their carrier service setup.
EICS supplies an outbound and inbound Shipment Manifest SOAP web service. The following are supported service operations:
A web service is used to send all the shipment information to the external manifesting system and also to receive close shipment requests from external systems.
A web service accepts requests from external systems to close shipments. It is used to find those "Submitted" shipments for the provided tracking ID, carrier, service and date, and dispatch those shipments.
Note:
EICS supplies a WSDL and XSD that defines the web service, operation, and data content. This web service will need to be implemented either for the manifesting system or a plug-in set up.
ShipmentManifestService
This web service notifies an external manifesting system that a manifest needs to be created.
Service Operation | Description |
---|---|
createManifest |
Requests the external manifesting system to create a new parcel manifest for an input transaction. |
StoreShipmentManifestService
This web service receives a message from an external manifesting system that the items on the manifest have been picked up.
Service Operation | Description |
---|---|
closeManifest |
Instructs EICS that submitted shipments have been picked up by the carrier. |
Integration for Notifications
StoreExtNotificationService
When store order with external ID is approved, EICS sends notification to the external system.
This service is applicable only for externally created store orders.
Service Operation | Description |
---|---|
createNotification |
Sends notification to external system on approving the externally created store orders with its items information. |
Integration for Sales Forecast
SalesForecastService
EICS may retrieves item sales forecasting information from a third-party sales forecasting system.
Service Operation | Description |
---|---|
retrieveSalesForecast |
Retrieves sales forecast data for the next 30 days for a particular item and store. |
Integration for Store Order
OrderApproveNotificationService
When store order is approved, EICS sends notification to a third-party item management system.
This notification will be sent out for store orders that are created manually or system generated.
It is not applicable to store orders created by external system.
Service Operation | Description |
---|---|
orderRequestApproved |
Sends notification to external item management system that the order request is approved. |
StoreExtNotificationService
When store order with external ID is approved, EICS sends notification to the external system.
This service is applicable only for externally created store orders.
Service Operation | Description |
---|---|
createNotification |
Sends notification to external system on approving the externally created store orders with its items information. |
Integration for Ticket Printing
When printing tickets, EICS sends ticket information to an external system for printing. This web service needs to be implemented for printing tickets to a physical printer.
TicketPrintService
Service Operation | Description |
---|---|
printTickets |
Sends item tickets to an external system to be printed. It must be implemented by the external system to receive the tickets. |
Retail Home Integration
EICS now supports following integration scenarios with Retail Home:
-
Launch SIOCS web client from Retail Home
-
Launch SIOCS favorites from Retail Home
-
Display a tile report for items that are out of stock on shop floor
-
Display a tile report for stock counts that are pending authorization
-
Launch detailed operational views in SIOCS web client from related tile reports in Retail Home
Launch SIOCS from Retail Home
Launching SIOCS client requires an entry to be made under the application navigator section of Retail Home. It enables the user to launch SIOCS web client in a new browser tab from within Retail Home. Please refer to Oracle Retail Home Administration Guide for information on how to work with application navigator in Retail Home.
The SIOCS application configuration should look like this:
Figure 7-11 Add Application Info
![Add Application Info Screen Add Application Info Screen](img/intg_addappinfo.png)
-
Seeded: Disabled and set to No.
-
Application Navigator: Enable it to launch SIOCS client from Retail Home.
-
Application Name: The name of the application that is, Store Inventory Operations Cloud.
-
Color Set: Any color that you want to allocate to SIOCS.
-
Application Code: Select SIOCS from the drop down.
-
Application Link: The URL of SIOCS web client.
-
Platform Service: Enable it to use Favorites feature.
-
URL: The base URL of the platform services. The URL would be of the form
https://<SIOCS-HOST>/RetailAppsPlatformServices
<SIOCS-HOST> is the same host in Application Link.
-
Supported Features: Check only the favorites feature.
-
The user needs to be part of RETAIL_HOME_ADMIN security group in order to access Application Navigator in Retail Home.
Tile Reports
EICS supports following two types of two metric reports:
-
Shop Floor Out of Stock Items
-
Stock Counts - Ready to Authorize
Adding an application navigator entry for SIOCS will automatically configure EICS tiles on Retail Home.
The data seed features do the following:
-
Creates a custom report for EICS tiles on Retail Home.
-
Creates two tiles from the custom report and maps them to retail_home_users IDCS or OCI IAM application role.
-
The data seed features will also configure tile states for the two tiles and hook them up with EICS end points.
After all the configuration, you should be able to see EICS tiles on the dashboard. They should look like the ones below:
Figure 7-12 Example EICS Tiles
![Example EICS Tiles Example EICS Tiles](img/intg_shopfloor.png)
EICS Endpoints
EICS exposes following two endpoints:
Shop Floor Out of Stock Items
This endpoint can be used as a data source for Shop floor Out of Stock tile state.
The response contains information on number of items that are out of stock across all the stores that are accessible to the user.
If the percentage of out of stock items to total items is greater than the Shopfloor Out of Stock Items Critical Percentage system configuration, EICS marks the response as important which displays a '!' mark next to the number on the tile report.
Table 7-1 Shop Floor Out of Stock
Endpoint | Operational View |
---|---|
https://<eics_external_load_balancer_address>/<CUST_ENV>/siocs-client-services/internal/rhreports/outofstock/shopfloor/tile |
Shopfloor Out of Stock |
Stock Counts - Ready to Authorize
This endpoint can be used as a data source for Stock Count - Ready to Authorize tile state.
The response contains information on number of stock counts that are pending authorization across all stores that are accessible to the user.
Table 7-2 Stock Counts - Ready to Authorize
Endpoint | Operational View |
---|---|
https://<eics_external_load_balancer_address>/<CUST_ENV>/siocs-client-services/internal/rhreports/readytoauthorize/tile |
Stock Count - Ready To Authorize |
The response payloads of both these endpoints confirm to the two metric payload specifications of Retail Home.
User should be a part of retail_home_users IDCS or OCI IAM application role to access these endpoints.
For convenience, EICS also provides a RETAIL HOME security role that captures security permissions required to access these operational views. The user still needs appropriate functional area permissions to navigate to transaction detail screens.
SIOCS Operational Views
EICS has added following operational views that can be hooked with related tiles:
-
Shopfloor Out of Stock Items
This view gives a store and item level breakdown of the information that is displayed on the tile. The user can look at item level records for each store and navigate to the item detail screen for any store/item combination provided he or she has the required permissions.
This view is available under Operations / Operational Views / Shopfloor Out of Stock menu.
-
Stock Count - Ready to Authorize
This view gives a store and stock count level breakdown of the information that is displayed on the tile. The user can look at stock count level records for each store and navigate to the stock count detail for any store/count combination provided he or she has the required permissions.
This view is available under Operations / Operational Views / Stock Count / Ready to Authorize menu.
Launch SIOCS Operational Views from Tile Report
Launching SIOCS operational views from related tile report requires the tile report to be configured with the URL of the related operational view. Once that is done, clicking on tile report header should open the related EICS operational view in a new browser tab.
Subscription Usage Batch
EICS has added a new batch to extract subscription usage for EICS and SOCS respectively during the subscription period. These extracted metrics are pushed to platform services from where Retail Home displays these on the Application Dashboard screen.
This is a restricted batch which by default is scheduled to run every month. The schedule can only be updated by a sysop user.
It can also be run as an Adhoc batch from EICS / Admin / Technical Maintenance / Job Admin / Adhoc Job.
REST Web Service OAuth2 Requests
This section will describe how to call an EICS web service using the OAuth2 protocol. The target audience is developers who are looking to write code that calls the web service.
Using the OAuth Protocol
The OAuth protocol is relatively straightforward:
-
Get an access token from the authentication provider
-
Pass the access token along with the web service request
In this case, the authentication provider is Oracle Identity Cloud Service (IDCS). Every customer who purchases a subscription to EICS gets a subscription to IDCS as part of their purchase.
Obtaining a Token
To generate a token from IDCS an IDCS application client will need to be created for you to use.
This is created during provisioning but for special situations additional application clients can be made in IDCS after provisioning.
You will need the following information about the IDCS application client to request a token:
-
IDCS URL
-
Client Id
-
Client Secret
-
Scope Name
Note:
the application client must be assigned the scope from the EICS IDCS cloud service in order to request the token. This assignment is performed when the application client is created.
The scope name will differ for each environment. Please ensure the correct value is used for your environment.
To generate a token, you will need to invoke the appropriate IDCS REST API. The curl command in Linux that describes the POST that will return a token is as follows:
curl -H 'Authorization: Basic <base64(clientId:clientSecret)>' -H 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' --request POST <IDCS URL>/oauth2/v1/token -d 'grant_type=client_credentials&scope=<EICS Scope>'
In Windows, use double-quotes, as follows:
curl -H "Authorization: Basic <base64(clientId:clientSecret)>" -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" --request POST <IDCS URL>/oauth2/v1/token -d "grant_type=client_credentials&scope=<EICS Scope>"
This is a standard REST POST, with the following details:
-
<IDCS URL> is the IDCS URL the retailer provided
-
Include the Client Id and Client Secret as a Basic Authentication header
-
Specify the Content Type as application/x-www-form-urlencoded;charset=UTF-8
-
Specify the body as grant_type=client_credentials&scope=<EICS Scope>
The service will respond with the following JSON message:
{
"access_token": "<TOKEN>",
"token_type": "Bearer",
"expires_in": 3600
}
Note that the response will return how long the token is valid for. You should reuse the same token until it expires in order to minimize calls to IDCS to get a token.
If the token request fails, you will receive the following JSON response:
{
"error":"<error>",
"error_description":"<error description>",
"ecid":"u….."
}
The most common errors are:
-
Invalid Client. This means that the client information you send in is not correct. The error description will expand on the reason:
-
Client Authentication Failed means that the client is valid, but the client secret is incorrect.
-
Invalid OAuth Client <CLIENT> means that the client id is not valid, and the invalid client will be listed in the error message.
-
-
Invalid Request. Some part of the inbound request is not valid. The error description is usually descriptive about what the actual error condition is
Calling the EICS Web Service
To invoke the web service with an OAuth2 token, you must add an Authorization header to the request. The value of the Authorization header must be Bearer <token>, that is:
-
The word Bearer
-
A space
-
A valid token
For a REST service call, the request might look something like this:
curl -X POST -H 'Content-Type: application/json' -H 'Authorization: Bearer <TOKEN>' -i https://CloudServiceURL --data '{PAYLOAD}'
Remember that the token will expire after a specific amount time, and to be more efficient you should always use a token so long as it's valid. It is your responsibility to make sure that you are keeping track of whether the token is still valid. Your pattern should be:
-
Check to see if you have a valid token that has not expired.
-
If not, call to IDCS and get a new token. Store it and its expiration time.
-
Send the request into the web service with the token in the Authorization header as a Bearer token.