Команда опциоанльно



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:

Some error description

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.

Important notice:

Non-English characters are forbidden for US parcels in all text fields. US customs doesn't accept them. We replace some symbols according to the following table . All other symbols will cause a rejection with the following error message: 

" contains non-English utf8 character(s)".

For example: "consignee name contains non-english utf8 character(s)".

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 24.9 Lbs, max length is 27in, max width is 17in, max height is 17in, max sum of length(inch) and girth(inch) is 50 (girth is the distance all the way around the package at the widest point (2W +2H))

– 2 – ACP Expedited (formerly Zoom Expedited) label (ACP Ground weight/size restrictions + faster delivery. Please note, that oversized ACP Expedited parcels will be automatically converted to ACP Priority)

– 4 – ACP Expedited Max (ACP Expedited weight/size restrictions + faster delivery)

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

– 10– ACP FedEx Home Delivery (formerly ACP Surface) label, max weight is 150 Lbs

– 70– ACP UPS Second day label

– 5 – ACP international  label, 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 Economy label (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 Priority label (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 (Please, contact us before using this code)

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

– 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)

– 60 – eTrak label – eTrak Parcel international label(Please, contact us before using this code)

– 61 – eTrak label – eTrak Postal international label (Please, contact us before using this code)

– 62 – eTrak label – eTrak Postal Signed international label (Please, contact us before using this code)

– 63 – eTrak label – eTrak Premium international label (Please, contact us before using this code)

– 64 – eTrak label – eTrak Untracked international label (Please, contact us before using this code)

labelFormat=PNG|PDF|EPL2|PDF4x6 (optional, default is PNG) – required label image format. PDF4x6 is special PDF label with page size 4x6 inches without margins. PDF4x6 format is useful to print on barcode thermal printers from PDF viewers. PDF4x6 is incompatible with label=11,14,20,30.

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

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:

1ZWE31190196785492

1234-4567890

20121120-093021

John Doe

9559 Collins Ave Apt #903

Beverly Hills

CA

90210

US

123-456-9890

john-doe@

John Doe

Amazon

some address

some city

EU

12345

GB

john@



John Smith

Shippers, LLC

LAX

Los Angeles

CA

90045

US

1 (800) 426-4968

john-smith@

100.50

EUR

1.125

kg

0.5

0.4

0.3

m

FR

4901.99.0070

Book

2

14.65

29.30

0.5



4-401.11(С)

…

…

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 – conditional, 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 – required, consignee’s address.

name – conditional, person name, max length 35 chars. "amazon" is forbidden.

companyName – conditional, 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. addressLine1 is required field, addressLine2 is optional.

city – required, city name, max length 35 chars.

state –conditional, state/province code, max length 2 chars. Required for countries with states/province/sub-country division. For parcels heading to US state is required field.

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

country – required, 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 (required) – shipper’s address for filling in AMS.

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.

name – conditional, attention name, max length 35 chars.

companyName – conditional, shipping 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. addressLine1 is required field, addressLine2 is optional.

city – required, city name, max length 35 chars.

state –conditional, state/province code, max length 2 chars. Required for countries with states/province/sub-country division.

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

country – required, 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

shipperURL – optional (desired), shipper’s web site address, is required for parcels heading to DFW.

DFW Airport US customs authorities require this field for clearance.

Leading http:// or https:// is required.

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

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

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

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

weightUnitOfMeasure – required, constant kg.

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

length – required, length, decimal number.

width – required, width, decimal number.

height – required, height, decimal number.

dimensionsUnitOfMeasure – conditional, constant m, required if dimensions is given.

product – required, 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 (optional, desired)– US customs HTS code, max length 12 chars.

description (required)– product description, max length 300 chars.

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

sku (optional) – product's SKU.

quantity – (required)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 > $800)

weight (optional) – total weight or this product.

productURL (optional) – link to product’s page. Leading http:// or https:// is required. For example



FDACode (optional) – product’s FDA Code (Food and Drug Administration) See for more details.

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

dg_code – optional, dangerous goods indicator. If supplied, should have one of following values:

01 - Lithium metal Batteries Contained in Equipment

02 - Lithium metal Batteries Packed with Equipment

03 - Lithium metal Batteries Stand-alone

04 - Lithium-ion Batteries Contained in Equipment

05 - Lithium-ion Batteries Packed with Equipment

06 - Lithium-ion Batteries Stand-alone

08 - ORM-D ()

09 - Small Quantity Provision

Please note: Label=1 (ground) is the only possible value for shipping dangerous goods code 08.

