Acp shipper Integration api 10. Note: This version of document is outdated and deprecated!
Download 0.61 Mb.
|
ACP Shipper Integration API v1.10. NOTE: This version of document is outdated and DEPRECATED! 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 http://acpapi.com/ in section “Manuals”. Description Endpoint url is https://acpapi.com/API/ OR http://acpapi.com/API/ (for test purposes) 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 % + 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: %, ?, =, &, #. 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: XSD-schemes as described below XML-requests may be found here: http://acpapi.com/API/schema/ Possible Commands: 1) command=createMailing Used for the creation of direct mailing item(s) and (optional) printable shipping label.
– 0 – not create label (DEPRECATED) – 1 – create usual (ZoomParcelGround) label – 2 – create expedited (ZoomParcelExpedited) label – 3 – create priority (ZoomParcelPriority) label
– 0 – usual clearance – 1 – express clearance
…
…
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. 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.
currency – currency code in ISO 4217 format (USD, EUR, …) 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
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 35 chars. manufacturerCode (optional) – product manufacturer's code, max length 35 chars. 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 desired) weight (optional) – total weight or this product. Structure of XML in API answer: …
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. 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).
…
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: …
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.
…
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.
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: …
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.
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.
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.
bagId – system id of the bag. shipperBagId – internal shipper's bag id. (either bagId or shipperBagId is required) Structure of XML in API answer: 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=closeDay Closes day and generates End of Day manifest. Specific parameters: label=0|1 (optional, default is 0) – return End of Day manifest (1) or not (0). bagLabels=0|1 (optional, default is 0) - return all this day's bag labels (1) or not (0). labelFormat=PNG|PDF|EPL2 (optional, default is PNG) – required label image format. Structure of XML in API answer: …
Fields description: shippingApiResponse – root node. day – describes result of closing day operation. result – operation result, string ok or error. errorType – error type in case of error. Possible values are: – empty – no new mailing items created since last day closing; – system – internal system error. error – text error description in case of error. dayId – system id of closed day. shipperDayId – internal shipper's day id, always empty for this command. labelFormat – format of created label, one of PNG, PDF, EPL2. label – base64-encoded content of created label. bag – individual current day's bag (if input parameter bagLabels=1). Repeated for all bags created by createBag command in current day. bagId – system id of this bag shipperBagId – internal shipper's bag id. labelFormat – format of created label, one of PNG, PDF, EPL2. label – base64-encoded content of created label. 6) command=reopenDay Undo close day to allow add/remove mailing items, bags, etc.
result – operation result, string ok or error. errorType – error type in case of error. Possible values are: – notFound – there are no closed days; – conflict – conflict with last closed day's state; – system – internal system error. error – text error description in case of error. dayId – system id of reopened day. shipperDayId – internal shipper's day id.
creationDate – closing date/time in UTC, format is “yyyy-mm-ddThh:mm:ssZ”. status – day's current status (“New”, “Picked Up”, etc). dayId – system day id. shipperDayId – internal shipper's day id. 7) command=createDay Closes day and generates End of Day manifest. Unlike closeDay, all included units (mail items and bags) must be specified in the request.
…
…
Fields description: shippingApiRequest – root node. day – describes created day. shipperDayId (optional, desired) – internal shipper's day id, max length 50 chars. If used, allows this day to be pointed to this id later. bag – describes particular bag for inclusion in the day. Should be repeated for each included bag. bagId – system id of the bag. shipperBagId – internal shipper's bag id. (either bagId or shipperBagId is required) mailItem – describes particular mailing item for inclusion in the day. Should be repeated for each included mailing item that is not included in any bag. 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: …
…
Fields description: shippingApiResponse – root node. day – describes result of creating day operation. result – operation result, string ok or error. errorType – error type in case of error. Possible values are: – invalid – transmitted day is invalid; – conflict – conflict with already existing day or current bags/mailing items' state; – system – internal system error. error – text error description in case of error. dayId – system id of this day, for future usage in other commands, like cancelDay (may be empty in case of error). shipperDayId – internal shipper's day id. labelFormat – format of created label, one of PNG, PDF, EPL2. label – base64-encoded content of created label.
creationDate – creation date/time in UTC, format is “yyyy-mm-ddThh:mm:ssZ”. status – day's current status (“New”, “Picked Up”, etc). bagId – system day id. shipperDayId – internal shipper's day id.
errorType – error type (in case of error). Possible values are: – invalid – transmitted bag is invalid; – notFound – requested bag found; – conflict – conflict with current bag's state; – system – internal system error. error – text error description. bagId – system id of this bag shipperBagId – internal shipper's bag id. labelFormat – format of created label, one of PNG, PDF, EPL2. label – base64-encoded content of created label.
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 day 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.
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. 8) command=cancelDay Used to cancel previously created day for a particular reason.
dayId – system id of the day. shipperDayId – internal shipper's day id. (either dayId or shipperDayId is required) Structure of XML in API answer: Fields description: shippingApiResponse – root node. day – describes result of canceling day operation. result – operation result, string ok or error. errorType – error type in case of error. Possible values are: – invalid – transmitted day is invalid; – notFound – requested day not found; – conflict – conflict with current day's state; – system – internal system error. error – text error description in case of error. dayId – system id of this day, the same as in request. shipperDayId – internal shipper's day id. conflictDay – in case of conflict with current day's state (errorType=conflict), contains description of the day. creationDate – creation date/time in UTC, format is “yyyy-mm-ddThh:mm:ssZ”. status – day's current status (“New”, “Picked Up”, etc). dayId – system day id. shipperDayId – internal shipper's day id. 9) command=getInfo Used to get information about all new direct mailing items and bags created in account since last closeDay operation, that have not been picked up yet (command may be used even if shipper does not use closeDay at all ad works only with mailing items). May be used to verify current account's state before requesting closeDay or for handling possible errors that may appear while working with API.
…
…
Fields description: shippingApiResponse – root node. info – describes result of operation. result – operation result, string ok or error. errorType – error type in case of error. Possible values are: – system – internal system error. error – text error description in case of error.
creationDate – creation date/time in UTC, format is “yyyy-mm-ddThh:mm:ssZ”. status – item's current status (“New”). 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. bag – individual current day's bag. Repeated for all bags created by createBag command in current day. creationDate – creation date/time in UTC, format is “yyyy-mm-ddThh:mm:ssZ”. status – bag's current status (“New”). bagId – system bag id. shipperBagId – internal shipper's bag id. comment – shipper's bag comment. Directory: DOC DOC -> Enterprise Network Management iPost: Implementing Continuous Risk Monitoring at the Department of State DOC -> Concept stage DOC -> Application for acem DOC -> What programs are available? DOC -> 100 Village Primary School Music Classrooms DOC -> Observational Assessment of Teaching Practices Teaching Assessment Initiative Proposal Submitted to The Teachers for a New Era project DOC -> Concept stage DOC -> Traditional British values Download 0.61 Mb. Share with your friends:
|