Get Close Retailers API Guide

Transcription

1 Introducing the Get Close Retailers API XML-RPC Get Close Retailers API Guide Version 2.0 CANNOT SHIP ORDER API GUIDE 10/29/13 PAGE 1

2 Revision History Revision/ Version Number Summary of Modifications Date Author/Writer Subject Matter Expert(s) 2.0 Converted to new branding template; minor style and format modifications; minor revisions to Getting Started. May 31, 2013 Michael Lujan Dave Miller 2.0 Revised the section titled, Obtaining your API key to Obtaining API access (not based on a key) October 28, 2013 Michael Lujan Dave Miller Copyright 2013 Shopatron, Inc. Get Close Retailers API Guide, Version 2.0 This document contains proprietary and confidential information of Shopatron, Inc., and is protected by Federal copyright law. The contents of this document may not be disclosed to third parties, translated, copied, or duplicated in any form, in whole or in part, (or by any means, electronic, mechanical, photocopying, or otherwise) without the express written permission of Shopatron, Inc. The information contained in this document is subject to change without notice. Neither Shopatron, Inc., its affiliates, nor their directors, officers, employees, or agents, are responsible for punitive or multiple damages or lost profits or other special, direct, indirect, incidental, or consequential damages, including any damages resulting from loss of business arising out of or resulting from the use of this material, or for technical or editorial omissions or errors made in it. Aspects of the Shopatron network are patented, patent-pending, or patent-applied for. Shopatron North America Shopatron, Inc. P.O. Box 5351 San Luis Obispo, CA, Shopatron Europe Shopatron UK, Ltd. Newport House Newport Street Old Town, Swindon SN1 3DX

3 Contents Introducing the Get Close Retailers API... 4 Getting Started... 4 Before you begin... 4 Obtaining API access... 4 System requirements... 5 Writing the application... 5 Process flow... 5 Programming the Get Close Retailers API... 5 Server and RPC information... 5 Data elements... 6 Country codes... 7 Example Requests... 9 Example: Minimum XML RPC message - single order with one item... 9 Responses Response codes Example success response Example error response Handling errors... 13

4 Introducing the Get Close Retailers API Introducing the Get Close Retailers API If you use our Ship to Store fulfillment processes for your in-store pickup program, you can obtain information about fulfillment partners who are nearest to an order using the Get Close Retailers API. This API is usually used on a product detail page, allowing the consumer to view and select from a list of close stocking retailers. You can send information about a specific order request to the Shopatron system. The following order information is sent: Manufacturer ID Catalog ID Currency ID Consumer s Postal Country Shipment Type (optional: use sts or ispu ) Part Numbers Distance (optional: used for the radius calculation: default value is 50, maximum is 150) In return, you receive information about the closest retailers, who may be able to fill the order, including the: Name Location Address Phone Distance Maximum Lead Time (in days). Max Lead Time is a result of the products passed in, and is the same for every retailer record. When a shopper requests Ship to Store at checkout, the Get Close Retailers API can retrieve information about retail fulfillment locations near the customer. Getting Started NOTE: Shopatron usually recommends our APIs only 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 Get Close Retailers API functions described in this guide, you will need to contact Shopatron Merchant Support at (877) or send to mss@shopatron.com to obtain the information to configure your account. GET CLOSE RETAILERS API GUIDE, VERSION /29/13 PAGE 4

5 Programming the Get Close Retailers API System requirements To use this API, you need a server with Internet access that runs your own shopping cart software to gather the order data Writing the application You will need to write the Get Close Retailers application. This application assembles an XML package with information about an order from the customer's shopping cart or from a product detail page. It then uses a Remote Procedure Call (RPC) to pass the package to the information to the Shopatron system. This creates a request for the Shopatron server to respond to. You can write the application in any programming or scripting language that can handle an RPC, including PHP, ASP, Cold Fusion, JSP, JAVA, C, and so on. 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. Process flow The process for the Shopatron Get Close Retailer API XML-RPC is summarized here: 1. When the customer requests ship to store or in-store pickup from their shopping cart or a product detail page, you make a request to the Shopatron XML RPC server. 2. The request includes the currency ID, the customer's Zip, and part numbers of the items in the cart. 3. The RPC authenticates your username and password and verifies your server and RPC name information. 4. The server immediately responds with an XML package that contains information about available retailers close to the customer's Zip. The package provides the retailer's name, location, address, phone, and distance from the customer's Zip, and specified Maximum Lead Time. Programming the Get Close Retailers API Server and RPC information 1. Create an XML-RPC message that calls immediate.get_close_retailer and passes an array of the parameters listed in the table below that defines the data elements. 2. Create an XML-RPC client that connects to the following server: Server file name: /xmladvserver.php Server address: xml.shopatron.com Server port: 443 GET CLOSE RETAILERS API GUIDE, VERSION /29/13 PAGE 5

