ACP Shipper Integration API V1.16

ACP Shipper Integration API v1.16.

This document describes the most basic commands of ACP Shipper API, needed for sending direct mailing. There are some more commands in this API, that may be used by a shipper: for address verification, mailing tracking, creation return and collect parcels. They are described in separate documents, which is listed on in section “Manuals”.

Description

Endpoint url is OR (for test purposes). Trailing slash in the endpoint URL is STRONGLY recommended especially on slow connections. Using the endpoint URL without trailing slash increase response time by 2-3 times.

Following input parameters must be sent via HTTPs POST method:

apikey=XXXXXXXXXX (required) – your personal API access key that we give to you.

command=commandName (required) – possible commands are described below.

testMode=0|1 (optional, default is 0) – run command in test environment (even if =0, test mode may always be enabled for user by administration).

+ additional parameters specific for each command.

Note: all parameters must be properly encoded, as required by HTTP standard. I.e., if request's encoding is “x-www-form-urlencoded” (header “Content-Type: application/x-www-form-urlencoded”), then all non-alphanumeric chars in parameter names and values must be replaced by char % plus their hexadecimal values. E.g., char “&” must be replaced by “%26”. On practice, it is enough to replace only following characters instead all non-alphanumeric characters: +,%, ?, =, &, #.

original symbol / URL encoded replacement sequence
+ / %2B
% / %25
? / %3F
= / %3D
%26
# / %23

API answer is standard “HTTP 200 OK” answer. Answer body contains text in XML format, specific for each command. In case of common error, such as authorization error or invalid input parameters, answer is the same for all commands:

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

shippingApiResponse

<error>Some error description</error

</shippingApiResponse

XSD-schemes as described below XML-requests may be found here:

Possible Commands:

1) command=createMailing

Used for the creation of direct mailing item(s) and (optional) printable shipping label.

Specific parameters:

data=text/xml (required) – data describing mailing items for processing (see below).

label=0|1|2|3|4|10|11|12|14|20|30|40 (required) – type of created and returned shipping label:

– 0 – do not create label, trackingNumber must be provided in this case in request XML

– 1 – ACP Ground (formerly Zoom Ground)label, max weight is 15 Lbs

– 2 – ACP Expedited (formerly Zoom Expedited) label, max weight is 15 Lbs

– 4 – ACP Expedited Max (ACP Expedited with 25 Lbs max weight + faster delivery)

– 3 – ACP Priority (formerly Zoom Priority) label, max weight is 70 Lbs

– 10– ACP Surface (formerly Zoom FedEX) label, max weight is 150 Lbs

– 5 – ACP internationallabel, used for international parcels originating from US, max weight is 44 Lbs, max declared value is 1000 USD (for parcels goes to china – 1000 CNY).(Please, contact us before using this code)

–11–FedEx International Economylabel (Please, contact us before using this code). You will receive two shipping labels after success API call (you must print them all). PNG labels are returned in a solid zip archive. PDF/EPL as a single file which contains two labels.

–14–FedEx International Prioritylabel (Please, contact us before using this code). You will receive two shipping labels after success API call (you must print them all). PNG labels are returned in a solid zip archive. PDF/EPL as a single file which contains two labels.

– 40 – ACP EU (formerly TrakPac) label (Please, contact us before using this code)

– 12 – ACP Mini (formerly Mini) label

– 20 – Canada label – should be choosed if destination country is Canada

– 30 – China label – should be choosed if destination country is China (Please, contact us before using this code)

– 50 – HLO label – Cargo label (Please, contact us before using this code)

labelFormat=PNG|PDF|EPL2 (optional, default is PNG) – required label image format.

labelSize=4x4|4x6 (optional, default is 4x6) – requested label image size in inches. This option takes effect only onlabel=1,2,3,4. This option overrides default labelSize default setting. Contact support to change the default value if required.

expressClearance=0|1 (optional, default is 0) – make express customs clearance:

– 0 – usual clearance

– 1 – express clearance

ddp=0|1 (optional, default is 0) – Delivery Duty Paid flag for dutiable parcels:

