This section provides all information needed to connect to Seven Senders via API when using our software service Seven Senders Portal.
- API Key Authorization
- Create an Order
- Update the State of an Order
- Create a Shipment
- Update an Order to provide the 'boarding complete' Information
- Additional Operations
API Key Authorization
The credentials for the API consist of a access-key, a string provided by Seven Senders. Before starting using the API, you need to request a JWT token by applying the POST/token operation containing your access-key. The JWT token should then be used inside the 'Authorization' header for every further request. Format: Authorization: Bearer YOUR_TOKEN
Workflow
In the following, the workflow is described step-by-step.
Create an Order
Orders are created by using the POST operation of the 'order' endpoint (POST /order).
Parameters
Parameter | Mandatory | Type | Example | Description |
order_id | Yes | String | "order123456" | The order reference inside your system |
order_url | Recommended | String | At which website the order was submitted | |
order_date | Yes | String (dd.mm.yyyy hh:mm:ss) | "2017-08-15T16:53:07+01:00" | The Date when the order was created inside your system |
boarding_complete | No | boolean [true or false] | “False” | Information indicating (if an order consists of multiple parcels) that all shipments of an order have been imported (cf. for this 1.5 “Update an order to provide us with the “boarding complete” information”) |
language | Recommended | Array[string] | “en” | What is the language of the customer for this order or the language for the shop_order_url defined. If you intent to send mails/sms notifications to your customers, we recommend that you provide this information for each order. The reason is that a notification can only be send if the shop_order_url and the Language are defined on the order |
order_tags | No | Array[string] | “SKU 1234” | Tags/Properties to allow you to segment your orders |
promised_delivery_date | Recommended | String | "2017-08-15T16:53:07+01:00" | The delivery date you’ve promised the customer. The promised_delivery_date is an important parameter* (cf. comment below the table) |
*Promised_delivery_date: Fundamental information since it’s used as input to calculate various KPI’s within Seven Senders Portal. Therefore, we highly advise you to provide this information in an acceptable accuracy.
Further Order Operations Available
- GET/orders/{id} → retrieve a single order that has previously been imported
- GET/orders → retrieve multiple orders that have previously been imported
- PUT/orders/{id} → updates (partially) an existing order
- DELETE/orders/{id} → delete one or multiple existing order/orders
Note: the given ID within the response when creating an order is needed to update or delete an order.
Update the State of an Order
Update the state of an order via the POST/order-states operation.
Parameters
Parameter | Mandatory | Type | Example | Description |
order_id | Yes | String | "order123456" | The order reference inside your system |
state | Yes | Choice: See tabel below | “paid” | The current state of the order |
datetime | Yes | String (dd.mm.yyyy hh:mm:ss) | "2017-08-15T16:53:07+01:00" | The date and time |
location | No | String | "Schwedter strasse 36A 10435 Berlin" | The physical location of the order |
Available Order-states
Status | Description |
new | Status when the order is imported |
paid | Order was paid by the customer |
in_production | This status is useful if you need to produce/made the item ordered by the customer |
In_preparation | The order is processed inside your warehouse |
Create a Shipment
Shipments are created by using the POST operation of the 'shipment' endpoint (POST/shipment). You need to link it to the corresponding order. The link between shipment(s) and order is done through the 'order_id'. The order status will then automatically change to 'shipped'.
Note: A shipment can only be linked to one order, but an order can consist of more than one shipment.
Parameters
Parameter | Mandatory | Type | Example | Description |
order_id | Yes | String | "order123456" | The order reference inside your system. The shipment will be link to this order. Alternatively, you can provide us an unique Id |
tracking_code | Maybe | String | "tracking123456789" | The shipment tracking number given by the carrier. Mandatory! If the tracking code is not available a value for the parameter “reference_number” needs to be provided (see parameter “reference_numer” and Bartolini Workaround) |
reference_number | Maybe | String | "ref123456" | The unique reference_number represents normally your internal reference for this shipment inside your IT system. This information is used when the carrier does not provide a tracking number before the FHS (e.g the Italian carrier BRT). Compare also the section Carriers that provide the tracking code after FHS Mandatory if no tracking code is provided & the reference number needs to be unique |
carrier: | carrier: {carrier_name: “dhl”, carrier_country: “DE”} | |||
carrier.carrier_name | Maybe | choice: See the list of choice below | "dhl" | Selected carrier to ship the parcel. Mandatory if a tracking number is provide |
carrier.carrier_country | Maybe | choice: See the list of choice below | “DE” | Country where the parcel is handed over to selected carrier / scanned for the first time by the selected carrier. Mandatory if a tracking number is provided |
carrier_service | No | choice: "standard" "express" "other" | "express" | Service / Product / Tariff used by the carrier |
recipient_first_name | Yes | String | “David” | Customer’s first name |
recipient_last_name | Yes | String | “Hasselhoff” | Customer’s last name |
recipient_email | Yes | Customer’s email address Send email notifications to you customer through Seven Senders Portal Without this information, no mail notification can be send. In case you’re only using our delivery product, you can provide a “default” email-address (e.g. [email protected]) | ||
recipient_address | Yes | String | "Schwedter str. 36A" | Customer’s address. Do not use line breaks. If a DHL “Packstation” has been chosen, please state “Packstation” and number (e.g “Packstation 123”) |
recipient_zip | Yes | String | "10435" | Customer’s ZIP code |
recipient_city | Yes | String | “Berlin” | Customer’s city |
recipient_country | Yes | String | “de” | Customer’s country. Use ISO 3166-1 alpha-2 |
recipient_phone | No | phone: Use + for the country code (see example) | "+4915224565981" | Customer’s phone number. Use this field to send sms notifications to your customer through Seven Senders Portal Without this information, no sms notification can be send. Note: this is a paid feature. If you’re interested in sending sms to your customers - please get in contact with us |
recipient_company_name | No | String | “Seven Senders” | Customer’s company name if he/she choose to be delivered at his/her company. |
return_parcel | No | boolean [true or false] | “false” | Indicates whether the shipment is a return from the customer |
| trackable | No | boolean [true or false] | "true" | Indicates if a shipment is trackable. By default set to true. Setting this parameter is prerequisite for displaying information on the Tracking Page and/or Embedded Widget in case of non-trackable shipments |
pickup_point_selected | No | boolean [true or false] | “false” | Is the customer address a pickup point (i.e postal shop, retail shop etc) ? |
weight | Yes | number | 1.12 | Shipment weight in KG (including packaging) |
planned_pickup_datetime | Yes | date: dd.mm.yyyy hh:mm:ss | "2017-08-19T15:47:00+0000" | Date and time agreed with the carrier to pick-up the shipment at your warehouse. When using the delivery products, state the with Seven Senders agreed on pickup time. This timestamp triggers the start of the delivery lead time. The planned pickup date represents an important parameter” (cf. comment below the table) |
comment | No | String | “Please be careful” | Comment regarding this shipment left by the customer or for your internal usage |
warehouse_address | Yes | String | "Kochhannstr. 38 10247 Berlin" | Warehouse full address. Do not use line breaks. |
warehouse | Yes | Choice: List of all warehouse defined inside your account | "warehouse" | The Warehouse name defined inside your account. Important: the provided warehouse name needs to be identical to the one(s) defined in your Seven Senders Portal account. |
shipment_tag | No | object | {"sku":"nikeAir2017"} | Tags/Properties to allow you to segment your shipments |
*Planned_pickup_datetime: Fundamental information since it’s used as input to calculate various KPI’s within Seven Senders Portal. Therefore, we highly advise you to take cut-off times, weekends etc. in to account when setting-up the “planned_pickup_datetime” logic.
Carriers Providing Tracking Code after FHS
There are some exceptions where the carrier is not providing a tracking code before the first hub scan at LMC (i.e. when the shipping label has been created).
Bartolini (BRT) (IT) is a carrier that does not always provide the tracking code before the FHS.
Bartolini (BRT) Workaround
Normally when creating a shipment inside the Seven Senders system , a tracking number (parameter: “tracking_code”) is required (cf. Create a Shipment). In case of BRT you need to pass a unique reference number (Parameter: “reference_number”). This implies also that no values for the parameters “carrier_name” and “carrier_country” can be transmitted. Once BRT scans the parcels in the hub, Seven Senders automatically retrieves the generated tracking codes and updates the corresponding shipments.
Note: this reference number needs to be identical to the number transmitted to BRT when notifying them about the shipment!
Available Carriers
The table below contains the currently available carriers (subject to change). But you can also retrieve all currently available carrier by applying the GET/carriers operation.
| Country | Carrier |
| AT | postat, dpd, ups, dhl |
| BE | bpost, dpd, kiala, mondialrelay, ups, dhl |
| CH | swisspost, dpd, ups, dhl |
| CZ | ceskaposta, dpd, ups |
| DE | dhl, deutschepost, gls, ups, hermes, dpd, tnt |
| DK | postnord, ups, dhl, dpd |
| ES | correos, seur, seur_international,asm, mrw, ups, dhl |
| FI | posti, postnord, ups, dhl, dpd |
| FR | colissimo, chronopost, tnt, dpd, mondialrelay, colisprive, gls, dhl, ups |
| GB | royalmail, yodel, parcelforce, hermes, dpd, dhl |
| IT | brt, tnt, gls, ups, dhl, nexive, posteitaliane, SDA posteitaliane |
| LU | dhl, ups, kiala, dpd |
| NL | postnl, kiala, dpd, mondialrelay, tnt, ups, dhl |
| NO | postnord, ups, dhl, dpd |
| PL | dpd, gls, ups, dhl, poczta polska |
| SE | postnord, ups, dhl |
| SK | ceskaposta, dpd, ups, dhl |
Definition of carrier and carrier_country in case of Cross Border Shipments
Defining the carrier and carrier_country in case of cross border shipments depends on the “set-up”. There are three scenarios (see picture below).
1. Scenario: Using the Seven Senders Delivery (direct injection) service
The carrier and carrier_country provided should be the carrier which is in charge for the 'last mile'.
- Shipping from: Germany (given it is the warehouse location)
- Shipping to: France
- Carrier: Seven Senders and Colissimo
In this example the carrier is 'Colissimo' and the carrier_country 'fr'.
2. Scenario: Shipping with Carriers (own contracts)
The carrier and carrier_country should be defined as the one you’re handing the parcel to in the first place.
- Shipping from: Germany (given it is the warehouse location)
- Shipping to: France
- Carrier: DHL DE and DHL FR
In this scenario, the carrier is 'DHL' and the carrier_country 'de'.
3. Scenario: Shipping with Carriers (own contracts) + self-organized Direct Injection
The carrier and carrier_country is the one that is in charge for the 'last mile'.
Shipping from: Germany (given it is the warehouse location)
Shipping to: France
Carrier: Freight Forwarding Company XYZ and DHL FR
In this scenario, the carrier is 'DHL' and the carrier_country 'fr'.
Shipment Statuses
After importing a shipment inside your account, Seven Senders updates the shipment's status based on information received from the carrier. A shipment can have the following status:
Status | Description |
New | The shipment has been created inside your Seven Senders account |
Info | The carrier has received the shipment information into his system |
Pickup | The shipment has been picked up by the carrier at your warehouse |
Hub scan at LMC | The Last Mile Carrier has scanned your shipment inside his hub |
Out for delivery | The Last Mile Carrier went to deliver the shipment to the customer |
Delivered to pickup point | The shipment has been delivery to a third party |
Delivered | The shipment was succesfully delivered to the customer |
Lost | The shipment has been lost |
Further Shipment Operations Available
- GET/shipments/{id] → retrieve a single shipment that has previously been imported
- GET/shipments → retrieve multiple shipments that has previously been imported
- PUT/shipments/{id} → updates completely or partially an existing shipment
- DELETE/shipments/{id} → delete one or multiple existing shipments
Note: the given ID within the response when creating an shipment is needed to update or delete an order.
Update an order to provide the 'boarding complete' information
Whenever all items of an order have been shipped and the corresponding shipments were created inside the Seven Senders Portal account, you need to provide us this information by using the PUT/orders/{id} operation. Through the PUT/orders/{id} operation you have to update the 'boarding_complete' parameter. The parameter value needs to be changed from 'False' (not all items shipped”) to 'True' (all items shipped).
Note: updating the “boarding_complete” parameter is important since this information is required to transfer an order (once all shipments have been delivered) to the state 'Completed':
- If boarding complete = true (or null) and all shipments are delivered → order completed
- If boarding complete = true (or null) and 1 shipment is delivered → order NOT completed
- If boarding complete = false and 1 shipment created in delivered → order NOT completed
- If boarding complete = false and all shipment created in delivered → order NOT completed
Additional Operations
- GET/carriers → retrieve all carriers available to create shipments in the Seven Senders system
- GET/shipments/{id}tracking_history→ retrieve all events for a given shipment inside your Seven Senders account.
- GET/warehouse → manage you warehouses used inside your Seven Senders account (operation coming soon)