Introduction
For integration purposes there are some APIs that are useful to import data into Plan & Go and also to be able to export.
Security / authentication
For each session, first get authenticated with /pl/api/v-1/auth/generate, then use the received token in the header for all the other calls. Like this:
# Example 1) Posting JSON (when logged in, we send the token in the header)
curl https://planandgo.di.no/pl/api/v-1/routePlan \
-H "Content-Type:application/json" \
-H "X-Auth-Token:olof:5f9a3609a5a295eff861d930a0c75bbee7991842" \
-d "{ \
\"companyId\": 1, \
\"date\": '2015-12-04T00:00:00.000+0100', \
\"name\": \"Utkjoring uke 9\" \
}"
# Example 2) posting FILE (when logged in, we send the token in the header)
curl https://planandgo.di.no/pl/api/v-1/file/999999 \
-H "Content-Type: multipart/form-data" \
-H "X-Auth-Token: olof:5f9a3609a5a295eff861d930a0c75bbee7991842" \
-F file=@my_import_file_in_this_dir.csv
Environments
- DEV: https://dev-planandgo.di.no
- STAGING: https://staging-planandgo.di.no
- PROD: https://planandgo.di.no
API-methods
| # | Endpoint / Description | Example - Request | Example - Response | |
|---|---|---|---|---|
| 1 | POST /pl/api/v-1/auth/generateFetches an login-token that the application can use to gain access to the API. | {
"username": "olof",
"password": "secret123"
}
| {
"token": "olof:5f9...842",
"userId": 23432,
"customerSystemId": 233,
"roles: [...]
}
| |
| 2 | 🔐 | POST /pl/api/v-1/routePlan Create an empty route plan (for a given distribution date). companyId: The ID of the transport company. Ask DI for the correct value(s) to use. | {
companyId: 1,
date: '2015-12-04T00:00:00.000+0100',
name: 'Utkjoring uke 9'
}
| {
id: 344,
date: '2015-12-04T00:00:00.000+0100',
name: 'Utkjoring uke 9',
...
}
|
| 3 | 🔐 | POST /pl/api/v-1/routePlan/<rp_id>/customerSystem/<cs_id> Create an empty file (prepare for a file-upload). Step 1 in file upload. rp_id: The returned routePlanId from previous call. | {
name: 'my-file-name.csv'
}
| {
id: 6722,
name: 'my-file-name.csv',
...
}
|
| 4 | 🔐 | POST /pl/api/v-1/file/<f_id> Upload the content of the file you have prepared. Filetypes supported:
Mimetype: multipart/form-data. Name the file-field: "file". See file specification. Step 2 in file upload. f_id: The returned fileId from previous call. | {
status: 'ok'
}
| |
| 5 | 🔐 | GET /pl/api/v-1/customerSystem/<cs_id>/publishedOrders/<yyyy-mm-dd> Fetch the published orders including the routename of each order. Included for each order is an estimate for WHEN the order will be delivered. It's a time interval like this: HH:MM-HH:MM. This will return orders across many routePlans, but only from published plans for the given distribution-date.
cs_id: Ask DI for the correct value to use (or look at the response from /auth/generate) | List of orders [
{
orderId: '12452',
routeName: 'Asker',
timeWindow: '19:29-21:29'
},
{
orderId: '12454',
routeName: 'Asker',
timeWindow: '19:37-21:37'
},
...
{
orderId: '29452',
routeName: 'Skøyen',
timeWindow: '18:11-20:11'
},
...
]
|
Usage
When the deliveries are ready on your end
- Generate a token for the session
- Repeat these steps for each transport company
- Create an empty routeplan, to get a fresh routePlanId (do this for each area that has it's own starting point)
- Create an empty file, to get a fresh fileId
- Generate a file (using our file-spec) and post it with the fresh fileId. Remember to fill out ORDER_ID (used as key when exporting optimized plans)
- Look for status: 'ok' or handle errors
When the plan is optimized and published - at a agreed time
Generate a token for the session
- Fetch the orders and extract the routename from there (for a given customerSystem and distribution-date)