– 0 – duty must be paid by consignee

– 1 – duty must be paid by shipper

Structure of XML in data parameter:

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

shippingApiRequest

<mailItem

<trackingNumber>1ZWE31190196785492</trackingNumber

<shipperItemId>1234-4567890</shipperItemId

<displayItemId>20121120-093021</displayItemId

<consignee

<nameJohn Doe</name

<addressLine19559 Collins Ave Apt #903</addressLine1

<cityBeverly Hills</city

<stateCA</state

<zip90210</zip

<countryUS</country

<phone>123-456-9890</phone

<email></email

</consignee

<shipper

<nameJohn Doe</name

<companyNameAmazon</companyName

<addressLine1some address</addressLine1

<citysome city</city

<state>EU</state

<zip>12345</zip

<countryGB</country

<email></email

</shipper

<returnAddress

<nameJohn Smith</name

<companyName>Shippers, LLC</companyName

<addressLine1LAX</addressLine1

<cityLos Angeles</city

<stateCA</state

<zip90045</zip

<countryUS</country

<phone>1 (800) 426-4968</phone

<email></email

</returnAddress

<value>100.50</value

<currency>EUR</currency

<weight>1.125</weight

<weightUnitOfMeasurekg</weightUnitOfMeasure

dimensions

length>0.5</length

width>0.4</width

height>0.3</height

</dimensions

<dimensionsUnitOfMeasurem</dimensionsUnitOfMeasure

<product

<countryOfOriginFR</countryOfOrigin

<harmonizationCode4901.99.0070</harmonizationCode

<descriptionBook</description

manufacturerCode</manufacturerCode

sku</sku

<quantity2</quantity

unitValue14.65</unitValue

<value29.30</value

<weight>0.5</weight

</product

…

</mailItem

…

</shippingApiRequest

Fields description:

shippingApiRequest – root node.

mailItem – describes particular mailing item. Can be repeated for the creation of multiple items at once (only if input parameter label=0). Container for HAWB data: goods for customer.

trackingNumber – tracking number of shipping label (USPS/UPS etc), required if input parameter label=0. Cannot be used with input parameter label≠0.

shipperItemId (optional, desired) – internal shipper's mailing item ID, max length 50 chars. If used, allows this mailing item to be pointed to this id later. Especially recommended if trackingNumber is not transmitted (input parameter label≠0) to avoid placing one mailing item twice due to connection problems, etc. Must be unique through all mailing items (direct and return/collect) for this shipper.

displayItemId (optional) – if used, will be printed on mailing label instead of shipperItemId (if input parameter label≠0).

consignee – consignee’s address.

name– person name, max length 35 chars.

companyName– company name, max length 35 chars.

(either name or companyName is required)

addressLine1, addressLine2 – address information. Combined length of these fields must not be greater than 105 chars.

city– city name, max length 35 chars.

state– state/province code, max length 2 chars.

zip – zip/postal-code, max length 10 chars.

country– country code in ISO 3166-1 alpha-2 format (US, GB, CA, …)

phone (optional) – phone number,max length 20 chars. Free form field: 123-456-9890, 1(800) 426-4968, 123456789, etc.

email (required for parcels with value > $800) – email address

shipper (optional) – shipper’s address for filling in AMS. Format identical to consignee node. If transmitted, valid address required. If you have more than 1 shipper address there are additional choices:

– set up a different account for each address and omit this node;

– use shipper node in createMailing command.

returnAddress (optional) – used only for printing on shipping labels as return address. Format identical to consignee node. If transmitted, valid address required.

value –total mailing item's cost, decimal number (i.e. 1234.12).

currency – currency code in ISO 4217 format (USD, EUR, GBP, CNY, RMB,…)

weight – mailing item total weight in kilograms, decimal number (i.e. 12.345).

weightUnitOfMeasure – constant kg.

dimensions (optional) – mailing item’s dimensions in meters.

length – length, decimal number.

width– width, decimal number.

height– height, decimal number.

dimensionsUnitOfMeasure – constant m

