Envase Mobile App Use Cases ############################################################################# This section documents the usage of the Core API for the workflows and use cases required by the |ma|. Other applications might leverage these use cases, but in general they should follow the recommendations in the :doc:`general` section of the documentation. Driver Management ============================================================================= The following sections document use cases related to managing users in the mobile app and associating them with Drivers in a TMS. The individual TMS systems will have their own association for each of the drivers; therefore, the mobile app needs to keep track of that association. .. attention:: As of right now, we don't really understand how Envase TMS is going to manage drivers. The recommendations here are based on Profit Tools TMS; although, we will like to be consistent in the future. There are some assumptions made related to managing users for the mobile app. These assumptions are related to the fact that we don't have user management yet in the |ptga|_. Once user management is implemented, the assumptions will be removed, and the use cases will be updated. For now, we consider each driver signing up with the mobile app to be an employee driver or owner-operator for a single TMS (Profit Tools). Therefore, the TMS will already contain a record for the driver, and the mobile app will need to associate the record with the app user. This will be done through their email address. .. important:: There is a requirement for the driver email address in the TMS to match the address they use to log into the mobile app. .. note:: We are evaluating the requirements for user management, so the implementation will be coming soon after all other requirements for the mobile app have been met. Associate Driver to ID ----------------------------------------------------------------------------- The mobile app signs new user/drivers and their accounts are created. Those accounts reference a TMS instance through the `custom:tms_url` attribute of the user, which allows the requests to the API to be dispatched to the correct TMS system. The created driver account has to be associated with a ``Driver`` in the TMS. The |ptca| exposes a service to manage drivers at ``/drivers``, which supports an ``email`` query parameter to filter the drivers by the specified value. This allows the mobile app to query the driver information for the ``Driver`` that has the specified email. The response will provide information about the matching driver, and one of the attributes returned will be the ``id``, which the mobile app is responsible to associate with the user account. Further requests where a reference to a driver is needed should use the associated id. The following shows the request and response for this workflow: .. code-block:: GET https://core.envaseconnect.cloud/drivers?email=john.smith@fasttransportation.com The response will look like the following: .. code-block:: json { "id": "12345", "self": "/drivers/12345", "email": "john.smith@fasttransportation.com", "firstName": "John", "middleName": "Carl", "lastName": "Smith", "ref": "D100", "status": "ACTIVE", "type": "company-driver", "medicalExpiration": "2029-12-31", "licenseExpiration": "2029-10-15", "hazmatCertified": true, "hazmatExpiration": "2029-05-26" } The mobile app should associate the ``id`` property returned with the current account. .. caution:: The current exposed properties related to license, medical, and hazmat statuses will be removed from the current response and exposed through different APIs related to endorsements and certifications for drivers. Avoid using them for now until all the work is completed. Register New Driver with TMS ----------------------------------------------------------------------------- The mobile app can create a new driver in the customer TMS provided that the driver is a driver employee or owner-operator. Let's say that the app queries the ``/drivers`` with a specific ``email`` and the response returns an empty list of drivers; the app could create a new driver with the information provided by the user during sign-up. .. danger:: The mobile app should be careful to not duplicate a record in the customer TMS. It would be wise to present some confirmation to the user before forcing the creation of the driver, or maybe, allow the user to enter a different email address that matches a record in the customer TMS to do the association. The following shows the request that will be needed to create a new Driver in the customer TMS system: .. code-block:: POST https://core.envaseconnect.cloud/drivers The request payload should have the following schema: .. code-block:: json { "firstName": "John", "middleName": "Peter", "lastName": "Smith", "ref": "D100", "status": "ACTIVE", "type": "company-driver", "medicalExpiration": "2029-12-31", "licenseExpiration": "2029-10-15", "hazmatCertified": true, "hazmatExpiration": "2029-05-26" } The response from the service will return a status of ``201 Created`` and the ``Driver`` object with the assigned id and resource URL: .. code-block:: json { "firstName": "John", "middleName": "Peter", "lastName": "Smith", "ref": "D100", "status": "ACTIVE", "type": "company-driver", "medicalExpiration": "2029-12-31", "licenseExpiration": "2029-10-15", "hazmatCertified": true, "hazmatExpiration": "2029-05-26", "id": "100", "self": "/drivers/100", "email": "jsmith@example.com" } Load Management ============================================================================= The |ma| needs to manage the loads offered to a driver, as well as maintain the work the driver is performing. The following sections document the interaction of the |ma| with the |ptca| to manage loads. Available non-shipment events are: **Event Types** +---------------------+------------------------------------------------------------------------------------+ | Event Type | Description | +=====================+====================================================================================+ || ns-bobtail || The driver arrives at the location with only a tractor. This is only used to | || || signify that the driver drove from a different location with only a tractor. | || || After the event is completed, the driver is still in the tractor. | +---------------------+------------------------------------------------------------------------------------+ || ns-dismount- || A loaded container is removed from a chassis. Before executing the event, the | || container || driver is in a tractor, pulling a chassis with the loaded container on it. After | || || the event is completed, the driver is expected to be in a tractor pulling a bare | || || chassis. The driver leaves the container behind. | +---------------------+------------------------------------------------------------------------------------+ || ns-drop-chassis || The driver arrives at the location pulling a bare chassis. Before this event | || || the driver will have hooked the bare chassis or dismounted a container. | || || After the event is completed, the driver is no longer pulling the chassis. | +---------------------+------------------------------------------------------------------------------------+ || ns-drop-container || The driver arrives at the location with the container and chassis. | || || Before the event, the driver is pulling a loaded or empty container. | || || After the event is completed the driver is no longer pulling equipment and | || || it has been left behind to be unloaded. The empty equipment may be hooked | || || again later. | +---------------------+------------------------------------------------------------------------------------+ || ns-drop-trailer || The driver arrives at the location with a loaded or empty trailer. | || || Before the event, the driver is pulling a loaded or empty trailer. | || || After the event is completed the driver is no longer pulling the trailer. | +---------------------+------------------------------------------------------------------------------------+ || ns-drop-unknown || The driver arrives at the location with an undefined piece of equipment. | || || Before the event, the driver is pulling a bare chassis, mounted container on | || || a chassis, or a trailer loaded equipment. After the event is completed the driver | || || is no longer pulling the equipment. | +---------------------+------------------------------------------------------------------------------------+ || ns-end-trip || The driver arrives at the location in which they are getting getting out of | || || the truck, tractor, or van. After the event is completed, the driver is no longer | || || in the tractor. | +---------------------+------------------------------------------------------------------------------------+ || ns-hook-chassis || The driver hooks a bare chassis on to their tractor. Prior to this event the | || || driver is expected to be driving a tractor that can pull the chassis. After the | || || event is completed the driver is pulling a chassis, and may go mount a container | || || or drop the chassis. | +---------------------+------------------------------------------------------------------------------------+ || ns-hook-container || The driver hooks a container on to their tractor. Prior to this event the | || || driver is expected to be driving equipment that can pull the container. | +---------------------+------------------------------------------------------------------------------------+ || ns-hook-trailer || A driver arrives at a the location and hooks the trailer. Before the event the | || || driver is expected to be driving a tractor that can hook the trailer. After | || || the event is completed the driver is pulling the loaded or empty equipment to | || || another location to be dropped or unloaded. | +---------------------+------------------------------------------------------------------------------------+ || ns-hook-unknown || The driver hooks a piece of equipment that is not yet defined as a container, | || || chassis, or trailer. | +---------------------+------------------------------------------------------------------------------------+ || ns-misc || A driver arrives at a location and performs a miscellaneous event, that is not | || || defined by any of the other events. This could be a break, scale stop, gas stop | || || or other miscellaneous activity. | +---------------------+------------------------------------------------------------------------------------+ || ns-mount-container || A driver arrives at a location with a bare chassis and a container is placed on | || || top of it. Before the event the driver is expected to be pulling a bare chassis | || || that can be mounted with the container. After the event is completed the driver | || || will bring the container to a location where it will be loaded, unloaded, dropped,| || || or dismounted. | +---------------------+------------------------------------------------------------------------------------+ || ns-new-trip || The driver arrives at the location where the tractor, truck, or van is parked | || || and enters the vehicle. Before the event the driver is not assigned any vehicle. | || || After the event is completed, the driver is in the vehicle. This is the start of | || || the trip. | +---------------------+------------------------------------------------------------------------------------+ Available Loads to Driver ----------------------------------------------------------------------------- The loads available to a driver are exposed by the driver plan which is part of the ``drivers`` service. The driver plan is a date bound service because the potential amount of data that needs to be processed in order to provide the information; therefore, its behavior is a bit different than other services. The driver plan is exposed through the following request: .. code-block:: GET https://core.envaseconnect.cloud/drivers/{driverId}/plans The response will return information about the moves routed to the driver for **today** and will have the following structure: .. code-block:: json { "self": "string", "items": [ { "shipment": { "id": "12345", "href": "/shipments/12345" }, "moves": [ { "driver": { "id": "100", "href": "/drivers/100", "type": "driver" }, "events": [ { "appointment": { "end": "2020-02-27T13:00:00", "number": "event-1-appt-number", "start": "2020-02-27T12:30:00" }, "scheduled": "2020-02-27T13:00:00", "arrived": "", "completed": false, "departed": "", "site": { "id": "111", "href": "/locations/sites/111" }, "type": "hook-origin" }, { "appointment": { "end": "2020-02-27T15:00:00", "number": "event-2-appt-number", "start": "2020-02-27T14:30:00" }, "appointment": "2020-02-27T14:30:00.571307-05:00", "arrived": "", "completed": false, "departed": "", "site": { "id": "222", "href": "/locations/sites/222" }, "type": "drop-destination" } ], "status": "pending" } ] } ] } The response shows a list of plans for the driver. Each item on the list contains a reference to the shipment, and a list of moves within the shipment that have been routed to the driver. Each move contains information about the events and their state. On a new shipment, the event will show a completed status of ``false``. The `move.status` will show a value of ``pending``. The |ma| needs to evaluate this information to determine the progress. When events have been completed, their ``completed`` property will show ``true``. The move status will also update accordingly. .. important:: Calculating the driver plan is a very expensive operation. That's why the default is to only provide the plan for **today**. The API supports query parameters to broad the date range of the response. The driver plan API support query parameters to fine-tune the data retrieved. The following shows the supported query parameters: .. code-block:: # Return driver plans starting on a specific date. GET https://core.envaseconnect.cloud/drivers/{driverId}/plans?startDate=2021-02-05 # Return driver plans on a date range. GET https://core.envaseconnect.cloud/drivers/{driverId}/plans?startDate=2021-02-03&endDate=2021-02-05 # Specifying only the endDate is an error. GET https://core.envaseconnect.cloud/drivers/{driverId}/plans?endDate=2021-02-05 -> ERROR!!! .. important:: The |ma| should be careful not specifying a broad date range because it may take a long time to calculate and the response might time-out. Using a time range of about a week should be fine, but it really depends on the volume of data in the customer TMS. After the |ma| has retrieve the driver plans, it should correlate the information with the related shipment itinerary, since all updates should be done through the itinerary object. Correlating Driver Loads with Shipment Itineraries ----------------------------------------------------------------------------- The load updates that |ma| submits are processed through the shipment itinerary object. The driver plans reference the related shipment as you can see in the example above. From that information, the |ma| can retrieve the full itinerary for a shipment using the following API: .. code-block:: GET https://core.envaseconnect.cloud/shipments/{shipmentId}/itinerary The driver plan in the previous section shows a move on shipment ``12345``, so a request to ``https://core.envaseconnect.cloud/shipments/12345/itinerary`` will return the corresponding itinerary: .. code-block:: json { "moves": [ { "driver": { "id": "100", "href": "/drivers/100", "type": "driver" }, "events": [ { "appointment": { "end": "2020-02-27T13:00:00", "number": "event-1-appt-number", "start": "2020-02-27T12:30:00" }, "scheduled": "2020-02-27T13:00:00", "arrived": "", "completed": false, "departed": "", "site": { "id": "111", "href": "/locations/sites/111" }, "type": "hook-origin" }, { "appointment": { "end": "2020-02-27T15:00:00", "number": "event-1-appt-number", "start": "2020-02-27T14:30:00" }, "scheduled": "2020-02-27T14:30:00", "arrived": "", "completed": false, "departed": "", "site": { "id": "222", "href": "/locations/sites/222" }, "type": "drop-destination" } ], "status": "pending" }, { "driver": { "id": "200", "href": "/drivers/200", "type": "driver" }, "events": [ { "appointment": { "end": "2020-02-28T13:00:00", "number": "event-1-appt-number", "start": "2020-02-28T12:30:00" }, "scheduled": "2020-02-28T13:00:00", "arrived": "", "completed": false, "departed": "", "site": { "id": "222", "href": "/locations/sites/222" }, "type": "hook-empty" }, { "appointment": { "end": "2020-02-28T15:00:00", "number": "event-1-appt-number", "start": "2020-02-28T14:30:00" }, "scheduled": "2020-02-28T14:30:00", "arrived": "", "completed": false, "departed": "", "site": { "id": "111", "href": "/locations/sites/111" }, "type": "drop-empty" } ], "status": "pending" } ], "id": "12345", "self": "/shipments/12345/itinerary", "shipment": { "id": "12345", "href": "/shipments/12345" } } You can see in the itinerary response that the first move on the list corresponds to the move in the driver plan in the previous section. This match can be done by evaluating different properties. The first property to evaluate is the ``move[*].driver.id``, which should match to the driver id specified in the plan. The itinerary above has been assigned two different drivers for the first move and second move. Only the first move matches. Sometimes, the driver will be assigned multiple moves in a shipment itinerary. The plan and itinerary will have to be correlated by the events within the moves. This can be done by evaluating the ``event.type`` and ``event.site`` information. .. important:: The |ma| needs to make this correlation and keep track of it in order to update the status of the events as they are completed. There will be additional information that the |ma| will want to retrieve related to the shipment. The following section explains how to retrieve additional information. Retrieving Load Details ----------------------------------------------------------------------------- The |ma| can retrieve additional information about the loads to present them to the driver. This information is referenced in the shipment itinerary or other components of the shipment. The API provides the references to additional information in the responses. **Retrieving Site Information** An important bit of information is the location where the events in the itinerary happen. The ``Event`` representation inside of the move references the location where it happens as the ``site`` property. This property is a reference to a location, and the ``href`` property within it points to the relative URL to get additional information: .. code-block:: GET https://core.envaseconnect.cloud/locations/sites/111 The response has the following structure: .. code-block:: json { "address1": "1 WASHINGTON ST.", "address2": "", "city": "DOVER", "code": "SITE111", "comments": "This is a new site", "country": "US", "directions": "Use the back entrance", "name": "SITE 111", "phone1": "8005551234", "phone2": "", "state": "NH", "zip": "03878", "id": "111", "self": "/locations/sites/111" } **Retrieving Shipment Equipment Information** The |ptca| provides information about the equipment associated with a shipment. It allows you to retrieve the chassis and containers associated with a specific shipment. The responses provide references to the actual equipment resource. You can get the associated chassis with the following request: .. code-block:: GET https://core.envaseconnect.cloud/shipments/{shpmentId}/equipment/chassis The response is a collection of the associated chassis: .. code-block:: json { "self": "/shipments/1234/equipment/chassis", "items": [ { "id": "121", "self": "/shipments/1234/equipment/chassis/121", "chassis": { "id": "1", "href": "/equipment/chassis/1" } } ] } As you can see, the collection provides references to the actual chassis in the equipment API. Normally, a shipment will have a single chassis, but some shipments are setup with multiple chassis. You can do the same with containers associated with the shipment: .. code-block:: GET https://core.envaseconnect.cloud/shipments/{shpmentId}/equipment/containers The response is a collection of the associated containers: .. code-block:: json { "self": "/equipment/containers", "items": [ { "id": "121212", "self": "/shipments/1234/equipment/containers/121212", "container": { "id": "1", "href": "/equipment/containers/1" }, "seal": "SL54321" } ] } The container reference is similar to the chassis, but it has an extra property ``seal`` that can be set to the seal reference number for that container. **Updating Equipment Information** The |ptca| allows to update the shipment equipment information by updating the references to valid equipment types in the system. One of the use cases for the |ma| is to update the ``seal`` property of a shipment container when the driver picks the container at the origin. This can be done with the following request: .. code-block:: PUT https://core.envaseconnect.cloud/shipments/{shpmentId}/equipment/containers/{containerId} The ``{containerId}`` used must be the ``id`` provided in the container reference. In the example above, the reference ``id`` is ``121212``. You should not mistake this ``id`` with the ``id`` insided the ``container`` property, which is the ``id`` of the container in the general equipment API. The payload to that endpoint should provide a full reference with the updated properties: .. code-block:: json { "container": { "id": "1" }, "seal": "SL789654" } In this example, we're just updating the ``seal`` property. Accept/Reject Load ----------------------------------------------------------------------------- One of the first things a driver will have to do is to accept or reject a load. This is done through the shipment itinerary by updating the value of the move status to ``accepted`` or ``rejected``. The API that exposes the shipment itinerary supports a ``PUT`` http method to do updates. This API requires a full shipment itinerary payload, so the |ma| should first retrieve the itinerary as shown above, update the necessary properties, and then send a ``PUT`` with the entire itinierary. The following shows the request to accept a load: .. code-block:: PUT https://core.envaseconnect.cloud/shipments/12345/itinerary The payload will look as follows: .. code-block:: json { "moves": [ { "driver": { "id": "100", "href": "/drivers/100", "type": "driver" }, "events": [ { "appointment": { "end": "2020-02-27T13:00:00", "number": "event-1-appt-number", "start": "2020-02-27T12:30:00" }, "scheduled": "2020-02-27T13:00:00", "arrived": "", "completed": false, "departed": "", "site": { "id": "111", "href": "/locations/sites/111" }, "type": "hook-origin" }, { "appointment": { "end": "2020-02-27T15:00:00", "number": "event-1-appt-number", "start": "2020-02-27T14:00:00" }, "scheduled": "2020-02-27T14:30:00.571307-05:00", "arrived": "", "completed": false, "departed": "", "site": { "id": "222", "href": "/locations/sites/222" }, "type": "drop-destination" } ], "status": "accepted" }, { "driver": { "id": "200", "href": "/drivers/200", "type": "driver" }, "events": [ { "appointment": { "end": "2020-02-28T13:00:00", "number": "event-1-appt-number", "start": "2020-02-28T12:30:00" }, "scheduled": "2020-02-28T13:00:00.571307-05:00", "arrived": "", "completed": false, "departed": "", "site": { "id": "222", "href": "/locations/sites/222" }, "type": "hook-empty" }, { "appointment": { "end": "2020-02-28T15:00:00", "number": "event-1-appt-number", "start": "2020-02-28T14:00:00" }, "appointment": "2020-02-28T14:30:00.571307-05:00", "arrived": "", "completed": false, "departed": "", "site": { "id": "111", "href": "/locations/sites/111" }, "type": "drop-empty" } ], "status": "pending" } ], "id": "12345", "self": "/shipments/12345/itinerary", "shipment": { "id": "12345", "href": "/shipments/12345" } } Notice how the ``status`` property of the first move has been set to ``accepted``. Confirming Arrival and Departure Points ----------------------------------------------------------------------------- As the driver completes the shipment, the event ``arrived`` and ``departed`` properties will need to be updated in the itinerary object. The update will happen through the shipment itinerary API and a full itinerary will need to be provided. The update is done by updating the ``arrived`` property of the event when the driver arrives to the location, and updating the ``departed`` property when the driver leaves. Updating this properties will also update the status of other properties in the itinerary: * Setting the ``arrived`` property in the event will mark the ``move.status`` to ``progress``. * Setting the ``departed`` property in the event will set the ``event.completed`` to ``true``. * Setting the ``ddeparted`` property in the last event of a move will also update the ``move.status`` to ``completed``. This means that the |ma| only has to update the date/time of the ``arrived`` and ``departed`` properties of the events to track the status of the itinerary. Updating Appointment Info ----------------------------------------------------------------------------- The event ``appointment.number`` property can be updated using the shipment itinerary. Note that the ``appointment.start`` and ``appointment.end`` properties are read-only and cannot be updated using the API. Document Management ============================================================================= Another important use case for the |ma| is the ability to submit shipment documents, as well as request other documents that contain important information for the driver. The |ptca| exposes APIs that allow submitting documents to the TMS and to retrieve existing documents from it. .. important:: At the moment, the TMS only supports documents in ``.tiff`` image format. It's the responsibility of the |ma| to provide the documents in the supported format. Requested documents will also be provided in ``.tiff`` image format. The following sections describe the available APIs and workflows for document management: Submit Document to TMS ----------------------------------------------------------------------------- The first step for the mobile app to submit a document is to upload it to **AWS S3**. The mobile app can decided where within AWS S3 the document will be located as a supported image. Once the document is uploaded, the |ma| should notify the TMS by sending a ``POST`` request to the service providing the necessary metadata to allow the TMS to retrieve the image: .. code-block:: POST https://core.envaseconnect.cloud/images The body of the request should have the following structure: .. code-block:: json { "context": "SHIPMENT", "entityId": "12345", "type": "BOL", "location": "S3", "bucket": "images-bucket", "fileKey": "key/within/the/bucket.tiff" } The properties on the payload have the following meaning: * **context**: The image context, which for the |ma| will always be ``SHIPMENT``. * **entityId**: The entity related to the image. Since the image context is ``SHIPMENT``, the value must be the shipment id. * **type**: One of the supported image types described below. * **location**: The |ma| uploads the images to S3; therefore, this property must always be set to ``S3``. * **bucket**: Bucket name where the image was uploaded. * **fileKey**": The file key within the bucket (the relative path to the file). The TMS supports the following image types: * **BOL**: Bill of Lading. * **CHAS TIR IN**: Chassis Trailer Interchange Receipt in * **CHAS TIR OUT**: Chassis Trailer Interchange Receipt out * **CUSTOMS**: Customs paperwork. * **DAMAGES**: Damage details. * **DEL DELAY**: Proof of Delivery Delay. * **EQUIPMENT PRE**: Pre trip inspection. * **EQUIPMENT POST**: Post trip inspection. * **HAZMAT**: Hazmat Details. * **OVERWEIGHT**: Permit for overweight load. * **POD**: Proof of Delivery. * **POP**: Proof of Pickup. * **PRENOTE**: Earliest information about a shipment. * **PU DELAY**: Proof of Pickup Delay. * **SCALE TICKET**: Ticket from weighting the truck. * **SEAL**: Container Seal. * **TIR IN**: Trailer Interchange Receipt (aka. EIR Equipment Interchange Receipt). * **TIR OUT**: Trailer Interchange Receipt. Request Document from TMS ----------------------------------------------------------------------------- The process for a driver to request an image is the inverse from uploading the image to the TMS. The |ma| should start the process by requesting the image from the TMS by sending a request: .. code-block:: GET https://core.envaseconnect.cloud/images?context=SHIPMENT&entityId=12345&&type=CUSTOMS The request requires the following parameters: * **context**: The image context, which for the |ma| will always be ``SHIPMENT``. * **entityId**: The id of the associated entity. Since the context is ``SHIPMENT``, it must be the shipment ``id``. * **type**: The type of the image. The image types that can be requested are: * **BOL**: Bill of Lading. * **CHAS TIR IN**: Chassis Trailer Interchange Receipt in * **CHAS TIR OUT**: Chassis Trailer Interchange Receipt out * **CUSTOMS**: Customs paperwork. * **DAMAGES**: Damage details. * **DEL DELAY**: Proof of Delivery Delay. * **EQUIPMENT PRE**: Pre trip inspection. * **EQUIPMENT POST**: Post trip inspection. * **HAZMAT**: Hazmat Details. * **OVERWEIGHT**: Permit for overweight load. * **POD**: Proof of Delivery. * **POP**: Proof of Pickup. * **PRENOTE**: Earliest information about a shipment. * **PU DELAY**: Proof of Pickup Delay. * **SCALE TICKET**: Ticket from weighting the truck. * **SEAL**: Container Seal. * **TIR IN**: Trailer Interchange Receipt (aka. EIR Equipment Interchange Receipt). * **TIR OUT**: Trailer Interchange Receipt. The API will return metadata for the image, as well as the location from where to access it: .. code-block:: json { "context": "SHIPMENT", "entity": "12345", "type": "CUSTOMS", "location": "S3", "bucket": "my_s3_bucket", "file": "requested/ORG123/SHIPMENT/12345/CUSTOMS.tiff" } It's the |ma| responsibility to download the image from the specified location. Shipment Settlements ============================================================================= The |ma| requires access to the settlement amounts for a shipment. This information is provided by the shipment line item API. The following sections describe how to access shipment line item information and how to create new shipment line items. Retrieve Shipment Settlements ----------------------------------------------------------------------------- The shipment line items (aka. settlements) can be retrieved through the shipment line items API. This API provides information about all the settlement amounts for the shipment. To retrieve all the shipment line items, the |ma| can send a request to the API: .. code-block:: GET https://core.envaseconnect.cloud/shipments/{shipmentId}/items The API returns a collection of shipment line items that are associated with the specified shipment. The response will have the following structure: .. code-block:: json { "self": "string", "items": [ { "id": "789", "self": "/shipments/4/items/789", "shipment": { "id": 4, "href": "/shipments/4" }, "type": "freight", "quantity": 1, "description": "FROZEN FISH", "rateType": "flat", "payRate": 10, "amount": 20, "note": "These were thawed" } ] } The response provides information about the line items associated with the shipment including individual amounts. It's the responsibility of the |ma| to calculate the total amount for all the items. Adding Settlement Items to Shipment ----------------------------------------------------------------------------- The |ma| can add additional items to the shipment. This is done by sending a request to the API with information about the shipment line item: .. code-block:: POST https://core.envaseconnect.cloud/shipments/{shipmentId}/items The body of the request provides the information about the shipment line item: .. code-block:: json { "type": "freight", "quantity": 1, "description": "FROZEN FISH", "rateType": "flat", "payRate": 10, "amount": 20, "note": "These were thawed" } The shipment id is provided through the URL, so the information is not required in the payload. Driver Endorsements ============================================================================= The |ma| requires access to the endorsements for a driver. The driver endorsements are part of the drivers API, and they are exposed under a specific driver resources .. caution:: The driver endorsements API is currently under discussion and it hasn't been implemented. Things might change after the feature is fully implemented. Retrieve Driver Endorsements ----------------------------------------------------------------------------- The |ma| can retrieve the driver endorsements by sending a request to the driver endorsements API: .. code-block:: GET https://core.envaseconnect.cloud/drivers/{driverId}/endorsements The response will have all the information about the endorsements the driver has: .. code-block:: json { "self": "/drivers/54321/endorsements", "id": "54321", "hazmat": true, "tankHaz": true, "doubleTriple": true, "tank": true, "airBrake": true, "brakeInspection": true } .. Replacements .. |ptga| replace:: Envase Connect Gateway API .. _ptga: ../../index.html .. |ptca| replace:: Envase Connect Core API .. |ma| replace:: Envase Mobile App .. |burl| replace:: https://core.envaseconnect.cloud