ACP system automatically converts ACP Expedited and ACP Expedited Max labels to ACP Ground for dangerous goods code 08.

Structure of XML in API answer:

ok

conflict

Error description

1ZWE31190196785492

1234-4567890

PNG

c2FkYXNkZmRhc2......ZhZ2RmaA==

LAX-USPS

LAX

yes

Direct

2012-08-31T20:00:00Z

Picked Up

1ZWE31190196785492

1234-4567890

20121120-093021

100.50

EUR

1.125

kg

1000001234567890

bag-1234

…

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-USPS, JFK-DHL, ...). Used for sorting mailing items by destination airport on sender's side.

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

recommendedAirport – recommended airport for sending parcel (i.e. LAX, JFK, ORD, DFW ...). Used for sorting mailing items on sender's side.

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:

1ZWE31190196785492

1234-4567890

…

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:

ok

conflict

Error description

1ZWE31190196785492

1234-4567890

Direct

2012-08-31T20:00:00Z

Picked Up

1ZWE31190196785492

1234-4567890

20121120-093021

100.50

EUR

1.125

kg

1000001234567890

bag-1234

…

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, free form text up to 6 chars long, it will be printed on the bag label – you need special permission from ACP to use this feature

Structure of XML in data parameter:

bag-1234

Bag 1 of 10

1ZWE31190196785492

1234-4567890

…

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:

ok

conflict

Error description

1000001234567890

bag-1234

PNG

c2FkYXNkZmRhc2......ZhZ2RmaA==

2012-08-31T20:00:00Z

New

1000001234567890

bag-1234

Bag 1 of 10

conflict

Error description

1ZWE31190196785492

1234-4567890

Direct

2012-08-31T20:00:00Z

Picked Up

1ZWE31190196785492

1234-4567890

20121120-093021

100.50

EUR

1.125

kg

1000001234567890

bag-1234

…

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:

1000001234567890

bag-1234

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:

ok

conflict

Error description

1000001234567890

bag-1234

2012-08-31T20:00:00Z

New

1000001234567890

bag-1234

Bag 1 of 10

Fields description:

shippingApiResponse – root node.

bag – describes result of canceling bag operation.

result – operation result, string ok or error.

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

– invalid – transmitted bag is invalid;

– notFound – requested bag not found;

– conflict – conflict with current bag's state;

– system – internal system error.

error – text error description in case of error.

bagId – system id of this bag, the same as in request.

shipperBagId – internal shipper's bag id.

conflictBag – in case of conflict with current bag's state (errorType=conflict), contains description of the 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.

5) command=createManifest

Used to create MAWB manifest.

Specific parameters:

data=text/xml (required) – data describing required manifest.

Please note that total size of data parameter must be less than 49.999 Mb

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

– 0 – usual clearance, 321 Regular

– 1 – express clearance, Express (ECCF)

– 2 – enhanced clearance (321 ACE) that is faster than usual, cheaper than express, is applicable to low value parcels only. Additional restriction is applied - all parcels must have filled valid HS codes for every product.

Structure of XML in data parameter:

123-1234567

34

56

34

56.0

kg

123-1234567.PDF

AGGKGKGDDGGDK…YYYY

123-1234567.xls

JFJFYYUOYOOPJFFH…YRYJG

somebody@

LAX

2012-12-10T10:00:00

JFK

2012-12-10T12:40:00-07:00

AA

123

1ZWE31190196785492

1ZWE31468778779797

…

…

Fields description:

shippingApiRequest – root node.

manifest – describes a manifest.

manifestNumber – MAWB# (for example 112-44995451)

senderWarehouseId (optional) – ID of warehouse-sender.

receiverWarehouseId (optional) – ID of warehouse-receiver.

If not sent then account’s default warehouse is used.

Contact us to get warehouses values. List of current warehouse IDs is available at (available for registered users only)

shippingUnits – integer, loose parcels considers to be a separate unite. E.g. you ship 5 bags (each one contents many parcels) and 3 loose parcels. Then you should to send "8" in this field. userDefinedWeight – decimal (3 decimal places after comma), actual weight of all shipping (MAWB etc)

userDefinedWeightUOM – one of kg, lb – weight unit of measure

manifestImage – MAWB “image” file (file size limit is 12 Mb). Accepted formats are PDF, PNG, JPG, BMP, TIFF, DOC, XLS

name 128 chars max, field contains file name

data field contains base64 encode file contents

manifestFile – file with the all HAWBs (file size limit is 20 Mb). We recommend to use the same file that you gave to the air company. Accepted formats XLS, CSV, DOC, Zipped (XLS, CSV, DOC)