product– describes particular product in this mailing item, should be repeated for each product in it.

countryOfOrigin (optional) – origin country's code in ISO 3166-1 alpha-2 format (US, GB, CA, …).

harmonizationCode – US customs HTS code, max length 12 chars.

description– product description, max length 300 chars.

manufacturerCode(optional) – product manufacturer's code, max length 35 chars.

sku(optional) – product's SKU.

quantity–purchased quantity, integer.

unitValue (optional, desired) –unit price, decimal number.

value (optional, desired) –total cost of this product, decimal number.

(either unitValue or value is required for parcels with value > $200)

weight (optional) – total weight or this product.

priorNoticeFilingNumber – optional, reserved for future use, string 12 chars max .

Structure of XML in API answer:

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

shippingApiResponse

<mailItem

<resultok</result

<errorTypeconflict</errorType

<error>Error description</error

<trackingNumber>1ZWE31190196785492</trackingNumber

<shipperItemId>1234-4567890</shipperItemId

<labelFormat>PNG</labelFormat

<label>c2FkYXNkZmRhc2...... ZhZ2RmaA==</label

<destinationBag>LAX</destinationBag

<isDutiable>yes</isDutiable

<conflictMailItem

<type>Direct</type

<creationDate>2012-08-31T20:00:00Z</creationDate

<statusPicked Up</status

<trackingNumber>1ZWE31190196785492</trackingNumber

<shipperItemId>1234-4567890</shipperItemId

<displayItemId>20121120-093021</displayItemId

<value>100.50</value

<currency>EUR</currency

<weight>1.125</weight

<weightUnitOfMeasurekg</weightUnitOfMeasure

<bagId>1000001234567890</bagId

<shipperBagId>bag-1234</shipperBagId

</conflictMailItem

</mailItem

…

</shippingApiResponse

Fields description:

shippingApiResponse – root node.

mailItem – describes result of creation of particular mailing item. Repeated for every mailing item in request.

result – operation result, string ok or error.

errorType – error type in case of error. Possible values are:

– invalid – transmitted mailing item is invalid;

– conflict – conflict with already existing mailing item (e.g., by shipperItemId);

– system – internal system error.

error – text error description in case of error.

trackingNumber – shipping tracking number of label for this mailing item. If creation of shipping label was ordered (input parameter label≠0), it is the tracking number of created label (may be empty in case of error). If not (label=0), it is the tracking number transmitted in request.

shipperItemId – internal shipper's mailing item id, transmitted in request.

labelFormat – format of created label, one of PNG, PDF, EPL2.

label – base64-encoded content of created label.

destinationBag – recommended bag type for shipping this mailing item (i.e. LAX, JFK, ...). Used for sorting mailing items by destination airport on sender's side.

isDutiable (optional) – “yes” for dutiable parcels.

conflictMailItem – in case of conflict with existing mailing item (errorType=conflict), contains description of that mailing item (in case of conflict with someone's else mailing item by tracking number, contains trackingNumber child node only).

type – one of: “Direct”, “Return”, “Collect”, “Undeliverable”.

creationDate – creation date/time in UTC, format is “yyyy-mm-ddThh:mm:ssZ”.

status – item's current status (“New”, “Picked Up”, etc).

trackingNumber – tracking number.

shipperItemId – internal shipper's mailing item id.

displayItemId – shipper's display item id.

value –total mailing item's cost.

currency – currency code.

weight – mailing item total weight in kilograms.

weightUnitOfMeasure – constant kg.

bagId – system bag id, in which this item is included.

shipperBagId – internal shipper's bag id.

2) command=cancelMailing

Used to cancel some of previously created direct or return/collect mailing item(s).

Specific parameters:

data=text/xml (required) – data describing canceled mailing items (see below).

Structure of XML in data parameter:

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

shippingApiRequest

<mailItem

<trackingNumber>1ZWE31190196785492</trackingNumber

<shipperItemId>1234-4567890</shipperItemId

</mailItem

…

</shippingApiRequest

Fields description:

shippingApiRequest – root node.

