Overview
fulfillmenttools offers a convenient way to send and track parcels. This page tells you more about the utilization of this feature.
Last updated
fulfillmenttools offers a convenient way to send and track parcels. This page tells you more about the utilization of this feature.
Last updated
fulfillmenttools can connect to various carriers allowing you to create shipments and corresponding parcels. Please clarify beforehand which carriers should be made available to your instance.
However, the usage of existing & ready to use carriers is similar and can be used no matter how many carriers you operate.
Courier, Express and Parcel Services (or in Short: CEP) refer to entities, that are in general configured in fulfillmenttools. It depends on your setup which CEP Providers are available & ready to use. The API description including some documentation about the used attributes can be found in our API reference
Good to know
By default, a freshly created tenant system does not show the available carriers within the backoffice since most of the carriers are country-specific. Activating a carrier has to be done via API. After that, it can be configured within the backoffice.
To get a list of available carriers you can issue the following call:
The response gives you a list of configured carriers, along with some general information and their key, which describes which kind of implementation is chosen by fulfillmenttools whenever this carrier is used to, for example, issue a label request or setup track and trace connection for a parcel. You can get a more detailed look at a configured carrier by requesting one identified carrier instance, for example:
A Carrier instance is a singleton in any given fulfillmenttools platform. That means in general it can exist exactly once per tenant.
As you can see in the above response there are some configurations made to this exact carrier (DHL in this case). These configurations can be done on every carrier instance (check Add Carrier for details or continue reading.
A carrier can be created by issuing the following call:
As you can see there are already some configurations to this carrier provided upon creation. Some of the interesting data is
Depending on the used Carrier implementation (depicted by the tag key) some additional configuration can be used to successfully operate a carrier:
One of the most important configurations is the attribute returnLabel in a given configuration. It tells fulfillmenttools whether a return label should be created with every label requested from the given carrier.
Please refer to Get Carrier Configuration from API and Change Configuration via API in our Swagger Documentation to understand which kind of configuration is necessary / advised.
This resource describes the stores, warehouses, popup stores, locations, etc. of the fulfillment network. In general, a facility is a place where fulfillment processes take place or should be considered. Details see use case Add and Manage Facilities
In this carrier services related use case a facility is a place where CEP services pick up parcels or inter facility transfers are started / finished.
Users can assign different carriers to one facility. With this information a fencing can be implemented where orders which need to be shipped by a chosen carrier are routed to a facility where this carrier is active. Carrier that are enabled on tenant level must also be enabled for the facilities in which this carrier is available.
The Facility-To-Carrier-Connection is (some people already understood) the connection between a facility and a carrier. Many configurations that allow for frictionless carrier services have to be configured here. Please refer to FacilityCarrierConnection for detailed information on every attribute. Here are some of the attributes worth mentioning:
Let's assume that we have a facility (see Add and Manage Facilities) and a carrier (see Creation of a carrier) already created. Lets receive the correspondent entities first (omitting some of the attributes):
Please take note of two important parameters we are going to use in the following: The id of the facility (a81a1c85-cfe5-49d3-81d3-675154ef323e in this case) and the id of the carrier (488bd1a6-6c76-4407-8dab-ece716dac14d). We need both values in order to create a connection between those two entities.
By using both values in our target URL the following call we configure the carrier to said facility:
The empty array of the attribute deliveryAreas indicates, that there are no restrictions regarding delivery targets.
We also conveniently set the cutoff time to 16:30, because in our fictive case this is the time when the DHL driver typically arrives at the Darkstore to pick up the parcels.
That's it: As long as the Carrier and the FacilityCarrierConnection stays in status "ACTIVE", it should be possible to create shipments and in the end also parcels using DHL as a CEP (see Create a shipment with parcels to track) originating from this facility.
Before we dive into the process of sending a parcel we need to clarify two more entities: Shipment and Parcel.
Let's assume we already connected a Facility with a Carrier using a FacilityCarrierConnection (see Connect an existing carrier to a facility). In this use case we are going to create a standalone shipment and two parcels - without having a Pickjob or any other leading entity. This is a perfect example on how flexible fulfillmenttools is: There might be standard processes, but you are also able to use parts of the system to suit your operational needs - like for example the need of dynamically create a Shipment Label for further use in other systems.
With the following call we create a shipment to be picked up in facility with ID 4fd70a59-9efe-40fd-808b-08ae86ca558f using the DHL Carrier with ID 488bd1a6-6c76-4407-8dab-ece716dac14d:
As you can see: The shipment has knowledge about the facility, the CEP and the address where to deliver.
As mentioned above: This shipment is not connected to any existing process! If you want to create a shipment to a specific process you need to provide the attribute processId within the request. Also shipments can be created during preceding processes. In that case data like the target address is provided via the order or the pickjob to the shipment which is created by fulfillmenttools.
Having the Shipment in place we are now ready to create a parcel via this shipment by issuing the following request:
Please take note that we are issuing a parcel the most simple way in which fulfillmenttools will use all necessary information from the corresponding shipment. However, you are also able to overwrite certain data from the shipment for each created parcel, such as the dimensions, the recipient, the sender or return address.
We just created the entity that represents the parcel in status OPEN. Now, in an async matter, fulfillmenttools is automatically taking care of the actual advising of the parcel label. During the time it takes fulfillmenttools and the CEPs API to negotiate and create a parcel, the status of the parcel changes from OPEN via PROCESSING to finally DONE. The shipment also transparently changes its status to CONFIRMED as soon as all created parcels of the shipment reached the status DONE.
Once the parcel reached one of the status DONE (happy case) or FAILED it is time to take a look at the result attribute of the parcel:
The result in general shows details about the outcome of the request:
In case of a successful termination of the request towards this specific CEP API (see above) we can find the trackingNumber, a tracking URL, a label to download the sendLabel and also with the attribute labelUrl a document that consists of all the documents that are of importance to this parcel (such as for example deliveryNotes, return labels, etc.).
In case of a unsuccessful termination of the request the summary attribute carries information about the root cause of the failure. The contents of this error message usually originates from the carrier - fulfillmenttools has limited control about the data.
In this case we are ready to download the avised label using the following call:
Be aware that the response has the Content-Type application/pdf and contains binary data.
Requesting a special service from the carrier
If a special is required, this can be requested either when creating a parcel by passing the service object with the desired service set to true:
It is also possible to pass the information directly when creating an order. In the order the services can be directly listed for each preferredCarrierWithProducts:
Only services offered by the chosen carrier will be taken when creating a parcel. Providing a service for a carrier which does not offer that service will be ignored.
Whether you want to operate against sandbox URLs or against real URLs provided by CEPs can be configured on different levels.
You can set carrier specific URLs tenant-wide, so they are being used in every facility or you can decide to set URLs for specific facilities separately. In order to achieve this, set the URLs as shown in the following by setting the carrier configuration and/or the facility carrier configuration.
Setting the carrier URLs on carrier level will result in these URLs being used whenever this carrier is used in a facility. Use the following endpoint to set the URL.
The following example demonstrates how to set the service url and track and trace url for a DHL carrier.
Setting the carrier URLs on facility level will overwrite any URL that has been set on carrier level for the respective carrier. The URLs on facility carrier level can be set by updating the configuration in the facility carrier connection. The following endpoint can be used for this purpose.
This example shows how to set the urls for a GLS carrier.
| Attribute | Description |
|---|---|
| Attribute | Description |
|---|---|
| Entity | Description |
|---|---|
defaultParcelWeightInGram
This value depicts, no surprise here, the default value (1000 gram) to a parcel advised using this carrier. However, the actual weight might be overwritten by the actual call for the creation of a parcel (see Add Parcel in our API Specification).
parcelLabelClassifications
This array of values describes which parcel dimensions should be selectable by a client when issuing a parcel. Please see, that these values are dependent on the carrier and your contract with it. It also maybe not be a mandatory value and could possibly be omitted.
credentials
The credentials that are used to connect to the carriers' API. Which kind of credentials is needed depends on the carrier (selected by the attribute key. In this case the DHL API in Version 2 is selected. Thus we need to provide an API Key. Also there is (especially for DHL) the possibility to provide Fallback Credentials using the legacy DHL API ("DHL Geschäftskunden API" in this case.)
logoUrl
This optional attribute can be used to set a specific logo to a custom carrier or to overwrite the fallback logos for standard carriers provided by fulfillmenttools if needed.
cutoffTime
Value (hour and minute) describe the time when the carrier (usually) shows up to take parcels with him. This information is especially useful when configuring SAMEDAY deliveries as it is crucial to have finished any fulfillment process until the arrival of the carrier.
deliveryAreas
This optional value might be of special interest to Custom Carriers and specific SAMEDAY carriers. It shows which target addresses (identified by an array of ISO 3166-1 alpha-2 conform country codes and their respective postalcodes) can be a valid target to a parcel sent via this carrier from the facility.
Parcel
A parcel is the digital representation of one physical parcel that is avised / on its way to the consumer.
Shipment
A shipment is the bracket around all parcels sent within a process using the same carrier. Please note: Certain data could vary from parcel to parcel: dimensions or targetAddress of the shipment can be overwritten in a parcel instance.
ID of the carrier you want to update the configuration
Carrier Configuration
Carrier Configuration was found & you were allowed to access it. The result is in the body.
ID of facility you want to get
The referenced carrier ID
Representation that describes the facility
Facility specific credentials for this carrier
Facility specific configuration for this carrier
This is the well known name for a supported CEP partner. Can be adapted to the clients needs.
"DHL Köln"It is taken into consideration for all carriers. Default: INACTIVE
Modification was successful.
The date this entity was created at the platform. This value is generated by the service.
"2020-02-03T08:45:51.525Z"The date this entity was modified last. This value is generated by the service.
"2020-02-03T09:45:51.525Z"The version of the document to be used in optimistic locking mechanisms.
42