DOCSEARCHbyAlgolia
Submit Docs

instantCMR API Documentation

website·Indexed 31 days ago

https://docs.instantcmr.com

REST API for logistics and transportation management. Includes endpoints for managing trips, user accounts, chat rooms, document storage, and gamification campaigns, along with detailed schemas for transaction processing and custom driver interface menus.

Tokens
30.2K
Snippets
116
Records
191
Agent score
50%

What's inside instantCMR

  1. Overview of instantCMR API capabilities

    The instantCMR API provides programmatic access to logistics and transport management features, allowing external systems to securely manage trips, users, documents, and related data. The API is divided into several functional areas:

    • Trip Management: Handle trip metadata, document requests, stations, and external documents.
    • User Administration: Programmatically manage user accounts (create, update, activate, deactivate) and configure roles and permissions.
    • Communication Tools: Create and manage chat rooms for user communication.
    • Document Management: Handle the upload, download, organization, and deletion of documents and folders in user storage.
    • Transaction Updates: Monitor and receive updates regarding trip statuses, document changes, and user activities.
    • Gamification: Submit and finalize driver performance scores for company campaigns.

  2. Overview of Document Storage API

    The Document Storage API enables the delivery of external documents and files to drivers' mobile devices. Each user account is automatically assigned a document storage. Files are identified by a server-generated unique identifier (filid) and a path (pat).

    Key behaviors:

    • Automatic Folder Creation: Uploading a document to a path automatically creates any missing parent folders.
    • Overwriting: Uploading a document to an existing path replaces the previous document and assigns a new filid.
    • Recursive Deletion: Deleting a folder automatically deletes all nested folders and documents (non-atomic operation).
    • Delivery Receipts: When a file is delivered to a mobile device, a delivery receipt is created in the user's storage containing the delivery date and the filid.

  3. Overview of instantCMR Chat API concepts

    The Chat API manages chat rooms and messages using the following key identifiers and constraints:

    • roomxtid: A client-generated unique identifier for a chat room. Once set, it cannot be changed.
    • userxtid: Unique identifier for instantCMR users (members).
    • postxtid: A client-generated unique identifier for individual messages, used to distinguish between messages with identical content from the same author.
    • etagroom: A hexadecimal sequence number representing the version of the chat room. Used in ETag and If-Match headers to prevent lost updates.
    • etagpost: A hexadecimal sequence number representing the order of a message within a room. It identifies the message and is used in ETag/If-Match headers for message updates.

    Constraints:

    • Chat rooms support up to 100 members.
    • Only members can view a room or post messages.
    • Removing a member removes the room and its messages from that member's list, but messages posted by that member are retained in the room.

  4. Gamification API Overview

    The Gamification system organizes performance data into campaigns, metrics, and scores to run automated driver competitions.

    • Campaigns: Time-bound competitions (e.g., Weekly Eco-Driving Challenge) managed within the Hub; they cannot be modified via API.
    • Metrics: Performance categories (e.g., fuel efficiency). A single metric can be used by multiple campaigns.
    • Scores: Numeric results submitted via API. Each driver can have one score per metric per day. The highest total score in a campaign determines the winner.
    • Hierarchy: Every score is associated with a specific company and a driver within that company.

  5. Manage trip data using the Trip API

    The Trip API is used to manage trip information for drivers, including metadata, document requests, station and task lists, and external documents (e.g., site entry/exit procedures).

    • Retrieve trips: Use GET /v3/igr/trip/{copid}/{tripxtid}.
    • Create or Update trips: Use PUT /v3/igr/trip/{copid}/{tripxtid}.
    • Manage Attachments: Use the rut endpoints (GET rut, PUT rut, DELETE rut) to handle files attached to trips.

  6. Implement internationalization for Custom Menu text

    The app selects translations based on the driver's preferred mobile device language. If multiple languages match, the most preferred locale is used. If no match is found, the default locale translation is used. A translation in the default locale is required.

    For simple implementations where internationalization is not needed, a shorthand string can be used, which is functionally equivalent to an object with the default locale key _.

    // Shorthand syntax (Default locale only)
{
    "ost18Text": "Messages"
}

// Expanded syntax (Internationalized)
{
    "ost18Text": {
        "_": "Messages",
        "hu": "Üzenetek"
    }
}

  7. Update an existing instantCMR user account

    To update a user, send a PUT request to the same URL used for creation (using the same userxtid).

    Critical Constraints:

    1. Concurrency Control: You must provide the current entity version tag in the If-Match: {ETag} header to avoid overwriting updates made by other sources. If the ETag does not match, the API returns 412 PreconditionFailed.
    2. Full Replacement: The request body fully replaces the previous version of the user entity. Any data omitted from the request body will be removed from instantCMR.
    PUT /v3/igr/user/{copid}/{userxtid} HTTP/1.1