name 128 chars max, field contains file name

data field contains base64 encoded file contents

 

alertEmail – email, We will send a confirmation email with copy of uploaded data

manifestPart – contains manifest part data. Repeated for every manifest part.

departureFacility – string, departure airport

departureDate – departure date/time, format is “yyyy-mm-ddThh:mm:ss[(+|-)hh:mm]”. If timezone is not set (2017-10-19T10:11:12) it defaults to GMT

arrivalFacility – arrival airport

arrivalDate – arrival date/time, format is “yyyy-mm-ddThh:mm:ss[(+|-)hh:mm]”. If timezone is not set (2017-10-19T10:11:12) it defaults to GMT

carrier – carrier's code

tripNumber – flight number

unit – describes required unit.

unitId – unit ID (tracking number for parcel, system ID for bag).

Structure of XML in API answer:

ok

conflict

Error description

1534646

123456789

2012-08-31T20:00:00Z

123456

1534646

123456789

123-1234567

34

56

40

10

1

10.125

kg

notFound

Error description

1ZWE31190196785492

mailItem

Direct

2012-08-31T20:00:00Z

10

Picked Up

0

123456

123457

1ZWE31190196785492

123456

20121120-093021

1.125

kg

101234567890

LAX-DHL

DHL

Normal

Direct

2012-08-31T20:00:00Z

10

Picked Up

0

123456

123457

101234567890

123456

20

20.25

kg

LAX-DHL/JFK-USPS

DHL/USPS

…

Fields description:

shippingApiResponse – root node.

manifest – describes a result of creating manifest.

result – operation result, string ok or error.

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

– invalid – transmitted data is invalid;

– conflict – conflict with already existing manifest by userManifesId or some of mailing items can not be included in the manifest.

– system – internal system error.

error – text error description in case of error.

manifestId – system ID of created manifest (in no errors).

userManifestId – transmitted userManifestId.

conflictManifest – describes already existing manifest with that created manifest conflicted (in case of errorType=conflict)

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

warehouseId – ID of warehouse created this manifest.

manifestId – system ID of manifest.

userManifestId – user ID of manifest.

manifestNumber – external manifest number.

senderWarehouseId – ID of warehouse-sender.

receiverWarehouseId - ID of warehouse-receiver.

numItems – total number of mailing items.

numBags – total number of bags.

numParts – number of parts in manifest.

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

weightUnitOfMeasure – constant kg.

unit – repeated for every unit that CAN NOT be included in the manifest (in case of global errorType=conflict)

errorType – units error type. Possible values are:

– invalid – transmitted data is invalid;

– notFound – unit not found;

– conflict – conflict with current unit's state.

– system – internal system error.

error – text error description.

unitId – transmitted unitId.

unitType – one of: mailItem, bag.

conflictMailItem OR conflictBag (in case of unit's errorType=conflict; there may appear only on of them, depending on unitType) – describes corresponding mailing unit; format is the same as in other commands' answers (acceptUnit, etc).

6) command=modifyManifest

Used to modify previously created MAWB manifest.

Specific parameters:

data=text/xml (required) – data describing required manifest.

Please note that total size of data parameter must be less than 49.999 Mb

Structure of XML in data parameter:

123456789

123-1234567

34

56.0

kg

123-1234567.PDF

AGGKGKGDDGGDK…YYYY

123-1234567.xls

JFJFYYUOYOOPJFFH…YRYJG

somebody@

LAX

2012-12-10T10:00:00

JFK

2012-12-10T12:40:00-07:00

AA

123

1ZWE31190196785492

…

…

Fields description:

shippingApiRequest – root node.

manifest – describes a manifest.

manifestId – system manifest ID.

All other fields are the same as in createManifest command.

Structure of XML in API answer:

ok

conflict

Error description

1534646

123456789

2012-08-31T20:00:00Z

123456

1534646

123456789

123-1234567

34

56

40

10

1

10.125

kg

notFound

Error description

1ZWE31190196785492

mailItem

Direct

2012-08-31T20:00:00Z

10

Picked Up

0

123456

123457

1ZWE31190196785492

123456

20121120-093021

1.125

kg

101234567890

LAX-DHL

DHL

Normal

Direct

2012-08-31T20:00:00Z

10

Picked Up

0

123456

123457

101234567890

123456

20

20.25

kg

LAX-DHL/JFK-USPS

DHL/USPS

…

Fields description:

All fields are the same as in createManifest command's response. Field errorType has one more possible value:

