Trip API

Retrieves a trip entity identified by tripxtid.

GET /v3/igr/trip/{copid}/{tripxtid}[?expire={download-url-expiry}][&{deleted}] HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  

HTTP/1.1 200 OK  
Date: Thu, 23 Jan 2020 16:29:47 GMT  
Content-Type: application/json; charset=UTF-8  
ETag: {ETag}  
Content-Length: 1386  

{triped}

Stores a trip entity, optionally replacing any previous entity stored under tripxtid.

Trip entities follow the guidelines of entity versioning. Send an If-None-Match: * header when creating a new trip entity to ensure that no previously existing trip gets overwritten. To update a trip entity, send the request with an If-Match header specifying the last known ETag of the trip entity.

When updating a document request associated with a trip, make sure that it is sent with the same document request id in its docrid field. Note that once a document request has been submitted, updating its document type in its kdocr field is not supported. Doing so will yield a 400 Bad request response. This also applies to deleted document requests.

Please be aware that document requests might also be added into a trip by reviewers using the instantCMR Hub. To ensure that you do not accidentally delete these document requests, make sure that you merge your document request changes with the contents of rgdocr field of the trip entity. I.e. if you want to add a new document request you can perform the addition on the version of the trip entity held in your local cache (the last known state of the trip) and send the modified trip entity in a PUT trip request. If however you receive a 412 PreconditionFailed and then retrieve an updated version of the trip entity, you would need to perform the document request addition again on the updated trip entity before sending a new PUT trip request, otherwise you risk removing document requests added by reviewers from the trip entity.

There is an edge case around deleting document requests (in the field rgdocr). Although document requests omitted in a trip update will be removed from the UI on the mobile app, they will be kept around to allow any documents created by drivers (in response to these requests) to be submitted. The GET trip endpoint provides a way to retrieve these dangling submissions.

The trip status (ktroc) can also be updated by external actors, which might be a change you are unaware of. The driver might change the trip status from open (o) to closed-by-driver (mfc), or the reviewer might change the trip status from closed-by-driver (mfc) to open (o) whenever s/he adds a new required document request to a trip already closed by the driver. Unless you want to explicitly override the trip status with your value, you should simply resend the trip status returned to you from the last GET trip request.

Trips that have at least one required and non-deleted document request that has not yet been fulfilled (i.e. no document has been submitted to fulfill that request) cannot be closed by the driver (mfc). This rule is also enforced by the instantCMR API, meaning that if for any PUT trip request that would violate this rule, the API will override any ktroc value of mfc to o.

This can occur if

• You set ktroc to mfc for a trip that has required document requests that are yet unfulfilled.
• You add a required document request to a trip that already has a ktroc value of mfc.

In both cases the PUT trip request will succeed with a 200 OK response, however the value of ktroc will be set to o (reopening an already closed trip if necessary). The response body returned by the instantCMR API will also reflect this change.

Note, that this rule only applies to trips with a status of closed-by-driver (mfc). Trips can be closed by dispatcher (c) even if not all required document requests have been fulfilled.

PUT /v3/igr/trip/{copid}/{tripxtid}[?expire={download-url-expiry}] HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  
Content-Type: application/json  
[If-Match: {ETag}]  
[If-None-Match: "*"]  
Content-Length: 1779  

{tripeu}

HTTP/1.1 200 OK  
Date: Thu, 23 Jan 2020 16:29:47 GMT  
Content-Type: application/json; charset=UTF-8  
Etag: {ETag} 
Content-Length: 1386  

{triped}

Attach a document or route to a trip and optionally to a station within the trip. Attachments are identified by their path and file name within the trip attachment storage (file-path). Attaching a document to a trip with the same name as a previous document attached to the same trip will overwrite the previous document.

Documents can be either attached to the entire trip or to individual stations of the trip. Documents attached to the trip will be displayed to the drivers on the Details tab of the trip whereas documents attached to a station will be displayed on the Stations tab, next to the individual station they are attached to. To attach a document to the entire trip, upload the document to the root folder of the trip attachment storage (e.g. /route.bcr or /document.pdf). To attach a document to a station , upload the document to a folder named after the stanxtid of the station (e.g. /station-1/route.bcr or /station-1/document.pdf).

PUT /v3/igr/trip/{copid}/{tripxtid}/rut/{file-path}[?expire={download-url-expiry}] HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  
Content-Type: application/octet-stream  
Accept: */*  
Content-Length: 11741  

{document-bytes}

HTTP/1.1 200 OK  
Date: Thu, 23 Jan 2020 16:29:47 GMT  
Content-Type: application/json; charset=UTF-8  
Etag: {ETag} 
Content-Length: 1386  

{triped}

Removes a document from the trip attachment storage.

DELETE /v3/igr/trip/{copid}/{tripxtid}/rut/{file-path}[?expire={download-url-expiry}] HTTP/1.1  
Host: api.instantcmr.com  
x-icmr-auth-1: {authentication-token}  
Content-Type: application/octet-stream  
Accept: */*  

HTTP/1.1 200 OK  
Date: Thu, 23 Jan 2020 16:29:47 GMT  
Content-Type: application/json; charset=UTF-8  
Etag: {ETag} 
Content-Length: 1386  

{triped}

Downloads an attached document from the trip attachment storage.

GET {document-url-path} HTTP/1.1  
Host: {document-url-host}  
x-icmr-auth-1: {authentication-token}  

HTTP/1.1 200 Thank you  
Content-Length: 67676  
Content-Type: image/jpeg  
Etag: "16049243cba368ad9bea03033d6f2fb6"  
Last-Modified: Thu, 23 Nov 2017 21:14:23 GMT  

{document-bytes}