Planning Receive API

Context

The Planning Receive API is a unified interface where you post your planning to. You should be aware of the format we would expect from you.

Environment

For the Planning Receive API we use the following URIs:

Production URL :
https​://planning-receive-api.services.simacan.com/trips/insertOrUpdate
Staging URL :
https:​//planning-receive-api-stg.services.simacan.com/trips/insertOrUpdate

OTM5 Production URL :
https​://planning-receive-api.services.simacan.com/otm/api/v5/trips
OTM5 Staging URL :
https:​//planning-receive-api-stg.services.simacan.com/otm/api/v5/trips

Example

Sending your planning

As mentioned before, you should have requested your access_token from the Auth API. Next, make sure you are setting the correct headers and request type for the filetype you are sending, so set your Content-Type to one of the following:

Filetype Content-Type Request type
csv text/csv POST
json application/json PUT
xml text/xml POST

Send it

Keep in mind that this request only works, if you have a bearer token and set the correct Content-Type. Include these in the header. The content of the request should be in the body of the message. In this example we post to the staging URL:

csvjsonxml
Copy
Copied
curl 
  --header "Content-Type: text/csv" \
  --header "Authorization: Bearer eyXXX" \
  --data-raw "trip ID,STOP ID,location ID,start time stop,END time stop
1,Stop1,1,2021-01-25T10:00:00+01:00,2021-01-25T10:00:00+01:00
1,Stop2,2,2021-01-25T10:45:00+01:00,2021-01-25T11:00:00+01:00
1,Stop3,1,2021-01-25T11:30:00+01:00,2021-01-25T11:45:00+01:00" \
  --request POST \
  https://planning-receive-api-stg.services.simacan.com/trips/insertOrUpdate
Copy
Copied
curl 
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer eyXXX" \
  --data-raw "{
    \"id\": \"2a8af6c6-e4d5-5dfb-9532-e8b17c3ffd88\",
    \"name\": \"2021-32-2-888\",
    \"externalAttributes\": {},
    \"actors\": [],
    \"actions\": []
    }"
  --request PUT \
  https://planning-receive-api-stg.services.simacan.com/otm/api/v5/trips
Copy
Copied
curl 
  --header "Content-Type: text/xml" \
  --header "Authorization: Bearer eyXXX" \
  --data-raw "YOUR_XML_DATA_HERE" \
  --request POST \
  https://planning-receive-api-stg.services.simacan.com/trips/insertOrUpdate

Response

If everything went fine, you should receive an HTTP status code 200 OK and a body which looks like this

01b44637-1395-4591-a0ec-14108022b707

Great! Your planning has been delivered to our platform. On success you will get the UUID for the specific file you've just sent us. Keep in mind, this is just a confirmation that we received your file. This is not a confirmation that your planning is processing.

To see the status of your delivered file, check the next chapter on the Planning Status API.

Responses

Key Description
200 Ok
401 Unauthorized Whenever you will get a 401 status, you have either provided the wrong credentials or none at all. Check if you bearer token has not expired
403 Forbidden You will receive this status, when you successfully supplied credentials, but your username does not have the necessary permissions for the resource. If you are sure you are using the correct account, please get in touch with us
404 Not Found Whenever you will get a 404, you are probably using a malformed or incorrect URL
415 Unsupported Media File The request's Content-Type is not supported.