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. The JWT token is valid until next token needs to be retrieved.
Create a Shipment
Shipments are created by using the POST operation of the 'shipment' endpoint (POST/shipment).
Parameters
| Parameter | Mandatory | Type | Example | Description |
| tracking_code | yes | string | "tracking 123456789" | The shipment tracking number given by the carrier. |
| reference_number | no | string | "ref123456" | The reference_number represents your internal reference for this shipment inside your IT system. The reference_number has to be unique. |
| pickup_point_selected | no | boolean (true or false) | "false" | Is the customer address a pickup point (i.e. postal shop, retail shop etc) |
| planned_pickup_datetime | yes | date: yyyy-mm-ddThh:mm:ss+nnnn | "2017-08-19T15:47:00+0000" | Date and time agreed with Seven Senders to pick-up the shipment at your warehouse. |
| 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" | This value is static per warehouse you ship from and will be provided by Seven Senders during implementation. |
| shipment_tag | no | object | {"sku":"nikeAir2017"} | Tags/Properties to allow you to segment your shipments. |
| recipient_address | yes | string | "Schwedter Str.36A, 10435 Berlin,Germany" | Customer's address. Do not use line breaks. If a DHL "Packstation" has been chosen, please state "Packstation" and number (e.g "Packstation 123" |
| return_parcel | no | boolean [true or false] | "false" | Indicates whether the shipment is a return from the customer |
| trackable | no | boolean | "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. |
| order_id | yes | string | "order123456" | The order reference inside your system. Alternatively, your can provide us an unique ID |
| carrier | carrier: {carrier_name: "dhl"; carrier_country: "DE"} | |||
| carrier. carrier_name | yes | choice: See the list of choice below | "dhl" | Selected carrier to ship the parcel |
| carrier.carrier_country | yes | 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. |
| 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_company_name | no | string | "Seven Senders" | Customer's company name if he/she choose to be delivered at his/her company. |
| recipient_email | yes | "d.hasselhoff@sevensenders.com | Customer's email address to send email notification to your customer through Seven Senders Portal. Without this information, no email notification can be sent. In case you're only using our delivery product, you can provide a "default" email-address (e.g. cs@yourcompany.de) | |
| 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) | "+4915223455981" | Customer's phone number. |
| recipient_address_details | 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" |
| weight | yes | number | 1.12 | Shipment weight in KG (including packaging) |
Available Carriers
The table below contains the currently available carriers (subject to change). All currently available carrier are applicable by applying the GET/carriers operation.
| Carrier_country | Carrier_name |
| AT | postat, dpd, ups, dhl |
| BE | bpost, dpd, kiala, mondialrelay, ups, dhl |
| CH | swisspost, dpd, ups, dhl |
| CZ | ceskaposta, dpd, ups |
| DE | dhlexpress, 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, SDAposteitaliane |
| 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'.