This section provides all information needed to connect to Seven Senders via API when using our software service Seven Senders Portal.
- API Key Authorization
- Workflow Chart: Order & Shipment
- Create an Order
- Update the State of an Order
- Update an Order to provide the 'boarding complete' Information
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.
Workflow Chart: Order & Shipment
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) |
| Available language | bg; cs; da; de; el; en; es; et; fi; fr; ga; hr; hu; it; lt; lv; mt; pl; pt; ro; ru; sk; sl; sv & uk (Note: Language is a LOWERCASE two letter ISO2 Code) | |||
*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 |
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