mailItem – describes particular mailing item for canceling, can be repeated for canceling several items at once.

trackingNumber – tracking number of mailing item.

shipperItemId – internal shipper's mailing item id.

(either trackingNumber or shipperItemId is required)

Structure of XML in API answer:

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

shippingApiResponse

<mailItem

<resultok</result

<errorTypeconflict</errorType

<error>Error description</error

<trackingNumber>1ZWE31190196785492</trackingNumber

<shipperItemId>1234-4567890</shipperItemId

<conflictMailItem

<type>Direct</type

<creationDate>2012-08-31T20:00:00Z</creationDate

<statusPicked Up</status

<trackingNumber>1ZWE31190196785492</trackingNumber

<shipperItemId>1234-4567890</shipperItemId

<displayItemId>20121120-093021</displayItemId

<value>100.50</value

<currency>EUR</currency

<weight>1.125</weight

<weightUnitOfMeasurekg</weightUnitOfMeasure

<bagId>1000001234567890</bagId

<shipperBagId>bag-1234</shipperBagId

</conflictMailItem

</mailItem

…

</shippingApiResponse

Fields description:

shippingApiResponse – root node.

mailItem – describes result of canceling of particular mailing item. Repeated for every mailing item in request.

result – operation result, string ok or error.

errorType – error type in case of error. Possible values are:

– invalid – transmitted mailing item is invalid;

– notFound – requested mailing item not found;

– conflict – conflict with current mailing item's state;

– system – internal system error.

error – text error description in case of error.

trackingNumber – tracking number of mailing item.

shipperItemId – internal shipper's mailing item id.

conflictMailItem – in case of conflict with current mailing item's state (errorType=conflict), contains description of current mailing item.

type – one of: “Direct”, “Return”, “Collect”, “Undeliverable”.

creationDate – creation date/time in UTC, format is “yyyy-mm-ddThh:mm:ssZ”.

status – item's current status (“New”, “Picked Up”, etc).

trackingNumber – tracking number.

shipperItemId – internal shipper's mailing item id.

displayItemId – shipper's display item id.

value –total mailing item's cost.

currency – currency code.

weight – mailing item total weight in kilograms.

weightUnitOfMeasure – constant kg.

bagId – system bag id, in which this item is included.

shipperBagId – internal shipper's bag id.

3) command=createBag

Used for aggregation of direct mailing items in shipping bag (e.g., bag 1 of 10) and printing bag label. Each bag consists of 1 or more mailing items.

Specific parameters:

data=text/xml (required) – data describing created bag (see below).

label=0|1 (optional, default is 0) – return bag label (1) or not (0).

labelFormat=PNG|PDF|EPL2 (optional, default is PNG) – required label image format.

airport= (optional, default is JFK) – you need special permission from ACP to use this feature

Structure of XML in data parameter:

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

shippingApiRequest

<bag

<shipperBagId>bag-1234</shipperBagId

<comment>Bag 1 of 10</comment

<mailItem

<trackingNumber>1ZWE31190196785492</trackingNumber

<shipperItemId>1234-4567890</shipperItemId

</mailItem

…

</bag

</shippingApiRequest

Fields description:

shippingApiRequest – root node.

bag – describes created bag.

shipperBagId (optional, desired) – internal shipper's bag id, max length 50 chars. If used, allows this bag to be pointed to this id later.

comment (optional) – comments for printing on bag label, max length 50 chars.

mailItem – describes particular mailing item for inclusion in the bag. Should be repeated for each included mailing item.

trackingNumber – tracking number of mailing item.

shipperItemId – internal shipper's mailing item id.

(either trackingNumber or shipperItemId is required)

Structure of XML in API answer:

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

shippingApiResponse

<bag

<resultok</result

<errorTypeconflict</errorType

<error>Error description</error

<bagId>1000001234567890</bagId

<shipperBagId>bag-1234</shipperBagId

<labelFormat>PNG</labelFormat

<label>c2FkYXNkZmRhc2...... ZhZ2RmaA==</label

<conflictBag

