introducing the get close retailers api xml-rpc get close ... · get close retailers api guide,...

Introducing the Get Close Retailers API

CANNOT SHIP ORDER API GUIDE 10/29/13 | PAGE 1

XML-RPC

Get Close Retailers API Guide Version 2.0

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, 93403

Shopatron Europe

Shopatron UK, Ltd.

Newport House

19-21 Newport Street

Old Town, Swindon SN1 3DX

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 ................................................................................................................. 10

Response codes ............................................................................................................... 10

Example success response ............................................................................................. 11

Example error response ................................................................................................... 13

Handling errors ................................................................................................................. 13


GET CLOSE RETAILERS API GUIDE, VERSION 2.0 10/29/13 | PAGE 4


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 Code

Country Code

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) 715-7467 or send email to [email protected] to

obtain the information to configure your account.

mailto:[email protected]

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 Code, 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 Code. The package provides the retailer's name, location,

address, phone, and distance from the customer's Zip Code, and specified Maximum Lead Time.


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



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 Code Yes None String 1 Zip or postal code for the

shipping address.

CountryCode Yes None String (2) 1 2-character Country Code of the

ship-to address for the order.

Country Codes are listed at the

end of this document.



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

Code


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




Code


Code

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

Example Requests



Code


Code

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


<?xml version="1.0" encoding="UTF-8"?>

<methodCall>

<methodName>immediate.get_close_retailer</methodName>

<params>

<param>

<value>

<string>xml_user</string>

</value>

</param>

<param>

<value>

<string>password</string>

</value>

</param>

<param>

<value>

<int>138</int>

</value>

</param>

<param>

<value>

<int>0</int>

</value>

</param>

<param>

<value>

<int>1</int>

</value>

</param>

<param>

<value>

<string>93401</string>

</value>

</param>

Responses



<param>

<value>

<string>US</string>

</value>

</param>

<param>

<value>

<string>sts</string>

</value>

</param>

<param>

<value>

<struct>

<member>

<name>0</name>

<value>


</value>

</member>

<member>

<name>1</name>

<value>

<string>SATDS5588d44dd789ffdd2B1</string>

</value>

</member>

</struct>

</value>

</param>

</params>

</methodCall>

Responses

On success, the RPC returns the Shopatron order id. On an error, the RPC returns a response

message with the faultCode and faultString.

Response codes

Code Description

2 Missing Part Numbers

3 Invalid ShipType Parameter

4 Missing Zip Code

5 Missing Country Code

Responses


Code Description

98 Invalid Zip Code

99 Invalid Authorization

Example success response



<methodresponse>

<params>

<param>

<value>

<struct>

<member>

<name>0</name>

<value>

<struct>

<member>

<name>RetailerID</name>

<value>

<int>42</int>

</value>

</member>

<member>

<name>LocationID</name>

<value>

<int>8003</int>

</value>

</member>

<member>

<name>Name</name>

<value>

<string>SLO Store</string>

</value>

</member>

<member>

<name>Address1</name>

<value>

<string>2074 Parker St</string>

</value>

</member>

<member>


<value>

<string>#100</string>

</value>

</member>

<member>


<value>

<string />

</value>

</member>

Responses



<member>

<name>City</name>

<value>

<string>San Luis Obispo</string>

</value>

</member>

<member>

<name>State</name>

<value>

<string>CA</string>

</value>

</member>

<member>

<name>Zip</name>

<value>


</value>

</member>

<member>

<name>CountryCode</name>

<value>

<string>US</string>

</value>

</member>

<member>

<name>Latitude</name>

<value>

<double>35.2545</double>

</value>

</member>

<member>

<name>Longitude</name>

<value>

<double>-120.646</double>

</value>

</member>

<member>

<name>Phone</name>

<value>

<string>805-547-8368</string>

</value>

</member>

<member>

<name>Distance</name>

<value>

<double>0.523715</double>

</value>

</member>

<member>

<name>MaxLeadTime</name>

<value>

<double>30</double>

</value>

</member>

</struct>

</value>

</member>

</struct>

Responses



</value>

</param>

</params>

</methodresponse>

Example error response

Example error response


<methodResponse>

<fault>

<value>

<struct>

<member>

<name>faultCode</name>

<value>

<int>2</int>

</value>

</member>

<member>

<name>faultString</name>

<value>

<string>invalid username or password, or insufficient

permissions</string>

</value>

</member>

</struct>

</value>

</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 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.

introducing the get close retailers api xml-rpc get close ... · get close retailers api guide,...

Documents