– notFound – required manifest not found;

7) command=cancelManifest

Used to cancel created before manifest (in case of some error in it, etc).

Specific parameters:

data=text/xml (required) – data describing required manifest.

Structure of XML in data parameter:

123456

12345689

Fields description:

shippingApiRequest – root node.

manifest – describes a manifest.

manifestId – system manifest ID.

userManifestId – internal warehouse's manifest ID.

(either manifestId or userManifestId is required)

Structure of XML in API answer:

ok

conflict

Error description

1534646

1534646

2012-08-31T20:00:00Z

123456

1534646

1534646

123-1234567

34

56

40

10

1

10.125

kg

Fields description:

shippingApiResponse – root node.

manifest – describes a result of canceling manifest.

result – operation result, string ok or error.

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

– invalid – transmitted data is invalid;

– notFound – required manifest not found;

– conflict – conflict with current manifest's state;

– sent – manifest is already sent to manifest recipient(s) (see sendMatifest command, etc.)

– system – internal system error.

error – text error description in case of error.

manifestId – system ID of manifest.

userManifestId – user ID of manifest.

conflictManifest – describes existing manifest (in case of errorType=conflict), format is the same as in createManifest command's answer.

8) command=getManifest

Used to get full data of previously created manifest.

Specific parameters:

data=text/xml (required) – data describing required manifest.

Structure of XML in data parameter:

123456

12345689

Fields description:

shippingApiRequest – root node.

manifest – describes a manifest.

manifestId – system manifest ID.

userManifestId – internal warehouse's manifest ID.

(either manifestId or userManifestId is required)

Structure of XML in API answer:

ok

invalid

Error description

1534646

1534646

2012-08-31T20:00:00Z

123456

0

New

123-1234567

34

John Smith

Shippers, LLC

LAX

Los Angeles

CA

90045

US

1 (800) 426-4968

john-smith@

56

John Smith

Shippers, LLC

LAX

Los Angeles

CA

90045

US

1 (800) 426-4968

john-smith@

40

10

1

10.125

kg

LAX

A

2012-12-10T10:00:00

JFK

B

2012-12-10T12:40:00-07:00

AA

123

20

5

50.125

kg

112233

Amazon

John Doe

Amazon

some address

some city

EU

12345

GB

john@

Direct

waste

Custom instruction

2012-08-31T20:00:00Z

10

Picked Up

0

123456

123457

1ZWE31190196785492

123456

20121120-093021

John Doe

9559 Collins Ave Apt #903

Beverly Hills

CA

90210

US

123-456-9890

john-doe@

John Doe

Amazon

some address

some city

EU

12345

GB

john@

John Smith

Shippers, LLC

LAX

Los Angeles

CA

90045

US

1 (800) 426-4968

john-smith@

100.50

EUR

1.125

kg

0.5

0.4

0.3

m

FR

4901.99.0070

Book

2

14.65

29.30

0.5

…

101234567890

LAX-DHL

DHL

Normal

10.50

1.50

0.00

12.00

…

Direct

2012-08-31T20:00:00Z

10

Picked Up

0

123456

123457

101234567890

123456

20

20.25

kg

LAX-DHL/JFK-USPS

DHL/USPS

…

…

…

Fields description:

shippingApiResponse – root node.

manifest – describes a manifest.

result – operation result, string ok or error.

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

– invalid – transmitted data is invalid;

– notFound – required manifest not found;

– system – internal system error.

error – text error description in case of error.

manifest – manifest description, includes all fields that present in return of getManifestList command, plus:

senderAddress – address of warehouse-sender.

receiverAddress – address of warehouse-receiver.

manifestPart – repeats for every manifest part, includes all info given in createManifest command, plus:

numItems – number of mailing items in this part.

numBags – number of bags in this part.

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

weightUnitOfMeasure – constant kg.

mailItem – repeats for every mailing item in this part, contains full info about mailing item. See detailed description in getUnitInfo command.

bag – repeats for every bag in this part, contains short info about it.

9) command=activityLog

Command is used to get MAWB customs status and related information.

Specific parameters:

data=text/xml (required) – data describing required manifest.

Structure of XML in data parameter:

1545748333

1545848333

160-78717855

Fields description:

shippingApiRequest – root node.

date_from – starting date of date range filter.

date_to – ending date of date range filter. Date range can not be greater than 7 days.

mawb – get information on specific MAWB. Takes higher precedence than date range filter. If this parameter is given then date range is omitted.

If neither mawb filter nor date range filter is given then system returns activity records for last 7 days MAWBs.

