ShipmentServer API Endpoints
Version 2.0 is not released yet - This documentation is for pre-read only.
- Generate the client_id & client_secret
- Request an access token using the clint_id & client_secret
- Using the access token in a request
How to construct a request
- Using a configuration in the production or test environment
- Using the default test account in the test environment
- How to use CURL examples
Methods on the API
- Shipments - to create shipments or reprint a label
- Stacks - to transmit one or more shipments
- Batches - inpect generated EDI date or documents
- Services - get information about products/services
- Addons - get information about droppoints / timeslots & pickuplockers
- Config - information about the current configuration on the actor
-
How to authenticate
Follow the steps below to generate the access token which is needed on every request you send to the ShipmentServer API.
Requirements:
- You need the Owner user of the account
- You need the id {ActorId} for the account you want to create requests on
-
1. Generate the client_id & client_secret
The client_id and client_screct is generated by following these steps
- Login to www.consignorportal.com with your Owner user
- Click on your username in the top right corner and select Settings
- In the menu to the right select Clients under API Configuration and click on the Add button
- Give the new entry a Display Name and a Description
- Make sure to that the Enable checkbox is checked
- Set the Allowed Scope to Shipment Server (public_api_shipmentserver)
- Save the client_id and client_secret somewhere save
See this article for more information
-
2. Request an access_token using the client_id and client_secret
Example on how to request a new access token using CURL
curl -s -X POST "https://www.consignorportal.com/idsrv/connect/token"
--header "Content-Type: application/x-www-form-urlencoded"
--data-urlencode "grant_type=client_credentials"
--data-urlencode "client_id=<YOUR_OWN_ID>"
--data-urlencode "client_secret=<YOUR_OWN_SECRET>"
- The Token is valid for 60 minuts before it expires and you have to re-authenticate
- You do not re-authenticate for each request, you should save it and reuse it from a cache
Response
{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjI3QjA1ODk4Nzc1OEUwMkMI1NiIsInR2...",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "public_api_shipmentserver"
}
-
3. Using the access token in a request
In order to get access to the ShipmentServer API
The access_token has to be added to the header on all requests.
{"Authentication": "Bearer <access_tolen>"}
Example on how to use the header in a CURL request
curl -s -X {MethodType} "{URL}/ShipServer/{ActorId}/{Method}"
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjI..."
-H "Content-Type: application/json"
Alternatively, you could also save the header information in a file.
authentication-configuration-64.txt
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjI...
Content-Type: application/json
And point to this file in the CURL request
curl -s -X {MethodType} "{URL}/ShipServer/{ActorId}/{Method}"
-H "@c:\\temp\\authentication-configuration-64.txt"
How to construct a request-
-
Using an account in the production or test environment
To use an account on one of the environments
- Change the {URL} and {ActorId}
- Apply the <access_token> in the authorization header.
- Change the {MethodType} and {Method} to the type of action you want to perform on the API
Production URL | https://api.shipmentserver.com | Swagger |
Test URL | http://demo.shipmentserver.com:8080 | Swagger |
curl -s -X {MethodType} "{URL}/ShipServer/{ActorId}/{Method}"
-H "Authorization: Bearer <access_token>"
-H "Content-Type: application/json"
--data-raw "{
\"data\": {},
\"options\": {}
}"
-
Using the default test account in the test environment
If you want to try the out the API you can use the Test Account with the Id 64
This account can be used with the Authentication type: Basic
Example on how to return all available services using curl
curl -s -X GET "http://demo.shipmentserver.com:8080/ShipServer/64/Products"
-H "Authorization: Basic dW46cHc="
-H "Content-Type: application/json"
You can also use the Swagger UI located here: http://demo.shipmentserver.com:8080/index.html
-
How to use CURL examples
Why do the CRUL examples change format when i click on them?
To use the CURL example in the Command Promt (CMD) you need to paste the examples without any line breaks.
C:\Users\WDAGUtilityAccount>curl -s -X GET "http://demo.shipmentserver.com:8080/ShipServer/64/Products" -H "Authorization: Basic dW46cHc=" -H "Content-Type: application/json" --data-raw "{ data: {}, options: {} }"
But if you need to edit the request in Notepad++ it's not useful to have the example as a single line
Hint: In Notepad++ press CTRL+J when you have a selection of lines to convert them to a single line
CURL options: [-s: only return data, -v: used when debugging, -X: request type]
All snippets are tested using the curl version 7.79.1 on Windows
Methods on the API
-
Shipments
POST | .../SaveShipment | Save a shipment to inbox |
POST | .../Shipments | Submit a shipment |
POST | .../ImportUpload | Import a shipment using a flat file |
POST | .../OrderAdvice | Save a shipment using shipping rules |
POST | .../SubmitOrder | Submit a shipment from inbox |
POST | .../Orders | Store an order in the order database |
POST | .../Shipments/LabelReprint | Reprint labels |
GET | .../Shipments/{ShipmentTag} | Return a shipment |
DEL | .../Shipments/{ShipmentTag} | Delete a shipment |
GET | .../Shipments/{ShipmentTag}/Documents | Return documents from a shipment |
GET | .../Shipments/{ShipmentTag}/DocumentLists | Return a list of documents from a shipment |
GET | .../Shipments/{ShipmentTag}/TrackingURL | Return track & trace information |
PATCH | .../Shipments/{ShipmentTag}/Details | Update details on a shipment |
POST | .../Shipments/{ShipmentTag}/Lines | Create a new goodsline |
PATCH | .../Shipments/{ShipmentTag}/Lines/{LineTag} | Update a goodsline |
DEL | .../Shipments/{ShipmentTag}/Lines/{LineTag} | Delete a goodsline |
DEL | .../Shipments/{ShipmentTag}/Packages/{PackageTag} | Delete a package |
-
Stacks
GET | .../Stacks | Return all stacks |
POST | .../Stacks | Create a new stack |
DEL | .../Stacks/{StackID} | Delete a stack |
PUT | .../Stacks/{StackID}/Manifest | Transmit all shipments on a stack |
PUT | .../Shipments/Manifest | Transmit one or multiple shipments |
POST | .../Stacks/Shipments | Get shipments from a stack |
PATCH | .../Stacks/Shipments | Move shipments to another stack |
-
Batches
GET | .../Batches/{BatchID} | Return a batch using the id |
-
Services
GET | .../Products | Return all services |
POST | .../ShipAdvises | Return services based on shipping rules |
POST | .../ShipmentPrice | Return the freight cost for a service |
POST | .../ShipmentValidations | Validate a service |
POST | .../ValidRoutes | Validate addresses on a service |
POST | .../Shipments/Default | Return default value for the service |
-
Addons
POST | .../DropPoints | Return droppoints for a services |
POST | .../DropPointIDs/{DropPoinID} | Return the address of one droppoint |
POST | .../PickupLockers | Return a list of pickuplockers |
POST | .../PickupLockerAllocations | Allocate a pickuplocker |
POST | .../TimeSlots | Return a list of time slots |
POST | .../TimeSlotAllocations | Allocate a time slot |
POST | .../VoidTimeSlot | Cancel a time slot |
-
Config
GET | .../SenderAddress | Return the preconfigured sender address |
GET | .../AvailableServices | Return services and configuration |
-
.../SaveShipment
Used to save a shipment to Inbox
- Normally used when the shipment is being completed using the Ticket UI
Request
POST /ShipServer/{ActorID}/SaveShipment
- ActorID - the id of the actor to run the request agaist
Example ( using the default test environment )
curl -s -X POST "http://demo.shipmentserver.com:8080/ShipServer/64/SaveShipment"
-H "Authorization: Basic dW46cHc="
-H "Content-Type: application/json"
--data-raw "{
\"data\": {
\"ProdConceptID\": 1782,
\"OrderNo\": \"Test Shipment 1\",
\"Addresses\": [{
\"Kind\": 1,
\"Name1\": \"Test Receiver Name1\",
\"Street1\": \"Test Road 1\",
\"PostCode\": 22222,
\"City\": \"SE\",
\"CountryCode\": \"SE\",
\"Phone\": \"12341234\",
\"Mobile\": \"12341234\",
\"Email\": \"noreply@nshift.com\",
\"Attention\": \"Test Attention\"
}],
\"Lines\":[{
\"Number\": 1,
\"PkgWeight\": 10000,
\"Height\": 100,
\"Length\": 100,
\"Width\": 100,
\"GoodsTypeKey1\": 13,
\"References\": [{
\"Kind\": 23,
\"Value\": \"Test Shipment - Do not process !\"
}]
}]
},
\"options\": { \"Place\": \"Inbox\" }
}"
Request body
The request body takes a shipment data and a options object
{ "data": { "ProdConceptID": INT,
"Addresses": "ARRAY,
"Lines": "ARRAY",
"References": "ARRAY",
"Services: "ARRAY" }, "options": {
"Place": "STRING",
"ServiceLevel": "STRING" } }
Data
See the section here
Options
- Place - where to save the shipment possible values: Inbox | Draft
- ServiceLevel - name of a ServiceLevel to execute in Shipping Rules
-
.../Shipments
Submits a shipment with or without the usage of Shipping Rules
- The most common way to create Shipments on the API
- Labels can be printed using Drop Zone and Cloud Print or return as a base64 string
- Recommended Label format is ZPLGK, PNG or PDF
Request
POST /ShipServer/{ActorID}/Shipments
- ActorID - the id of the actor to run the request agaist
Example ( using the default test actor on the test environment )
curl -s -X POST "http://demo.shipmentserver.com:8080/ShipServer/64/Shipments"
-H "Authorization: Basic dW46cHc="
-H "Content-Type: application/json"
--data-raw "{
\"data\": {
\"ProdConceptID\": 1782,
\"OrderNo\": \"Test Shipment 1\",
\"Addresses\": [{
\"Kind\": 1,
\"Name1\": \"Test Receiver Name1\",
\"Street1\": \"Test Road 1\",
\"PostCode\": 7400,
\"City\": \"Herning\",
\"CountryCode\": \"DK\",
\"Phone\": \"12341234\",
\"Mobile\": \"12341234\",
\"Email\": \"noreply@nshift.com\",
\"Attention\": \"Test Attention\"
}],
\"Lines\":[{
\"Number\": 1,
\"PkgWeight\": 10000,
\"Height\": 100,
\"Length\": 100,
\"Width\": 100,
\"GoodsTypeID\": 13,
\"References\": [{
\"Kind\": 23,
\"Value\": \"Test Shipment - Do not process !\"
}]
}]
},
\"options\": { \"Labels\": \"ZPLGK\" }
}"
Request body
The request body takes a data and a options object
{ "data": {
"ProdConceptID": INT, "Addresses": "ARRAY, "Lines": "ARRAY",
"References": "ARRAY",
"Services: "ARRAY" }, "options": {
"Labels": "STRING",
"TicketUserName": "STRING",
"WorkstationID": "UUID",
"DropZoneLabelPrinterKey": "STRING",
"DropZoneDocPrinterKey": "STRING",
"UseShippingRules": "INT (0/1)",
"ServiceLevel": "STRING",
"RerunCSROnError": "INT (0/1)",
"Token": "STRING",
"ReturnShipment": "INT (0/1)",
"PriceCalculation": "INT (0/1)" } }
See the section here
Options
- Labels - the label type to generate, more information here
ZPL, ZPLGK, EPL, PNG, PDF, DATAMAXLP2, DATAMAXDPL, none
- - TicketUserName - login name used in the DropZone client
- WorkstationID - id of the installed DropZone client
- DropZoneLabelPrinterKey - name of a label printer key defined in the DropZone client
- DropZoneDocPrinterKey - name of a a4 printer key defined in the DropZone client
- - UseShippingRules - use 1 to activate Shipping Rules
- ServiceLevel - name of a ServiceLevel to execute in Shipping Rule
- - Token - a token found in the response of method GetShipAdvise which describes the product to create the shipment with
- RerunCSROnError - use 1 to rerun CSR if the product specified in the token is no longer valid
- - ReturnShipment - creates a return shipment in addition to the other shipment.
- PriceCalculation - use 1 to get price back from Price Calculation Setup Item
Example on how to contruct the JSON when creating a Bring Parcels with the Services eAdvising and Optional DropPoint from NO to SE
https://nshift.zendesk.com/hc/article_attachments/4405279960220/post_shipments_example_1.txt
-
.../ImportUpload
This method allow you to upload a file
- txt, csv, edi or custom
- xml is also supported, but a (XSLT version 1) stylesheet is required in order to translate the file into a CSV file.
before it can be processed.
Request
POST /ShipServer/{ActorID}/ImportUpload
- ActorID - the id of the actor to run the request agaist
Example CSV or TXT ( using the default test environment )
curl -s -X POST "http://demo.shipmentserver.com:8080/ShipServer/64/ImportUpload"
-H "Authorization: Basic dW46cHc="
-H "Content-Type: application/json"
--data-raw "{
\"data\": {
\"filename\":\"test.csv\",
\"filecontent\":\"SGVhZGVyTGluZTtTaGlDYXJyaWVyQ29kZTtSZWZPcmRlck51bWJlcjtBZHJOYW1lMTtBZHJBZGRyZXNzMTtBZHJQb3N0Tm87QWRyQ2l0eTtBZHJTdGF0ZTtBZHJDb3VudHJ5O0Fkck1vYmlsZTtBZHJFbWFpbDtBZHJBdHRlbnRpb247TE51bWJlcjtMV2VpZ2h0O0xIZWlnaHQ7TExlbmd0aDtMV2lkdGg7SW1wb3J0U2VydmljZXM7TEdvb2RzVHlwZQ0KO0dlbmVyaWMxO1Rlc3QgeDEyMztUZXN0IFJlY2VpdmVyIE5hbWUxO1Rlc3QgUm9hZCAxOzc0MDA7SGVybmluZzs7REs7MTIzNDEyMzQ7bm9yZXBseUBuc2hpZnQuY29tO1Rlc3QgUmVjZWl2ZXIgQXR0OzE7MTsxMjA7MTMwOzE0MDtTZXJ2aWNlMSBTZXJ2aWNlMiBFWFc7SFBM\"
},
\"options\": {
\"Labels\":\"ZPLGK\"
}
}"
filecontent before it has been base64 encoded
HeaderLine;ShiCarrierCode;RefOrderNumber;AdrName1;AdrAddress1;AdrPostNo;AdrCity;AdrState;AdrCountry;AdrMobile;AdrEmail;AdrAttention;LNumber;LWeight;LHeight;LLength;LWidth;ImportServices;LGoodsType
;Generic1;Test x123;Test Receiver Name1;Test Road 1;7400;Herning;;DK;12341234;noreply@nshift.com;Test Receiver Att;1;1;120;130;140;Service1, Service2;HPL
Request body
The request body takes a shipment data and a options object
{
"data": {
"filename": "STRING",
"filecontent": "BASE64 ENCODED STRING"
},
"options": {
"Labels": "STRING",
"ImportOnLocation": "INT (0/1)",
"TicketUserName": "STRING",
"WorkstationID": "UUID"
}
}
Data
- filename - name and extention of the file
- filecontent - the content of the file to be uploaded, encoded in base64
Options
- Labels - the label type to generate, more information here
ZPL, ZPLGK, EPL, PNG, PDF, DATAMAXLP2, DATAMAXDPL, none
- - ImportOnLocation - target the Setup Item - Import Setup on Actor (0) or Location (1)
- TicketUserName - login name used in the DropZone client
- WorkstationID - uuid of the installed DropZone client
Example using an Import Setup configured on Actor level
https://nshift.zendesk.com/hc/article_attachments/4405346019868/post_importupload_example_1.txt
-
.../OrderAdvice
Saves a shipment using Shipping Rules (CSR) and ETA web service to Inbox.
- To use this method, you must have Shipping Rules configured for the actor
- To use the Required Delivery Date feature, you also need to have configured ETA.
Request
POST /ShipServer/{ActorID}/OrderAdvice
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data and a options object
{ "data": { "Addresses": "ARRAY, "Lines": "ARRAY" }, "options": {
"ServiceLevel": "STRING",
"RequiredDeliveryDate": "DATETIME", //YYYY-MM-DD
"Visibility": "STRING"
"Submit": INT (0/1),
"Labels": "STRING",
"TicketUserName": "STRING",
"WorkstationID": "UUID",
"DropZoneLabelPrinterKey": "STRING",
"DropZoneDocPrinterKey": "STRING",
"ValidatePostCode": INT (0/1) } }
Data
See the section here
Options
- ServiceLevel - name of a ServiceLevel to execute in Shipping Rules
- RequiredDeliveryDate - the eta of when the shipment should be delivered YYYY-MM-DD
- ValidatePostCode - use 0 to disable PostCode validation
- Visibility - use the value "extended" to return product and carrier name in the response
- - Submit - create the shipment instead of saving it to Inbox
- Labels - the label type to generate, more information here
ZPL, ZPLGK, EPL, PNG, PDF, DATAMAXLP2, DATAMAXDPL, none
- - TicketUserName - login name used in the DropZone client
- WorkstationID - id of the installed DropZone client
- DropZoneLabelPrinterKey - name of a label printer key defined in the DropZone client
- DropZoneDocPrinterKey - name of a a4 printer key defined in the DropZone client
-
.../SubmitOrder
Submits an existing order which has been created using the OrderAdvice method
- Can also creates a return label
- Cloud Print can be used to prints the labels on a certain workstation.
- CSR can be executed again without calling ETA Web Service. If the ServiceLevel is specified and different from OrderAdvice,
Request
POST /ShipServer/{ActorID}/SubmitOrder
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data and a options object
{ "data": { "ShpCSID": "INT", "OrderNo": "STRING",
"Lines": "ARRAY",
"DetailGroups": "ARRAY" }, "options": {
"Labels": "STRING"
"TicketUserName": "STRING"
"WorkstationID": "UUID"
"UseCopy": "STRING"
"UseShippingRules": "STRING"
"ReturnShipmentServiceLevel": "STRING"
"ReturnShipmentFirst": "STRING"
"Vibility": "STRING" } }
Data
See the section here
Any keys provided besides the ShpCSID and OrderNo will be used to update the shipment.
E.g. if the weight have been change since the shipment was created using the OrderAdvice method
Options
- Labels - the label type to generate, more information here
ZPL, ZPLGK, EPL, PNG, PDF, DATAMAXLP2, DATAMAXDPL, none - TicketUserName - login name used in the DropZone client
- WorkstationID - id of the installed DropZone client
- UseCopy - use 1 to keep the original shipment in inbox
- - UseShippingRules - enable Shipping Rules on the request
- ServiceLevel - name of a ServiceLevel to execute in Shipping Rules
- - ReturnShipmentServiceLevel - if a return label is needed, add the name of the ServiceLevel which contain the return products
- ReturnShipmentFirst - use 1 if the return label needs to be printed first
- -
- Visibility - use the value "extended" to return product and carrier name in the response
-
.../Orders
Store part of a shipment in the Orders storage service.
- The shipment in the Order database is completed using .../Shipment or .../ImportUpload
Request
POST /ShipServer/{ActorID}/Orders
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data and a options object
{ "data": { "Addresses": "ARRAY", "Lines": "ARRAY" }, "options": {
"OrderID": "STRING" } }
Data
See the section here
Options
- OrderID - Uuid or another unique string.
-
.../Shipments/LabelReprint
Used to reprint a shipment which has been submitted
- Use the same label format as when it was submitted.
Request
POST /ShipServer/{ActorID}/Shipments/LabelReprint
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data and a options object
{ "data": { "ShpCSID": "INT", "PkgCSID": "INT" }, "options": {
"Labels": "STRING",
"TicketUserName": "STRING",
"WorkstationID": "UUID",
"DropZoneLabelPrinterKey": "STRING",
"DropZoneDocPrinterKey": "STRING", } }
Data
- ShpCSID - the id of the shipment
- PkgCSID - the id of the package ( not required )
Options
- Labels - the label type to generate, more information here
ZPL, ZPLGK, EPL, PNG, PDF, DATAMAXLP2, DATAMAXDPL, none
- - TicketUserName - login name used in the DropZone client
- WorkstationID - id of the installed DropZone client
- DropZoneLabelPrinterKey - name of a label printer key defined in the DropZone client
- DropZoneDocPrinterKey - name of a a4 printer key defined in the DropZone client
-
.../Shipments/{ShipmentTag}
Used to return a shipment which has not been deleted.
Request
GET /ShipServer/{ActorID}/Shipments/{ShipmentTag}
- ActorID - the id of the actor to run the request agaist
- ShipmentTag - both the ShpTag or ShpCSID can be used here
-
.../Shipments/{ShipmentTag}
Used to delete a shipment which has not yet been transmitted.
Request
DELETE /ShipServer/{ActorID}/Shipments/{ShipmentTag}
- ActorID - the id of the actor to run the request agaist
- ShipmentTag - both the ShpTag or ShpCSID can be used here
-
.../Shipments/{ShipmentTag}/Documents
This method documents is used to return a list of all documents encoded as base64 on a shipment.
Request
GET /ShipServer/{ActorID}/Shipments/{ShipmentTag}/Documents
- ActorID - the id of the actor to run the request agaist
- ShipmentTag - both the ShpTag or ShpCSID can be used here
Example ( using the default test actor on the test environment )
curl -s -X GET "http://demo.shipmentserver.com:8080/ShipServer/64/Shipments/6AD32347-5EC5-4AEA-A6DD-7F8E60B06C3F/Documents"
-H "Authorization: Basic dW46cHc="
-H "Content-Type: application/json"
-
.../Shipments/{ShipmentTag}/DocumentLists
This method documents is used to return a list of all documents on a shipment.
Request
GET /ShipServer/{ActorID}/Shipments/{ShipmentTag}/DocumentLists
- ActorID - the id of the actor to run the request agaist
- ShipmentTag - both the ShpTag or ShpCSID can be used here
Example ( using the default test actor on the test environment )
curl -s -X GET "http://demo.shipmentserver.com:8080/ShipServer/64/Shipments/6AD32347-5EC5-4AEA-A6DD-7F8E60B06C3F/DocumentLists"
-H "Authorization: Basic dW46cHc="
-H "Content-Type: application/json"
-
.../Shipments/{ShipmentTag}/TrackingURL
Return the Tracking URL for a shipment
- If the carrier do not support track and trace, a link to Consignorportal.com can be returned instead.
Request
GET /ShipServer/{ActorID}/Shipments/{ShipmentTag}/TrackingURL
- ActorID - the id of the actor to run the request agaist
- ShipmentTag - the ID or Tag of the Shipment
-
.../Shipments/{ShipmentTag}/Details
Used to update details on a shipment
Request
PATCH /ShipServer/{ActorID}/Shipments/{ShipmentTag}/Details
- ActorID - the id of the actor to run the request agaist
- ShipmentTag - the ID or Tag of the Shipment
Request body
The request body require a shipment data containing the details
{
"data": {
"DetailGroups": [{
"GroupID": 1,
"GroupDisplayName": "Article Info",
"Rows": [ CustomsArticleInfoObject ]
}, {
"GroupID": 2,
"GroupDisplayName": "Customs Info",
"Details": [ CustomsInfoObject ]
}
]
},
"options": { }
}
Example
https://nshift.zendesk.com/hc/article_attachments/4405705836700/post_details_example_1.json
-
.../Shipments/{ShipmentTag}/Lines
Add a goodsline to an existing shipment
Request
POST /ShipServer/{ActorID}/Shipments/{ShipmentTag}/Lines
- ActorID - the id of the actor to run the request agaist
- ShipmentTag - the ID or Tag of the Shipment
Request body
The request body require a data object with a Lines Array
{ "data": { "Lines": [ LineObject ] }, "options": {} }
-
.../Shipments/{ShipmentTag}/Lines/{LineTag}
Used to update a goodsline
Request
PATCH /ShipServer/{ActorID}/{ShipmentTag}/Lines/{LineTag}
- ActorID - the id of the actor to run the request agaist
- ShipmentTag - the ID or Tag of the Shipment
- LineTag- the Tag of the line
Request body
The request body require a data object with a Lines Array
{ "data": { "Lines": [ LineObject ] }, "options": {} }
-
.../Shipments/{ShipmentTag}/Lines/{LineTag}
Used to delete a goodsline
Request
DELETE /ShipServer/{ActorID}/Shipments/{ShipmentTag}/Lines/{LineTag}
- ActorID - the id of the actor to run the request agaist
- ShipmentTag - the ID or Tag of the Shipment
- LineTag- the Tag of the line
-
.../Shipments/{ShipmentTag}/Packages/{PackageTag}
Used to delete a package on a goodsline
Request
DELETE /ShipServer/{ActorID}/Shipments/{ShipmentTag}/Packages/{PackageTag}
- ActorID - the id of the actor to run the request agaist
- ShipmentTag - the ID or Tag of the Shipment
- PackageTag- the Tag of the package
-
.../Stack
Return all stacks
Request
GET /ShipServer/{ActorID}/Stacks
- ActorID - the id of the actor to run the request agaist
Request body
The request body is not used
-
.../Stack
Create a new stack
Request
POST /ShipServer/{ActorID}/Stacks
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data and a options object
{
"data": {
"SubcarrierCSID": "INT",
"SubcarrierConceptID": "INT",
"StackName": "STRING"
},
"options": {}
}
Data
- SubcarrierCSID - where to create the stack
- SubcarrierConceptID - where to create the stack
- StackName - name of the stack
-
.../Stacks/{StackID}
Delete a stack
Request
DEL /ShipServer/{ActorID}/Stacks/{StackID}
- ActorID - the id of the actor to run the request agaist
- StackID - the id of the stack to delete
-
.../Stacks/{StackID}/Manifest
Transmit all shipments on a stack
Request
POST /ShipServer/{ActorID}/Stacks/{StackID}/Manifest
- ActorID - the id of the actor to run the request agaist
- StackID - the id of the stack to delete
-
.../Shipments/Manifest
This method will only transmit the specified shipment(s) within a stack.
Request
PUT /ShipServer/{ActorID}/Shipments/Manifest
- ActorID - the id of the actor to run the request against
Request body
The request body takes an Array of ShpCSID
{ "data": {
"ShipmentCSIDs": "ARRAY"
}, "options": {} }
Example
{
"data": {
"ShipmentCSIDs": [123, 124]
},
"options": {}
}
-
.../Stacks/Shipments
Get shipments from a stack
Request
POST /ShipServer/{ActorID}/Stacks/Shipments
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a data object with the stack id
{
"data": {
"StackCSID": "INT"
},
"options": {}
}
Data
- StackCSID - the id of the stack
-
.../Stacks/Shipments
Move Shipments from one Stack to another
Request
Patch /ShipServer/{ActorID}/Stacks/Shipments
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data and a options object
{
"data": {
"StackCSID": "INT",
"ShpCSID": "ARRAY"
},
"options": {}
}
Data
- StackCSID - id of the target stack
- ShpCSID - Id or Tag of the shipment(s) to move
-
.../Batches/{BatchID}
Return a batch using the id
Request
GET /ShipServer/{ActorID}/Batches/{BatchID}
- ActorID - the id of the actor to run the request agaist
- BatchID - the id of the actor to run the request agaist
-
.../Products
Return all services
Request
GET /ShipServer/{ActorID}/Products
- ActorID - the id of the actor to run the request agaist
Example
https://nshift.zendesk.com/hc/article_attachments/4407229470236/get_products_example1.txt
-
.../ShipAdvises
Get advises on which products can be used based on the data object in the payload.
- Normally used on the checkout page in a webshop
- Shipping Rules contain the logic on which products should be returned
- Can also use Carrier Performance (ETA) to display expected delivery time
Request
POST /ShipServer/{ActorID}/shipAdvises
- ActorID - the id of the actor to run the request against
Request body
The request body takes a shipment data and a options object.
{
"data": { "Addresses": "ARRAY, "Lines": "ARRAY" }, "options": {
"ServiceLevel": "STRING", "Price": "STRING", "TimeSlots": "INT", "DropPoints": "INT", "DropPointCount": "INT", "PickupLockers": "INT", "EarliestPickup": "DATE", "RequiredDeliveryDate": "DATETIME", "Deliverydate": "STRING" } }
Data
See the section here
Options
- ServiceLevel - name of a ServiceLevel to execute in Shipping Rules
- Price - Use value "CSR" to get price from CSR, or "1" or "2" to get Price1 or Price2
- TimeSlots - Use value 1 to activate TimeSlots
Read the TimeSlots article to get more information on how to create a Shipment using TimeSlots - DropPoints - Use value 1 to get DropPoints
- DropPointCount - Numer of drop points to return for each product
- PickupLockers - Use value 1 for carriers who support this
- EarliestPickup - Set the earliest time for carrier to pick up the shipment
- RequiredDeliveryDate - YYYYMMDD
- Deliverydate - "ETAWS"
-
.../ShipmentPrice
Return the freight cost for a service
Request
POST /ShipServer/{ActorID}/OrderAdvice
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data object
{ "data": {
"ProdConceptID": "INT", "Addresses": "ARRAY", "Lines": "ARRAY" }, "options": { } }
Example
https://nshift.zendesk.com/hc/article_attachments/4407194562972/post_shipmentprice_example1.txt
Data
See the section here
-
.../ShipmentValidations
Validate a service using local validationrules
Request
POST /ShipServer/{ActorID}/ShipmentValidations
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data object
{ "data": {
"ProdConceptID": "INT", "Addresses": "ARRAY", "Lines": "ARRAY" }, "options": {
}
}
Data
See the section here
-
.../ValidRoutes
Validate addresses on a service
Request
POST /ShipServer/{ActorID}/ValidRoutes
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data object
{ "data": {
"ProdConceptID": "INT", "Addresses": "ARRAY", },
"options": {
} }
Example
https://nshift.zendesk.com/hc/article_attachments/4407222951708/post_validroutes_example1.txt
Data
See the section here
-
.../Shipments/Default
Return default value ( Setup Items ) for the service
Request
POST /ShipServer/{ActorID}/Shipments/Default
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data and a options object
{
"data": {
"ProdConceptID": "INT"
},
"options": {
}
}
Example
https://nshift.zendesk.com/hc/article_attachments/4407242774684/post_shipments_default_example1.txt
-
.../DropPoints
Retrun a list of DropPoints
- The result can be added to the Addresses Array on the Shipment Object as AddressKind 10
Request
POST /ShipServer/{ActorID}/DropPoints
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data and a options object
{ "data": {
"ProdConceptID": "INT",
"ResultCount": "INT", "Addresses": "ARRAY" }, "options": {} }
Example on how to request DropPoints on Bring Parcels, in this case a service id is required.
https://nshift.zendesk.com/hc/article_attachments/4405348200988/post_droppoints_example_1.txt
Data
- ProdConceptID - id of the product
- ResultCount - amount of DropPoints to retrieve 1-10
- Addresses - address of the receiver
- Services - some products require a service to support droppoints
-
.../DropPointIDs/{DropPoinID}
Return the address of a droppoint
Request
POST /ShipServer/{ActorID}/DropPointIDs/{DropPoinID}
- ActorID - the id of the actor to run the request agaist
- DropPointID - the id of the DropPoint to get the address of
Request body
The request body requires a shipment data object
{ "data": {
"ProdConceptID": "INT", "Addresses": "ARRAY", "Lines": "ARRAY",
"Services: "ARRAY" }, "options": {
} }
Data See the section here
Options Not used on this request |
Example #1
|
- |
-
.../PickupLockers
Returns a list of PickupLockers from a service
Request
POST /ShipServer/{ActorID}/PickupLockers
- ActorID - the id of the actor to run the request agaist
Request body
The request body requires a shipment data object
{ "data": {
"ProdConceptID: "INT", "Addresses": "ARRAY", "Lines": "ARRAY" }, "options": { } }
Data See the section here
Options Not used on this request |
|
Example #1
|
Example including the response:
https://nshift.zendesk.com/hc/article_attachments/4407713393692/post_pickuplockers_instaboxV3_example1.txt
-
.../PickupLockerAllocations
Allocate a PickupLocker
Request
POST /ShipServer/{ActorID}/PickupLockerAllocations
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data and a options object
{ "data": {}, "options": {} }
Data
Options
-
.../TimeSlots
Return a list of time slots
Request
POST /ShipServer/{ActorID}/TimeSlots
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data and a options object
{ "data": {
"ProdConceptID": "INT", "Addresses": "ARRAY", "Lines": "ARRAY" }, "options": {
"EarliestPickup": "DATETIME"
"LatestPickup": "DATETIME" }
}
Data See the section here
Options
|
|
Example #1
|
-
.../TimeSlotAllocations
Allocate a TimeSlot
Request
POST /ShipServer/{ActorID}/TimeSlotAllocations
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data and a options object
{ "data": {}, "options": {} }
Data
Options
-
.../VoidTimeSlot
Cancel a booked TimeSlot
Request
POST /ShipServer/{ActorID}/VoidTimeSlot
- ActorID - the id of the actor to run the request agaist
Request body
The request body takes a shipment data and a options object
{ "data": {}, "options": {} }
Data
Options
-
.../SenderAddress
Get the default sender address ( if configured on the actor )
Request
GET /ShipServer/{ActorID}/SenderAddress
- ActorID - the id of the actor to run the request agaist
-
.../AvailableServices
Return configurations for services on the actor
Request
POST /ShipServer/{ActorID}/AvailableServices
- ActorID - the id of the actor to run the request agaist
-
Labels
Information about the label format:
- All label types are encoded as Base64.
- none will not return any label but creates the shipment.
- PNG labels in PNG format.
- PDF labels in PDF format.
- EPL labels in EPL format for printers that are supporting this e.g. LP2844, ZM400 and GK420D.
- ZPL labels in ZPL format but will have a margin of 30 on top of the label. This label type is optimized for LP2844-Z printers and may print too far down on the label for other printers, if this issue occurs try the ZPLGK type.
- ZPLGK is also in ZPL II format but without the top margin. Supported by printers like GK420D, ZM400 and may also work with other printers that are supporting ZPL II language.
- DATAMAXLP2 label for Datamax printer
- Unicode ( e.g. Cyrillic characters ) are only supported for PNG, PDF and ZPLGK label type.
-
Data Object
Complete documentation for the data object can be found here:
https://helpcenter.nshift.com/hc/en-us/articles/360003165473
Example on the top level keys when defining the shipment object
{
"ProdConceptID": 0, // the id of a service
"OrderNo": "", // an order number
"Addresses": [ AddressObject ], // a list of addresses
"Lines": [ LineObject ], // a list of goodslines
"References": [ ShipmentReferenceKind ], // a list of references
"DetailGroups": [ DetaiGroupObject ], // custom information
"Services": [ AddOnsIds ] // a list of add-ons to activate on a service
}
-
AddressObject
The Kind is what defines the type of address, see the complete list here
The full list of supported keys can be found here
Example of a receiver address
{
"Kind": 1, // 1 = receiver
"Name1": "Test Receiver Name1",
"Street1": "Test Road 1",
"PostCode": "0580",
"City": "Oslo",
"Phone": "12341234",
"Mobile": "12341234",
"Email": "noreply@nshift.com",
"Attention": "Test Attention",
"CountryCode": "NO",
}
Example of a sender address
{
"Kind": 2, // 2 = sender
"Name1": "Test Receiver Name1",
"Street1": "Test Road 1",
"PostCode": "0580",
"City": "Oslo",
"Phone": "12341234",
"Mobile": "12341234",
"Email": "noreply@nshift.com",
"Attention": "Test Attention",
"CountryCode": "NO",
}
Example of a droppoint address
{
"Kind": 10, // 10 = droppoint
"CustNo": 0000000, // DropPoint ID
"Street1": "Test Road 1",
"PostCode": "0580",
"City": "Oslo",
"CountryCode": "NO",
}
-
LineObject
The full list of supported keys can be found here
Example
{
"Number": 1, // number of labels to create on the goodsline
"PkgWeight": 10000, // in gram
"Height": 100, // in mm
"Length": 100, // in mm
"Width": 100, // in mm
"GoodsTypeKey1": "CLL", // the key of the goodstype
"References": [ LineReferenceKind ]
}
-
LineReferenceKind
The full list of supported keys can be found here
Example
[
{ "Kind": 23, "Value": "" }, // Line Content
{ "Kind": 24, "Value": "" }, // Line Marking
{ "Kind": 129, "Value": "" }, // Line Custom field 1
{ "Kind": 225, "Value": "" } // Line Custom field 10
]
-
ShipmentReferenceKind
The full list of supported keys can be found here
Example
[
{ "Kind": 9, "Value": "2022-02-03" }, // Delivery Time
{ "Kind": 63, "Value": "test" }, // Custom Field 1
{ "Kind": 64, "Value": "test" }, // Custom Field 2
{ "Kind": 108, "Value": "2022-02-01T00:00:00" }, // Pickup Start
{ "Kind": 109, "Value": "2022-02-02T04:00:00" }, // Pickup End
{ "Kind": 110, "Value": "2022-02-03T00:00:00" }, // Delivery Start
{ "Kind": 111, "Value": "2022-02-04T00:00:00" } // Delivery End
]
-
DetailGroupObject
Example
{
"DetailGroups": [
{ CustomsArticleInfoObject },
{ CustomsInfoObject },
{ FedExCustomsInformationObject },
{ DHLFilingObject },
{ OrderDataObject }
]
}
-
CustomsArticleInfoObject
Example
{
"GroupID": 1, // Article Info
"Rows": [{
"RowNo": 1, // Row Index
"LineNo": 1, // Link To Line Index + 1
"Details": [
{ "KindID": 5, "Value": "1" }, // No units
{ "KindID": 8, "Value": "KG"}, // Unit of Measure (code)
{ "KindID": 7, "Value": "Item 1" }, // Description of goods
{ "KindID": 4, "Value": "DK" }, // Country of Origin
{ "KindID": 2, "Value": "100,00" }, // Unit Value
{ "KindID": 1, "Value": "123456" }, // Article No
{ "KindID": 18, "Value": "123456" }, // Commodity Code
{ "KindID": 17, "Value": "DKK" }, // Currency
{ "KindID": 10, "Value": "100,00" }, // Total Value
{ "KindID": 9, "Value": "10,00" }, // Total Weight
{ "KindID": 193, "Value": "1" } // Goods Line No
]
}, {
"RowNo": 2, // Row Index
"LineNo": 1, // Link To Line Index + 1
"Details": [
{ "KindID": 5, "Value": "1" }, // No units
{ "KindID": 8, "Value": "KG"}, // Unit of Measure (code)
{ "KindID": 7, "Value": "Item 2" }, // Description of goods
{ "KindID": 4, "Value": "DK" }, // Country of Origin
{ "KindID": 2, "Value": "120,00" }, // Unit Value
{ "KindID": 1, "Value": "123456" }, // Article No
{ "KindID": 18, "Value": "123456" }, // Commodity Code
{ "KindID": 17, "Value": "DKK" }, // Currency
{ "KindID": 10, "Value": "120,00" }, // Total Value
{ "KindID": 9, "Value": "12,00" }, // Total Weight
{ "KindID": 193, "Value": "1" } // Goods Line No
]
}, {
"RowNo": 1, // Row Index
"LineNo": 2, // Link To Line Index + 1
"Details": [
{ "KindID": 5, "Value": "1" }, // No units
{ "KindID": 8, "Value": "KG" }, // Unit of Measure (code)
{ "KindID": 7, "Value": "Some other Item" }, // Description of goods
{ "KindID": 4, "Value": "DK" }, // Country of Origin
{ "KindID": 2, "Value": "100,00" }, // Unit Value
{ "KindID": 1, "Value": "123456" }, // Article No
{ "KindID": 18, "Value": "123456" }, // Commodity Code
{ "KindID": 17, "Value": "DKK" }, // Currency
{ "KindID": 10, "Value": "100,00" }, // Total Value
{ "KindID": 9, "Value": "5,00" }, // Total Weight
{ "KindID": 193, "Value": "2" } // Goods Line No
]
}
]
}
-
CustomsInfoObject
Example
-
FedExCustomsInformationObject
Example
-
DHLFilingObject
Example
-
OrderDataObject
Example