Host: api.instantcmr.com
x-icmr-auth-1: {authentication-token}
Content-Type: application/json
If-Match: {ETag}

{usereu}

  8. Manage driver trips through integration

    Trips consist of a list of stations and document requests. While the Hub UI allows data review, trips must be created via API integration. The workflow is: 1. Define the trip (stations, document requests, guides, or route plans). 2. Send a PUT request to the instantCMR backend to create the trip; this synchronizes the data to the driver's mobile phone and notifies them. 3. As the driver completes tasks, Dubtrip entities (containing trip status and submitted items) are added to the message queue. 4. Use the same poll-and-acknowledge process as arbitrary document submissions to sync these updates back to your system.

  9. Position and size widgets using layout coordinates

    Widgets use a density-independent coordinate system to maintain aspect ratio across different screen orientations.

    • X-axis: 9 equi-distant units (shorter edge of screen).
    • Y-axis: 16 equi-distant units (longer edge of screen).
    • Origin (0,0): Top-left corner.
    • Bottom-Right (9,16): Bottom-right corner.
    • Orientation: When switching between portrait and landscape, the system mirrors around the x=y line (mirrored vertically and rotated 90° counterclockwise). A unit of (dx: 1, dy: 1) always represents a square.
    // Widget Position (Ptd)
{ "x": 4, "y": 7.5 }

// Widget Size (Szd)
{ "dx": 4, "dy": 7.5 }

  10. Handle trip attachments and navigable routes

    Each trip has attachment storage for documents and routes.

    • Navigable Routes: Must have the .bcr extension. These appear in the 'Routes' section of the mobile app with a button to launch an external navigation app.
    • General Documents: Any other file type (e.g., .pdf, .jpg, .png). These appear in the 'Incoming documents' section and open via the device's registered mime-type app.

  11. Understand the Trip update (Tripeu) schema

    The Tripeu object is used to send trip updates to the instantCMR API. It shares a similar structure to the Triped response but is designed for requests to modify trip data, including metadata, document requirements, and station details.
    {
    "ouid": "EUT",
    "ktroc": "o",
    "ostSortBy": "0000000",
    "tripmeta": {
        "ostTripCode": "200026571",
        "ostOrderId": "AB2398VBA4",
        "ostAddress": "IT 25011 Calcinato, VIA CAVOUR 149",
        "ostCustomer": "BATHSYSTEM SPA",
        "odtuCreate": "2020-02-27T10:20:23.839Z",
        "ostInstructions": "use 6 ratchet straps",
        "ostNotes": "call upon arrival",
        "ostHaulerPlate": "FM682RK",
        "ostTrailerPlate": "OB462PY"
    },
    "ouserxtidDriver": "494922944810349",
    "rgdocr": [
        {
            "docrid": "qOMjwWEGbysBn8axLPlJ2A",
            "dtuRequest": "2020-02-27T10:20:23.839Z",
            "kdocr": "cmr",
            "ostShortName": "CMR (Calcinato)",
            "ostDesc": "scan all pages",
            "fRequired": true
        }
    ],
    "rgstan": [
        {
            "stanxtid": "geqcQAOxUbkeS-N8jEtJOQ",
            "kstan": "ld",
            "odtu": "2019-12-02T06:30:00.000Z",
            "ostAddress": "IT 25011 Calcinato, VIA CAVOUR 149",
            "ostNotes": "gate code: A678*",
            "okmDistance": 825,
            "ostSortBy": "0000000",
            "cufis": {
                "rgcufi": [
                    {
                        "id": "parking_lot",
                        "n": "Parking Lot",
                        "v": "Lot No. 2"
                    }
                ]
            }
        }
    ],
    "cufis": {
        "rgcufi": [
            {
                "id": "reference_number",
                "n": "Reference Number",
                "v": "202203-DE-19373"
            }
        ]
    }
}

  12. Automate receiving document submissions via API

    When drivers scan documents (CMRs, delivery notes, pallet receipts, etc.), instantCMR creates a Dubdosu entity containing driver metadata, notes, and image links. These entities are placed in a message queue. To automate the export of these submissions into a Transport Management System (TMS), the backend must follow a poll-and-acknowledge pattern: 1. Poll the provided endpoint to retrieve the first few items from the queue. 2. Process the entities and download the images. 3. Send an acknowledgment request to the instantCMR backend to mark the entities as processed and remove them from the queue.