Structure of XML in API answer:

ok

invalid

Error description

1234567

JFK

999-12345678

CX

0123

1234 kg

12

285

10/03/2018 19:30

10/02/2018 22:32

10/03/2018 10:47

1539029580

Customs on hold 7 parcels:

7489098323516803007, 4890983235168605539, 7489098323516964149, 4890983235168014102, 7489098323516938429, 4890983235169516841, 7489098323516867508

7

0

1539001200



512

4 days 14 hr

5 days 7 hr

….

….

Fields description:

shippingApiResponse – root node.

result – operation result, string ok or error.

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

– invalid – transmitted data is invalid;

– notFound – required manifest not found;

– system – internal system error.

error – text error description in case of error.

activityLog – details on specific MAWB, this node is repeated as many times as many MAWBs found depending on filters you have passed to API call.

- mID – integer, MAWB system id which is returned upon MAWB creation

- arrival_facility – 3 chars IATA airport code of destination (JFK etc)

- manifest_number – MAWB number as you have entered it into the ACP system

- carrier – 2 chars IATA airline code (CX etc)

- trip_number – flight number as you have entered it into the ACP system

- weight – weight of MAWB in KG with kg marker

- shipping_units – integer number, count of shipping units (pallets, bags, sacks etc)

- parcels_count - integer number, count of HAWBs in MAWB

- arrival_time - UNIX timestamp of MAWB time of arrival

- time- UNIX timestamp of MAWB creation time

- sending_time - UNIX timestamp of AMS file time

- multiples_informal – reserved for future use

- customs_release_date - UNIX timestamp of US customs release time

- airport_release_date- UNIX timestamp of airport release time (reserved for future use)

- comment – Human readable comments on customs status of MAWB, for example:

Customs on hold 7 parcels:

7489098323516803007, 4890983235168605539, 7489098323516964149, 4890983235168014102, 7489098323516938429, 4890983235169516841, 7489098323516867508

- hold_count - integer number, count of HAWBs which is under customs exam procedure

- eccf_flag – 0/1/2. MAWB type: 0- 321 Regular, 1 – Express (ECCF), 2 – 321 ACE.

- pod_time - UNIX timestamp of Proof of delivery (PoD) time if given by trucking company

- pod_image_fn - link to download PoD image ,

- m_pieces – integer value, it shows how many parcel parts is in this MAWB. If each HAWB is a single piece shipment then this field has same value as parcels_count. In all other cases it is bigger than parcels_count

- ams_to_customs - Human readable period between AMS filing date and US customs release date

- prealert_to_customs- Human readable period between MAWB creating date and US customs release date

10) command=createMarineManifest

Used to create MBL manifest.

Specific parameters:

data=text/xml (required) – data describing required manifest.

Please note that total size of data parameter must be less than 49.999 Mb

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

– 0 – usual clearance, 321 Regular

– 1 – express clearance, Express (ECCF)

– 2 – enhanced clearance (321 ACE) that is faster than usual, cheaper than express, is applicable to low value parcels only. Additional restriction is applied - all parcels must have filled valid HS codes for every product.

Structure of XML in data parameter:

123-1234567

34

56

34

56.0

kg

123-1234567.PDF

AGGKGKGDDGGDK…YYYY

123-1234567.xls

JFJFYYUOYOOPJFFH…YRYJG

somebody@

LAX

2012-12-10T10:00:00

JFK

2012-12-10T12:40:00-07:00

AA

123

Glory of Seas

AAA/1234567

PA

0

1ZWE31190196785492

1ZWE31468778779797

…

…

ABCD

Fields description:

shippingApiRequest – root node.

manifest – describes a manifest.

manifestNumber – MBL# 15 chars similar to MAWB.

senderWarehouseId (optional) – ID of warehouse-sender.

receiverWarehouseId (optional) – ID of warehouse-receiver.

If not sent then account’s default warehouse is used.

Contact us to get warehouses values. List of current warehouse IDs is available at (available for registered users only)

shippingUnits – integer, loose parcels considers to be a separate unite. E.g. you ship 5 bags (each one contents many parcels) and 3 loose parcels. Then you should to send "8" in this field. userDefinedWeight – decimal (3 decimal places after comma), actual weight of all shipping (MAWB etc)

userDefinedWeightUOM – one of kg, lb – weight unit of measure

manifestImage – MAWB “image” file (file size limit is 12 Mb). Accepted formats are PDF, PNG, JPG, BMP, TIFF, DOC, XLS

name 128 chars max, field contains file name

