Acp shipper Integration api 10. Note: This version of document is outdated and deprecated!

Description

The system has three types of objects:

1. 
   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.
   
2. 
   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.
   
3. 
   Day
   The day is an object that groups all bags and parcels that are created during a specific period of time (not necessarily the actual day) and are sent for shipment together. There are also 2 commands that can be used to work with days: closeDay and reopenDay. closeDay groups all new bags and parcels that have not been grouped or sent yet, while reopenDay cancels the last such grouping.
   

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. The ID for Days is dayId and it is also generated by the system (as opposed to the others, the dayId is purely informational and not used anywhere else; the command reopenDay opens the last closed day).

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.

The additional command getInfo provides current information about all newly created (i.e. still unsent) parcels and bags from the last closing day. It can be used before applying the command closeDay to ensure that all of the data on the server is correct. In the case of inaccurate results, you will be able to receive current information and to choose how to handle any errors based upon it.

2. Live Examples

1. 
   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)
   
2. 
   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.
   
3. 
   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.
   
4. 
   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.
   
5. 
   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.
   
6. 
   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.
   
7. 
   At the end of the day OR in the middle of the day when a track is leaving the Shipper warehouse, the Integrator is supposed to call closeDaycommand. This may be several closed days during one real day.
   
8. 
   In the case that the day was accidentally closed too early – the Integrator is supposed to reopen the day (use command reopenDay). After the day has been reopened, it can be modified.
   

3. Demo and Training Access