Vi har gjennomgått dokumentasjonen av våre APIer og gjort noen endringer/forenklinger. Sjekk ut vår nye API-dokumentasjonen. Nye APIer kan brukes kort etter påsken 2019.
Vi kommer tilbake til dato for når APIene ikke lenger kan brukes.
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+0000', \
\"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. distrNo: A grouping mechanism used to separate different distributions during the day (for the "Customer Plus"-view). Values:
Will be used for:
| {
"companyId": 1,
"date": "2015-12-04T00:00:00.000+0000",
"distrNo": 0,
"name": "Utkjoring uke 9"
}
| {
"id": 344,
"date": "2015-12-04T00:00:00.000+0000",
"distrNo": 0,
"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",
"customerCount": 230,
"deliveryCount": 278
}
| |
| 5 | 🔐 | GET /pl/api/v-1/customerSystem/<cs_id>/publishedOrders/<yyyy-mm-dd> Fetch the published orders including the routename of each order. Also added which pickupLocation the route has. routeId and pickupLocationId is our internal IDs and will be generated for each new distribution date. Use them only for sorting/grouping if you want an integer instead of a string for that. companyId tells you which distribution company is handling the 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 [
{
"companyId": 1,
"orderId": "768787",
"routeName": "Sentrumruten",
"timeWindow": "20:00-23:00",
"estimatedTime": "16:43",
"routeId": 6225,
"pickupLocationId": 988,
"pickupLocationName": "Storgata 11A, 1234 OSLO",
"cancelled": false
},
...
]
| |
| 6 | 🔐 | POST /pl/api/v-1/customerSystem/<cs_id>/purgeOrders Purge personal information (GDPR) based on given ORDER_IDs (within a customerSystem). cs_id: Ask DI for the correct value to use (or look at the response from /auth/generate) | [
{"orderId": "12345"},
{"orderId": "34453"},
{"orderId": "22834"}
]
| List of orders [
{"orderId":"12345","status":"purged"},
{"orderId":"34453","status":"purged"},
{"orderId":"22834","status":"none.found"}
]
|
| 7 | 🔐 | POST /pl/api/v-1/customerSystem/<cs_id>/cancelOrders Cancel orders within a customerSystem. cs_id: Ask DI for the correct value to use (or look at the response from /auth/generate) Each order has a status. Only status cancelled indicates that order was successfully cancelled | [
{"orderId": "12345"},
{"orderId": "34453"},
{"orderId": "22834"},
{"orderId": "22866"}
]
| List of orders [
{"orderId":"12345","status":"cancelled"},
{"orderId":"34453","status":"too.many.found"},
{"orderId":"22834","status":"none.found"},
{"orderId":"22866","status":"too.late"}
]
|
| 8 | 🔐 | POST /pl/api/v-1/customerSystem/<cs_id>/<yyyy-mm-dd>/<orderId>/deliveries Replace the deliveries for an order (within a customerSystem and distrDate). cs_id: Ask DI for the correct value to use (or look at the response from /auth/generate) | [
{"product": "ABC", ... },
{"product": "DEF", ... }
]
Attributes:
| {
"status": "updated"
}
|
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, estimater time etc from there (for a given customerSystem and distribution-date)
When a customer wants to be deleted from your system (GDPR)
- Assumes that you have a full history of the customer's orderIds
- Generate a token for the session
- Call "purgeOrders" given all the customer's orders (for a given customerSystem)