data field contains base64 encode file contents

manifestFile – file with the all HAWBs (file size limit is 20 Mb). We recommend to use the same file that you gave to the air company. Accepted formats XLS, CSV, DOC, Zipped (XLS, CSV, DOC)

name 128 chars max, field contains file name

data field contains base64 encoded file contents

 

alertEmail – email, We will send a confirmation email with copy of uploaded data

manifestPart – contains manifest part data. Repeated for every manifest part.

departureFacility – string, departure port, 4 or 5 digits

departureDate – departure date/time, format is “yyyy-mm-ddThh:mm:ss[(+|-)hh:mm]”. If timezone is not set (2017-10-19T10:11:12) it defaults to GMT

arrivalFacility – arrival port ,4 or 5 digits

arrivalDate – arrival date/time, format is “yyyy-mm-ddThh:mm:ss[(+|-)hh:mm]”. If timezone is not set (2017-10-19T10:11:12) it defaults to GMT

carrier – ocean carrier's code

tripNumber – voyage number 10 alphanum

unit – describes required unit.

unitId – unit ID (tracking number for parcel, system ID for bag).

scacNumber – SCAC Number, 4 alpha code

vesselName – vessel name

containerNumber – container number 4 alpha/7 digits

vesselCountryOfFlag – vessel’s country of flag, country ISO2 code is used (US, CN, PA etc)

vesselNameType – optional, possible values 0|1, default is 0. Value of 1 is used to provide Lloyd’s vessel code instead of the vessel name in the vesselName field.

Structure of XML in API answer:

ok

conflict

Error description

1534646

123456789

2012-08-31T20:00:00Z

123456

1534646

123456789

123-1234567

34

56

40

10

1

10.125

kg

notFound

Error description

1ZWE31190196785492

mailItem

Direct

2012-08-31T20:00:00Z

10

Picked Up

0

123456

123457

1ZWE31190196785492

123456

20121120-093021

1.125

kg

101234567890

LAX-DHL

DHL

Normal

Direct

2012-08-31T20:00:00Z

10

Picked Up

0

123456

123457

101234567890

123456

20

20.25

kg

LAX-DHL/JFK-USPS

DHL/USPS

…

Fields description:

shippingApiResponse – root node.

manifest – describes a result of creating manifest.

result – operation result, string ok or error.

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

– invalid – transmitted data is invalid;

– conflict – conflict with already existing manifest by userManifesId or some of mailing items can not be included in the manifest.

– system – internal system error.

error – text error description in case of error.

manifestId – system ID of created manifest (in no errors).

userManifestId – transmitted userManifestId.

conflictManifest – describes already existing manifest with that created manifest conflicted (in case of errorType=conflict)

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

warehouseId – ID of warehouse created this manifest.

manifestId – system ID of manifest.

userManifestId – user ID of manifest.

manifestNumber – external manifest number.

senderWarehouseId – ID of warehouse-sender.

receiverWarehouseId - ID of warehouse-receiver.

numItems – total number of mailing items.

numBags – total number of bags.

numParts – number of parts in manifest.

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

weightUnitOfMeasure – constant kg.

unit – repeated for every unit that CAN NOT be included in the manifest (in case of global errorType=conflict)

errorType – units error type. Possible values are:

– invalid – transmitted data is invalid;

– notFound – unit not found;

– conflict – conflict with current unit's state.

– system – internal system error.

error – text error description.

unitId – transmitted unitId.

unitType – one of: mailItem, bag.

conflictMailItem OR conflictBag (in case of unit's errorType=conflict; there may appear only on of them, depending on unitType) – describes corresponding mailing unit; format is the same as in other commands' answers (acceptUnit, etc).

11) command=modifyMarineManifest

Used to modify previously created MBL manifest.

Specific parameters:

data=text/xml (required) – data describing required manifest.

Please note that total size of data parameter must be less than 49.999 Mb

Structure of XML in data parameter:

123456789

123-1234567

34

56.0

kg

123-1234567.PDF

AGGKGKGDDGGDK…YYYY

123-1234567.xls

JFJFYYUOYOOPJFFH…YRYJG

somebody@

LAX

2012-12-10T10:00:00

JFK

2012-12-10T12:40:00-07:00

AA

123

Glory of Seas

AAA/1234567

PA

0

1ZWE31190196785492

…

…

ABCD

Fields description:

shippingApiRequest – root node.

manifest – describes a manifest.

manifestId – system manifest ID.

All other fields are the same as in createManifest command.

Structure of XML in API answer:

ok