6 Programming the Get Close Retailers API Data elements Refer to this table for details for defining data elements: Element Required Parent Data Type (Length) Occurs Description UserName Yes None String 1 Shopatron username. (Must be a valid and active user account with System Admin or Order Admin permission.) Password Yes None String 1 Password for Shopatron user account. ManufacturerID Yes None Int 1 The Shopatron-assigned Manufacturer ID you want order data for; you can find this in your Shopatron account. CatalogID Yes None Int 1 The Shopatron-assigned Catalog ID you want order data for; you can find this in your Shopatron account. CurrencyID Yes None Int 1 The Currency Type for the order. These Currency Types are supported: 1 - US Dollar 2 - Canadian Dollar 3 - British Pound 4 - German Euro 5 - French Euro 7 - Italian Euro 8 - Spanish Euro 9 - British Euro 10 - Dutch Euro Zip/Postal Yes None String 1 Zip or postal code for the shipping address. Country Yes None String (2) 1 2-character Country of the ship-to address for the order. Country s are listed at the end of this document. GET CLOSE RETAILERS API GUIDE, VERSION /29/13 PAGE 6

7 Programming the Get Close Retailers API Element Required Parent Data Type (Length) Occurs Description ShipType Optional filters String 1 The shipping type for the order. Acceptable values are sts (for ship to store) or ispu (for in-store pickup). PartnumberBlock Yes None Struct 1 The part number portion of the package. Acts only as a container for a list of part numbers; indexed from 0. Distance Optional None Int 1 Distance used in the radius calculation. The default value is 50. The maximum value is 150. Any Integer sent outside the range will be set to the default value. Country codes Country 2-Character Country Country 2-Character Country 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 GET CLOSE RETAILERS API GUIDE, VERSION /29/13 PAGE 7

8 Programming the Get Close Retailers API Country 2-Character Country Country 2-Character Country 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 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 GET CLOSE RETAILERS API GUIDE, VERSION /29/13 PAGE 8

9 Example Requests Country 2-Character Country Country 2-Character Country Guam GU United Kingdom GB Hong Kong HK United States of America US Iceland IS Vatican City VA India IN Example Requests Example: Minimum XML RPC message - single order with one item Example: Minimum XML RPC message - single order with one item <?xml version="1.0" encoding="utf-8"?> <methodcall> <methodname>immediate.get_close_retailer</methodname> <params> <string>xml_user</string> <string>password</string> <int>138</int> <int>0</int> <int>1</int> <string>93401</string> GET CLOSE RETAILERS API GUIDE, VERSION /29/13 PAGE 9

10 Responses Example: Minimum XML RPC message - single order with one item <string>us</string> <string>sts</string> <struct> <name>0</name> <string>112233</string> <name>1</name> <string>satds5588d44dd789ffdd2b1</string> </struct> </params> </methodcall> Responses On success, the RPC returns the Shopatron order id. On an error, the RPC returns a response message with the fault and faultstring. Response codes Description 2 Missing Part Numbers 3 Invalid ShipType Parameter 4 Missing Zip 5 Missing Country GET CLOSE RETAILERS API GUIDE, VERSION /29/13 PAGE 10

11 Responses Description 98 Invalid Zip 99 Invalid Authorization Example success response Example success response <?xml version="1.0" encoding="utf-8"?> <methodresponse> <params> <struct> <name>0</name> <struct> <name>retailerid</name> <int>42</int> <name>locationid</name> <int>8003</int> <name>name</name> <string>slo Store</string> <name>address1</name> <string>2074 Parker St</string> <name>address2</name> <string>#100</string> <name>address3</name> <string /> GET CLOSE RETAILERS API GUIDE, VERSION /29/13 PAGE 11

12 Responses Example success response <name>city</name> <string>san Luis Obispo</string> <name>state</name> <string>ca</string> <name>zip</name> <string>93401</string> <name>country</name> <string>us</string> <name>latitude</name> <double> </double> <name>longitude</name> <double> </double> <name>phone</name> <string> </string> <name>distance</name> <double> </double> <name>maxleadtime</name> <double>30</double> </struct> </struct> GET CLOSE RETAILERS API GUIDE, VERSION /29/13 PAGE 12

13 Responses Example success response </params> </methodresponse> Example error response Example error response <?xml version="1.0" encoding="utf-8"?> <methodresponse> <fault> <struct> <name>fault</name> <int>2</int> <name>faultstring</name> <string>invalid username or password, or insufficient permissions</string> </struct> </fault> </methodresponse> Handling errors If you receive an error response fault code after sending the order information to Shopatron, take the following steps: 1. Record the outgoing package and the associated fault code response from Shopatron. 2. Test for connectivity to the server (usually shopatron.com). 3. Hold the XML package for future transmission to Shopatron's servers. 4. Send an to Shopatron Merchant Support at include the time and date of the failed transmission. 5. When Shopatron support staff contacts you, resend the failed attempts. GET CLOSE RETAILERS API GUIDE, VERSION /29/13 PAGE 13