<creationDate>2012-08-31T20:00:00Z</creationDate

<statusNew</status

<bagId>1000001234567890</bagId

<shipperBagId>bag-1234</shipperBagId

<comment>Bag 1 of 10</comment

</conflictBag

<mailItem

<errorTypeconflict</errorType

<error>Error description</error

<trackingNumber>1ZWE31190196785492</trackingNumber

<shipperItemId>1234-4567890</shipperItemId

<conflictMailItem

<type>Direct</type

<creationDate>2012-08-31T20:00:00Z</creationDate

<statusPicked Up</status

<trackingNumber>1ZWE31190196785492</trackingNumber

<shipperItemId>1234-4567890</shipperItemId

<displayItemId>20121120-093021</displayItemId

<value>100.50</value

<currency>EUR</currency

<weight>1.125</weight

<weightUnitOfMeasurekg</weightUnitOfMeasure

<bagId>1000001234567890</bagId

<shipperBagId>bag-1234</shipperBagId

</conflictMailItem

</mailItem

…

</bag

</shippingApiResponse

Fields description:

shippingApiResponse – root node.

bag – describes result of creating bag operation.

result – operation result, string ok or error.

errorType – error type in case of error. Possible values are:

– invalid – transmitted bag is invalid;

– conflict – conflict with already existing bag or current mailing items' state;

– system – internal system error.

error – text error description in case of error.

bagId – system id of this bag, for future usage in other commands, like cancelBag (may be empty in case of error).

shipperBagId – internal shipper's bag id.

labelFormat – format of created label, one of PNG, PDF, EPL2.

label – base64-encoded content of created label.

conflictBag – in case of conflict with existing bag (errorType=conflict) by shipperBagId, contains description of that bag.

creationDate – creation date/time in UTC, format is “yyyy-mm-ddThh:mm:ssZ”.

status – bag's current status (“New”, “Picked Up”, etc).

bagId – system bag id.

shipperBagId – internal shipper's bag id.

comment – shipper's bag comment.

mailItem – in case of conflict (errorType=conflict), describes particular mailing item requested for inclusion in the bag that can NOT be included in it for a particular reason. Repeated for each such mailing item.

errorType – error type. Possible values are:

– invalid – transmitted mailing item is invalid;

– notFound – requested mailing item not found;

– conflict – conflict with current mailing item's state;

– system – internal system error.

error – text error description.

trackingNumber – tracking number of mailing item.

shipperItemId – internal shipper's mailing item id.

conflictMailItem – in case of conflict with current mailing item's state (both bag's errorType=conflict and mailItem's errorType=conflict), contains description of current mailing item.

type – one of: “Direct”, “Return”, “Collect”, “Undeliverable”.

creationDate – creation date/time in UTC, format is “yyyy-mm-ddThh:mm:ssZ”.

status – item's current status (“New”, “Picked Up”, etc).

trackingNumber – tracking number.

shipperItemId – internal shipper's mailing item id.

displayItemId – shipper's display item id.

value –total mailing item's cost.

currency – currency code.

weight – mailing item total weight in kilograms.

weightUnitOfMeasure – constant kg.

bagId – system bag id, in which this item is included.

shipperBagId – internal shipper's bag id.

4) command=cancelBag

Used to cancel previously created bag for a particular reason.

Specific parameters:

data=text/xml (required) – data describing canceled bag (see below).

Structure of XML in data parameter:

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

shippingApiRequest

<bag

<bagId>1000001234567890</bagId

<shipperBagId>bag-1234</shipperBagId

</bag

</shippingApiRequest

Fields description:

shippingApiRequest – root node.

bag – describes canceled bag.

bagId – system id of the bag.

shipperBagId – internal shipper's bag id.

(either bagId or shipperBagId is required)

Structure of XML in API answer:

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

shippingApiResponse

bag

<resultok</result

<errorTypeconflict</errorType

<error>Error description</error

<bagId>1000001234567890</bagId

<shipperBagId>bag-1234</shipperBagId

<conflictBag

<creationDate>2012-08-31T20:00:00Z</creationDate