conflict

Error description

1534646

123456789

2012-08-31T20:00:00Z

123456

1534646

123456789

123-1234567

34

56

40

10

1

10.125

kg

notFound

Error description

1ZWE31190196785492

mailItem

Direct

2012-08-31T20:00:00Z

10

Picked Up

0

123456

123457

1ZWE31190196785492

123456

20121120-093021

1.125

kg

101234567890

LAX-DHL

DHL

Normal

Direct

2012-08-31T20:00:00Z

10

Picked Up

0

123456

123457

101234567890

123456

20

20.25

kg

LAX-DHL/JFK-USPS

DHL/USPS

…

Fields description:

All fields are the same as in createManifest command's response. Field errorType has one more possible value:

– notFound – required manifest not found;

12) command=cancelMarineManifest

Used to cancel created before manifest (in case of some error in it, etc).

Specific parameters:

data=text/xml (required) – data describing required manifest.

Structure of XML in data parameter:

123456

12345689

Fields description:

shippingApiRequest – root node.

manifest – describes a manifest.

manifestId – system manifest ID.

userManifestId – internal warehouse's manifest ID.

(either manifestId or userManifestId is required)

Structure of XML in API answer:

ok

conflict

Error description

1534646

1534646

2012-08-31T20:00:00Z

123456

1534646

1534646

123-1234567

34

56

40

10

1

10.125

kg

Fields description:

shippingApiResponse – root node.

manifest – describes a result of canceling manifest.

result – operation result, string ok or error.

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

– invalid – transmitted data is invalid;

– notFound – required manifest not found;

– conflict – conflict with current manifest's state;

– sent – manifest is already sent to manifest recipient(s) (see sendMatifest command, etc.)

– system – internal system error.

error – text error description in case of error.

manifestId – system ID of manifest.

userManifestId – user ID of manifest.

conflictManifest – describes existing manifest (in case of errorType=conflict), format is the same as in createManifest command's answer.

13) command=getMarineManifest

Used to get full data of previously created manifest.

Specific parameters:

data=text/xml (required) – data describing required manifest.

Structure of XML in data parameter:

123456

12345689

Fields description:

shippingApiRequest – root node.

manifest – describes a manifest.

manifestId – system manifest ID.

userManifestId – internal warehouse's manifest ID.

(either manifestId or userManifestId is required)

Structure of XML in API answer:

ok

invalid

Error description

1534646

1534646

2012-08-31T20:00:00Z

123456

0

New

123-1234567

34

John Smith

Shippers, LLC

LAX

Los Angeles

CA

90045

US

1 (800) 426-4968

john-smith@

56

John Smith

Shippers, LLC

LAX

Los Angeles

CA

90045

US

1 (800) 426-4968

john-smith@

40

10

1

10.125

kg

ABCD

LAX

2012-12-10T10:00:00

JFK

2012-12-10T12:40:00-07:00

AA

123

20

5

50.125

kg

Glory of the Seas

ABCD/1234567

112233

Amazon

John Doe

Amazon

some address

some city

EU

12345

GB

john@

Direct

waste

Custom instruction

2012-08-31T20:00:00Z

10

Picked Up

0

123456

123457

1ZWE31190196785492

123456

20121120-093021

John Doe

9559 Collins Ave Apt #903

Beverly Hills

CA

90210

US

123-456-9890

john-doe@

John Doe

Amazon

some address

some city

EU

12345

GB

john@

John Smith

Shippers, LLC

LAX

Los Angeles

CA

90045

US

1 (800) 426-4968

john-smith@

100.50

EUR

1.125

kg

0.5

0.4

0.3

m

FR

4901.99.0070

Book

2

14.65

29.30

0.5

…

101234567890

LAX-DHL

DHL

Normal

10.50

1.50

0.00

12.00

…

Direct

2012-08-31T20:00:00Z

10

Picked Up

0

123456

123457

101234567890

123456

20

20.25

kg

LAX-DHL/JFK-USPS

DHL/USPS

…

…

…

Fields description:

shippingApiResponse – root node.

manifest – describes a manifest.

result – operation result, string ok or error.

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

– invalid – transmitted data is invalid;

– notFound – required manifest not found;

– system – internal system error.

error – text error description in case of error.

manifest – manifest description, includes all fields that present in return of getManifestList command, plus:

senderAddress – address of warehouse-sender.

receiverAddress – address of warehouse-receiver.

manifestPart – repeats for every manifest part, includes all info given in createManifest command, plus:

numItems – number of mailing items in this part.

