Upload
vodang
View
213
Download
0
Embed Size (px)
Citation preview
Introducing the Inventory Inquiry API (REST)
ADD TO CART XML API GUIDE 11/22/13 | PAGE 1
SHOPATRON
Inventory Inquiry API Guide Version 3 REST
Revision/
Version
Number
Summary of Modifications Date Author/Writer Subject Matter
Expert(s)
3.0 Initial release for this version. November 22, 2013 Michael Lujan Dave Miller,
James Elliot
Copyright © 2013 Shopatron, Inc.
Shopatron North America
Shopatron, Inc.
P.O. Box 5351
San Luis Obispo, CA, 93403
Shopatron Europe
Shopatron UK, Ltd.
Newport House
19-21 Newport Street
Old Town, Swindon SN1 3DX
Contents
Introducing the Inventory Inquiry API (REST) .......................................................... 4
Getting Started ............................................................................................................ 4
Before you begin ................................................................................................................ 4
Obtaining API access ........................................................................................................ 4
System requirements ......................................................................................................... 4
Inventory Inquiry API Call ........................................................................................... 4
getInventory ........................................................................................................................ 5
Resource information......................................................................................................... 5
Request data parameters .................................................................................................. 5
Request header ................................................................................................................. 7
Example request ................................................................................................................ 7
Response data elements ................................................................................................... 9
Success response ........................................................................................................... 10
Handling Errors ......................................................................................................... 11
Country Codes .......................................................................................................... 12
HTTP Error Codes ..................................................................................................... 13
Introducing the Inventory Inquiry API (REST)
INVENTORY INQUIRY API GUIDE VERSION 3 REST 11/22/13 | PAGE 4
Introducing the Inventory Inquiry API (REST)
Shopatron's Inventory Inquiry API allows you to share your real-time inventory information among
multiple fulfillment locations.
REpresentational State Transfer (REST) is a style of software architecture for distributed systems such
as the World Wide Web. REST has emerged as a predominant Web service design model.
Getting Started
NOTE: Shopatron usually recommends the Inventory Inquiry API to developers who have experience with REST as well as to those who have a dedicated IT staff of capable programmers and a web-capable database for product and order data storage.
Before you begin
Obtaining API access
Before you can use the Inventory Inquiry API functions described in this guide, you will need to contact
Shopatron Merchant Support at (877) 715-7467 or send email to [email protected] to obtain the
information to configure your account.
System requirements
To use the Inventory Inquiry API, you need a client with Internet access that runs your own REST client
to send data to the Shopatron server.
NOTE:
Shopatron reserves the right to disallow the use of this API if the user violates Shopatron policies. Before we take this action, we attempt to contact the user. Additionally, we reserve the right to augment or modify this API at any time. This includes changing the number of, name of, and placement of data attributes and the queue schedule by which this API operates. While we will make every effort to provide regression support for older versions, you should prepare your application to anticipate updates. We do not recommend hard-coding the attribute placement by number, as the order of the attributes may change.
Inventory Inquiry API Call
This document contains information about the Inventory Inquiry (REST) Web service getInventory
call.
Inventory Inquiry API Call
INVENTORY INQUIRY API GUIDE VERSION 3 REST 11/22/13 | PAGE 5
getInventory
Resource information
Call Syntax/URL https://api.shopatron.com/coex/services/rest/client/v3/
inventory/post_query
Synopsys Returns an array of inventory items given a set of criteria.
Version 3
HTTP Method POST
Supported Formats JSON
Request data parameters
Refer to this table for details for defining request data parameters.
Parameter Required Data Type Description
manufacturerID Yes Integer Shopatron manufacturer ID.
catalogID Yes Integer The Shopatron-assigned catalog ID.
type Yes Enumeration An enumeration of strings for the type of
request being made:
ANY - fulfillment locations that have partial
quantities of line items in stock
ALL - fulfillment locations that have all
complete line items in stock
PARTIAL - fulfillment locations that have
some complete line items in stock
ALL_STORES – all fulfillment locations
that have all complete line items in stock
postalCode No String All locations with the specified postal code.
latitude Yes, but only
if longitude is
in the
request
Number The latitude coordinates for the location.
Inventory Inquiry API Call
INVENTORY INQUIRY API GUIDE VERSION 3 REST 11/22/13 | PAGE 6
Parameter Required Data Type Description
longitude Yes, but only
if latitude is
in the
request
Number The longitude coordinates for the location.
countryCode No String All locations with the specified country code.
radius No Number The radius from the specified point within
which to search. The point is specified by
latitude/longitude or zip code.
unit No Enumeration The unit in which the radius will be
interpreted:
M – Miles
KM - Kilometers
limit No Integer The maximum number of results to return.
ignoreSafetyStock No Boolean Should the results ignore safety stock?
includeNegativeInventory No Boolean Should the results include negative
inventory?
STSEnabled No Boolean Does the location have STS enabled?
STHEnabled Boolean Does the location have STH enabled?
ISPUEnabled No Boolean Does the location have ISPU enabled?
locationNames No String Location name when coupled with
fulfillerID uniquely identifies a
Fulfillment Location.
items Yes Array of
objects
Each object contains these properties:
partNumber, UPC, SKU, and quantity.
partNumber Conditional String An item property. The part number for the
item, as assigned by the manufacturer.
UPC Conditional String An item property. The merchant's Universal
Product Code (UPC) for this item.
SKU Conditional String An item property. Fulfillment Location-
specific stock keeping unit (SKU), if available.
Inventory Inquiry API Call
INVENTORY INQUIRY API GUIDE VERSION 3 REST 11/22/13 | PAGE 7
Parameter Required Data Type Description
quantity Yes, with at
least one of
the other
items
properties
Integer An item property. The number of units of this
item the consumer wants.
Request header
API-Key : <apikey>
Content-Type: application/json
Example request
{
"title": "Get Inventory Query",
"type": "object",
"properties": {
"manufacturerID": {
"title": "Manufacturer Identifier",
"type": "integer",
"minimum": 0
},
"catalogID": {
"title": "Catalog Identifier",
"type": "integer",
"minimum": 0
},
"type": {
"title": "Request Type",
"enum": [
"ANY",
"ALL",
"PARTIAL",
"ALL_STORES"
]
},
"postalCode": {
"title": "Postal Code",
"type": "string"
},
"latitude": {
"title": "Latitude",
"type": "number"
},
"longitude": {
"title": "Longitude",
"type": "number"
},
"countryCode": {
"title": "Country Code",
"type": "string"
},
"radius": {
"title": "Radius from lat/lon or zip to search within",
"type": "number"
},
Inventory Inquiry API Call
INVENTORY INQUIRY API GUIDE VERSION 3 REST 11/22/13 | PAGE 8
"unit": {
"title": "Radius from lat/lon or zip to search within",
"enum": [
"M",
"KM"
]
},
"limit": {
"title": "The maximum number of results to return",
"type": "integer",
"minimum": 1
},
"ignoreSafetyStock": {
"title": "Should the results ignore safety stock",
"type": "boolean"
},
"includeNegativeInventory": {
"title": "Should the results include inventory less than 0",
"type": "boolean"
},
"STSEnabled": {
"title": "Does the location have STSEnabled",
"type": "boolean"
},
"STHEnabled": {
"title": "Does the location have STHEnabled",
"type": "boolean"
},
"ISPUEnabled": {
"title": "Does the location have ISPUEnabled",
"type": "boolean"
},
"locationNames": {
"title": "Fulfiller Location Names",
"type": "array",
"items": {
"title": "Location Name",
"type": "string"
}
},
"items": {
"title": "Product Information to query for",
"type": "array",
"items": {
"type": "object",
"properties": {
"partNumber": {
"title": "Part Number",
"type": "string"
},
"UPC": {
"title": "Universal Product Code",
"type": "string"
},
"SKU": {
"title": "Stock Keeping Unit",
"type": "string"
},
"quantity": {
"title": "Number being requested",
"type": "integer",
"minimum": 0
Inventory Inquiry API Call
INVENTORY INQUIRY API GUIDE VERSION 3 REST 11/22/13 | PAGE 9
}
}
}
}
},
"additionalProperties": false,
"required": [
"manufacturerID",
"catalogID"
]
}
Response data elements
Refer to this table for details for the data elements returned.
Element Data Type Description
locationName String Location name when coupled with fulfillerID uniquely
identifies a Fulfillment Location.
ManufacturerID Integer Shopatron manufacturer ID.
CatalogID Integer The Shopatron-assigned catalog ID.
OnHand Integer Number of on-hand inventory items.
Available Integer Number of inventory items available at the physical Fulfillment
Location which can be ordered.
PartNumber String Vendor-specific part number.
UPC String Vendor-specific UPC.
SKU String Fulfillment Location-specific UPC, if available.
LTD Double "Lifetime To Date." This is a flexible sales metric that may be
defined and interpreted any way the manufacturer prefers; for
example, the sales velocity metric (sales / days in operation).
Floor Integer "Floor" is a term used to describe a flexible threshold. With
respect to the example for 'safety stock' below, this threshold
can be, for example, the number of items in stock a
manufacturer can drop down to before some sort of email
notification is sent out to someone (as opposed to Safety
Stock, below).
Inventory Inquiry API Call
INVENTORY INQUIRY API GUIDE VERSION 3 REST 11/22/13 | PAGE 10
Element Data Type Description
SafetyStock Integer "Safety stock" is a term used to describe a flexible threshold.
With respect to the example of 'floor' above, this threshold can
be, for example, the number of items in stock that a
manufacturer can drop down to before it stops fulfilling orders
altogether.
Distance Number Distance from the location from which the query is made.
STHEnabled Boolean Whether or not the store has enabled Ship to Home.
RestockEnabled Boolean Whether or not the store has enabled restock.
PickupEnabled Boolean Whether or not the store has enabled pickup.
US String The country code for the location
STHRank Integer Ship to Home Ranking.
Restock Integer Restock Ranking.
Success response
{
"title": "Get Inventory Response",
"type": "array",
"items" : {
"type": "object",
"properties": {
"locationName" : {
"title": "The Name of the Location",
"type": "string"
},
"ManufacturerID": {
"title": "Manufacturer Identifier",
"type": "integer",
"minimum": 0
},
"CatalogID": {
"title": "Catalog Identifier",
"type": "integer",
"minimum": 0
},
"OnHand": {
"title": "Number of Items On Hand",
"type": "integer",
},
"Available": {
"title": "Number of Items Available",
"type": "integer",
},
"PartNumber": {
"title": "Part Number",
"type": "string"
Handling Errors
INVENTORY INQUIRY API GUIDE VERSION 3 REST 11/22/13 | PAGE 11
},
"UPC": {
"title": "Universal Product Code",
"type": "string"
},
"SKU": {
"title": "Stock Keeping Unit",
"type": "string"
},
"LTD": {
"title": "Life to Date",
"type": "integer",
},
"Floor": {
"title": "Number of Items on the Store Floor",
"type": "integer",
},
"SafetyStock": {
"title": "Number of Items Needed at the store in case
somebody wants to buy it",
"type": "integer",
},
"Distance": {
"title": "Distance from the location queried for",
"type": "number",
},
"STHEnabled": {
"title": "Whether the store has Ship to Home enabled",
"type": "boolean",
},
"RestockEnabled": {
"title": "Whether the store has restock enabled",
"type": "boolean",
},
"PickupEnabled": {
"title": "Whether the store has pickup enabled",
"type": "boolean",
},
"US": {
"title": "The country code for the location",
"type": "string"
},
"STHRank": {
"title": "Ship to Home Ranking",
"type": "integer",
},
"Restock": {
"title": "Restock Ranking",
"type": "integer",
}
}
}
}
Handling Errors
If you receive an error response fault code when you send the order information to Shopatron, follow
these steps:
Country Codes
INVENTORY INQUIRY API GUIDE VERSION 3 REST 11/22/13 | PAGE 12
1. Record the outgoing package and the associated fault code response from Shopatron.
2. Test for connectivity to the server.
3. Hold the REST package for future transmission to Shopatron's servers.
4. Send an email to Shopatron Merchant Support at [email protected]; include the time and date
of the failed transmission.
5. When Shopatron support staff contacts you, resend the failed attempts.
Country Codes
Refer to these codes for parameter elements pertaining to country codes.
Country 2-Character Country
Code
Country 2-Character Country
Code
Anguilla AI Ireland IE
Antigua & Barbuda AG Italy IT
Argentina AR Japan JP
Aruba AW Korea, South KR
Australia AU Kuwait KW
Austria AT Liechtenstein LI
Bahamas BS Luxembourg LU
Barbados BB Macao MO
Belgium BE Malaysia MY
Belize BZ Martinique MQ
Bermuda BM Netherlands NL
Bhutan BT Netherlands Antilles AN
Brazil BR New Caledonia NC
British Virgin Islands VG New Zealand NZ
Canada CA Norway NO
Chile CL Portugal PT
HTTP Error Codes
INVENTORY INQUIRY API GUIDE VERSION 3 REST 11/22/13 | PAGE 13
Country 2-Character Country
Code
Country 2-Character Country
Code
China CN Reunion Island RE
Costa Rica CR Saint Lucia LC
Czech Republic CZ Saint Pierre & Miquilon PM
Denmark DK San Marino SM
Egypt EG Singapore SG
Fiji FJ Solomon Islands SB
Finland FI South Africa ZA
France FR Spain ES
French Polynesia PF Sweden SE
Germany DE Switzerland CH
Great Britain GB Taiwan TW
Greece GR Thailand TH
Greenland GL Trinidad & Tobago TT
Guadeloupe GP United Arab Emirates AE
Guam GU United Kingdom GB
Hong Kong HK United States of
America
US
Iceland IS Vatican City VA
India IN
HTTP Error Codes
Code Description
400 Bad Request. The request could not be understood by the server due to malformed syntax.
The client should not repeat the request without modifications.
401 Unauthorized. The request requires user authentication. The response must include a
WWW-Authenticate header field containing a challenge applicable to the
requested resource. The client may repeat the request with a suitable
Authorization header field. If the request already included Authorization
HTTP Error Codes
INVENTORY INQUIRY API GUIDE VERSION 3 REST 11/22/13 | PAGE 14
Code Description
credentials, then the 401 response indicates that authorization has been
refused for those credentials. If the 401 response contains the same
challenge as the prior response, and the user agent has already attempted
authentication at least once, then the user should be presented the entity that
was given in the response, since that entity might include relevant diagnostic
information. HTTP access authentication is explained in HTTP Authentication:
Basic and Digest Access Authentication.
403 Forbidden. The server understood the request, but is refusing to fulfill it. Authorization will
not help and the request should not be repeated. If the request method was
not Head, and the server wishes to make public why the request has not been
fulfilled, it should describe the reason for the refusal in the entity. If the server
does not wish to make this information available to the client, the status code
404 (Not Found) can be used instead.
404 Not Found. The server has not found anything matching the Request-URI. No indication is
given of whether the condition is temporary or permanent. The 410 (Gone)
status code should be used if the server knows, through some internally
configurable mechanism, that an old resource is permanently unavailable and
has no forwarding address. This status code is commonly used when the
server does not wish to reveal exactly why the request has been refused, or
when no other response is applicable.
409 Conflict. The request could not be completed due to a conflict with the current state of
the resource. This code is only allowed in situations where it is expected that
the user might be able to resolve the conflict and resubmit the request. The
response body should include enough information for the user to recognize
the source of the conflict. Ideally, the response entity would include enough
information for the user or user agent to fix the problem; however, that might
not be possible and is not required.
Conflicts are most likely to occur in response to a PUT request. For example,
if versioning were being used and the entity being PUT included changes to a
resource which conflict with those made by an earlier (third-party) request, the
server might use the 409 response to indicate that it can't complete the
request. In this case, the response entity would likely contain a list of the
differences between the two versions in a format defined by the response
Content-Type.
413 Request Entity Too Large. The server is refusing to process a request because the request entity is
larger than the server is willing or able to process. The server may close the
connection to prevent the client from continuing the request.
If the condition is temporary, the server should include a Retry- After header
field to indicate that it is temporary as well as after what time the client MAY
try again.
500 Internal Server Error. The server encountered an unexpected condition which prevented it from
fulfilling the request.