numBags – number of bags in this part.

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

weightUnitOfMeasure – constant kg.

mailItem – repeats for every mailing item in this part, contains full info about mailing item. See detailed description in getUnitInfo command.

bag – repeats for every bag in this part, contains short info about it.

Description

The system has three types of objects:

Parcel

This is the actual parcel that is sent by a Shipper to a specified destination. There are 2 commands that can be used to work with parcels: createMaling and cancelMailing. If the parcel needs to be edited after its creation, it must first be cancelled and re-created.

Bag

This is a bag into which parcels are added during the preparation for the shipment process wherein they will be picked up. There are 2 commands that can be used to work with bags: createBag and cancelBag. If the bag needs to be edited after its creation, it must first be cancelled and re-created.

The parcel is the only operating object in the system that is required for work. Bags are specified groups of parcels that enable some features (for example, to receive a group of parcels by a Shipper), but are not required for work. Only the use of the parcel is required for work.

Internal ID

All objects in the system are identified by an internal ID which is reported in a system response for the objects created and it can be used in other operations to classify these objects later. The ID for the parcels is its trackingNumber and can be transferred from an outside program while creating a parcel or it can be generated by the system. The ID for Bags is bagId and is generated by the system.

While creating packages and bags, the Shipper can also transmit its own internal ID; shipperItemId and shipperBagId, respectively (the ID must be unique to the Shipper for the duration of work). These IDs can be used later to identify objects in place of using the system ID (or with them - in this case, both identifiers must be valid to locate the object). The use of this internal ID is optional but recommended, as it assists in avoiding possible mistakes. For example, if while creating a package with a label (i.e. a trackingNumber is not transferred) the parcel itself was created, but the API result wasn’t received due to communication problems. When a second attempt to create this parcel is made, a duplicate of the parcel will be created because a shipperItemId was not used. An error may be displayed (which can be corrected properly later).

Errors

If an error occurs during system operations, the response of the system contains information that allows the error to be corrected accurately. For example, if you are trying to create an ID that already exists in the system you will receive a result containing a type of “conflict” error that includes the data of the existing parcel. Based on this information presented, a determination can be made regarding the reasons for the error. For example, if the existing package with the same ID was created a week ago, this may be the mistake of client software. If the creation of the parcel took place recently, the API response had not been received due to communication problems and data for the existing parcels in the new result matches the one created, it can be assumed that the parcel was created successfully and therefore we can take the data from this result.

Live Examples

The Shipper uses its own labels and is generating a parcel to John Doe. The Shipper is supposed to call createMailing with label=0 and the trackingNumber=123456 (for instance)

The Shipper warehouse worker made a mistake. The parcel to John Doe was destroyed accidentally. The Shipper is supposed to call cancelMailing with trackingNumber =123456.

The Shipper worker made a mistake and forgot to add an item into the parcel. The Mailing is to be cancelled (use command cancelMailing), and a new one is to be created (use command createMailing). The mailing ID can be the same as it was the first time. The old Mailing should be cancelled prior creating a new mailing with the same mailing ID because the system requires ID uniqueness.

The Shipper places individual parcels in a shipping bag. The Integrator working with the Shipper should:

3.1. Keep local records of a “temporary bag.” The temporary bag instance is not to be transferred to ACP.

3.2. The worker keeps packing the real bag (or some other shipping unit), and the Integrator is supposed to keep records of mailing IDs.

3.3. When the “temporarily bag” is full (the worker is ready to seal the physical bag), the Integrator is supposed to call the command createBag.

3.4. Save the bagId received and the label graphics. Print the label.

3.5. The worker should seal the label on the bag.

The worker accidentally “sealed” the bag too early. The old bag should be cancelled (use command cancelBag) and a new bag created (use command createBag). Follow the same order as for Mailing cancellation.

Two or more Shipping Stations:

If the Shipper has two or more shipping stations (different workers pack orders in two different places) – it is Integrator responsibility to maintain different “temporarily bags” locally. Ideally, each worker should have his or her own “temporary bag” that he or she works with. Each time when one of the workers finishes packing their bag – createBag is supposed to be called.

Demo and Training Access

If you have a specific question that is not answered in this document; or you need to test a chain of command to check some business case – feel free to use the demo access at You may use a general API key (published on the page by default) – just remember that it’s available for anyone; therefore the database may content random parcels. Feel free to use your own API key – just don’t forget to mark the test mode checkbox – otherwise your account might be billed.

[pic]

................
................

In order to avoid copyright disputes, this page is only a partial summary.

Google Online Preview   Download