Load Offers API
===============

This document outlines all the features that we have
to support the Load Offers API interface.

This set of features allows you, as a integrator, to query
our available loads and accept these directly from your
platform.

Main features:

1. List Available Loads
2. Accept Load
3. List Accepted Loads
4. Drop Carrier from Load
5. Manage webhooks


How each feature works?
***********************

This API works as a marketplace where many loads are offered every day.
The `Search Offers endpoint`_ provides many query parameters in order
to filter the results based on origin, destination, equipment type,
pickup date or delivery date.

Request::

    curl --request GET \
    --url https://api.sandbox.loadsmart.com/api/v2/load-offers/offers \
    --header 'Authorization: JWT <Application-JWT token>' 

Response::

    Response::

    {
        "count": 1,
        "next": null,
        "previous": null,
        "results": [
            {
                "id": "1f3b2981-dae1-4e48-bc6a-01ea55efd8fd", <-- offer reference
                "price": 2246.0,
                "load": {
                    "equipment_type": "DRV",
                    "commodity": "",
                    "weight": 20000.0,
                    "dimensions": {
                        "length": null,
                        "height": null,
                        "width": null
                    },
                    "distance": 1300.5,
                    "stops": [
                        {
                            "type": "PU",
                            "address": "101 Collins Avenue",
                            "city": "Miami Beach",
                            "state": "FL",
                            "country": "USA",
                            "window_start": "2023-09-13T13:00:00Z",
                            "window_end": "2023-09-13T15:00:00Z",
                            "window_timezone": "America/New_York",
                            "requirements": {
                                "blind_bol": false,
                                "drop_trailer": false,
                                "heavy_scale_ticket": false,
                                "light_scale_ticket": false
                            },
                            "latitude": 25.770007,
                            "longitude": -80.133743,
                            "zipcode": "33139",
                            "facility_info": {
                                "score": null,
                                "avg_time_spent": {
                                    "pickup": 7,
                                    "delivery": null
                                },
                                "detention_rate": 0
                            }
                        },
                        {
                            "type": "DEL",
                            "address": "459 Broadway",
                            "city": "New York",
                            "state": "NY",
                            "country": "USA",
                            "window_start": "2023-09-14T18:00:00Z",
                            "window_end": "2023-09-14T20:00:00Z",
                            "window_timezone": "America/New_York",
                            "requirements": {
                                "blind_bol": false,
                                "drop_trailer": false,
                                "heavy_scale_ticket": false,
                                "light_scale_ticket": false
                            },
                            "latitude": 40.720859,
                            "longitude": -74.000961,
                            "zipcode": "10013",
                            "facility_info": {
                                "score": null,
                                "avg_time_spent": {
                                    "pickup": 1,
                                    "delivery": null
                                },
                                "detention_rate": 0
                            }
                        }
                    ],
                    "requirements": {
                        "beer": null,
                        "chemicals": null,
                        "ctpat": null,
                        "food_grade": null,
                        "frozen": null,
                        "hazmat": null,
                        "hvhr": null,
                        "pharmaceuticals": null,
                        "produce": null,
                        "teams": false,
                        "tsa": null,
                        "twic": null,
                        "vented_vans": null
                    },
                    "ref_number": "413036"
                },
                "actions": {
                    "redirect_url": "https://carrier.sandbox.loadsmart.com/#/loads/7e97683d-ea5a-4754-bf0c-e88644f3b997?utm_source=mayara",
                    "accept_url": "https://api.sandbox.loadsmart.com/api/v2/load-offers/offers/1f3b2981-dae1-4e48-bc6a-01ea55efd8fd/accept" <-- book it now URL
                }
            }
        ]
    }


Besides other information, you'll find the offer unique identifier in this 
endpoint's response. You can use it to further requests such as to get
a specific offer information:

Request::

    curl --request GET \
    --url https://api.sandbox.loadsmart.com/api/v2/load-offers/offers/1f3b2981-dae1-4e48-bc6a-01ea55efd8fd \
    --header 'Authorization: JWT <Application-JWT token>' 



After the search, an offer can be accepted for a carrier. It is necessary
to use User-JWT to call the `Accept an Offer endpoint`_ in order accept
the offer for a specific carrier signed on token.

Request::

    curl --request POST \
    --url https://api.sandbox.loadsmart.com/api/v2/load-offers/offers/1f3b2981-dae1-4e48-bc6a-01ea55efd8fd/accept \
    --header 'Authorization: JWT <User-JWT token>' 

Response::

    {
	    "id": "f4212bbb-3a52-47bb-bc88-de0bbe335eaa" <<- load reference
    }

Besides other features, you can use the load reference to download the 
Rate Confirmation by calling the `Rate Confirmation endpoint`_:

Request::

    curl --request GET \
    --url https://api.sandbox.loadsmart.com/api/v2/load-offers/loads/f4212bbb-3a52-47bb-bc88-de0bbe335eaa/rate_confirmation \
    --header 'Authorization: JWT <User-JWT token>' 

Every accepted offer can be listed and detailed for further verification
by using the `List Accepted Loads endpoint`_:

Request::

    curl --request GET \
    --url https://api.sandbox.loadsmart.com/api/v2/load-offers/loads \
    --header 'Authorization: JWT <Application-JWT token>' 

An accepted load can be dropped in case the carrier is no longer able to move
the load. To perform this action, the `Drop a load endpoint`_ must be called.

Request::

    curl --request DELETE \
    --url https://api.sandbox.loadsmart.com/api/v2/load-offers/loads/f4212bbb-3a52-47bb-bc88-de0bbe335eaa \
    --header 'Authorization: JWT User-JWT' \
    --header 'Content-Type: application/json' \
    --data '{
        "reason": "drop reason"
    }'

A couple of events can be sent via webhook calls and it informs when an event
is originated inside Loadsmart's platform. The events can be:

* `load_cancelled`: the load was canceled by the shipper.
* `load_carrier_bounced`: the carrier was dropped from the load by Loadsmart.

This API provide endpoints to manage the webhooks configurations.

For the features listed above, they are all accessible over a
`REST API`_.

Validating on Sandbox
*********************

In order to make sure that all steps are been correctly followed, there are
a few test-cases to execute in **sandbox** environment. Before executing these steps
it is important to complete the validation of :doc:`/how-tos/partner` case
the partner integration is been created.

Accept an Offer:

1. With a `Application-JWT token`_, `Search Offers`_;
2. With a `User-JWT token`_, `Accept an Offer`_;
3. `List Loads`_ and check if the load from the accepted offer is there.

Drop a Load:

1. With an a load that was accepted (previous test case);
2. `Drop a Load`_;
3. `List Loads`_ and check if the load was removed.

Load dropped event (this test requires interaction with Loadsmart team):

1. With the `webhooks`_ configured;
2. And with an a load a accepted (first test case);
3. Loadsmart will drop the carrier an accepted load (event `load_carrier_bounced`);
4. Check if the webhook event is received.

.. _REST API: https://developer.loadsmart.com/api/#tag/Load-Offers
.. _Search Offers endpoint: https://developer.loadsmart.com/api/#tag/Load-Offers/paths/~1api~1v2~1load-offers~1offers/get
.. _Search Offers: https://developer.loadsmart.com/api/#tag/Load-Offers/paths/~1api~1v2~1load-offers~1offers/get
.. _Accept an Offer endpoint: https://developer.loadsmart.com/api/#tag/Load-Offers/paths/~1api~1v2~1load-offers~1offers~1{offer_id}~1accept/post
.. _Accept an Offer: https://developer.loadsmart.com/api/#tag/Load-Offers/paths/~1api~1v2~1load-offers~1offers~1{offer_id}~1accept/post
.. _Drop a load endpoint: https://developer.loadsmart.com/api/#tag/Load-Offers/paths/~1api~1v2~1load-offers~1loads~1{load_id}/delete
.. _Application-JWT token: https://developer.loadsmart.com/api/#section/Authentication/Available-contexts/Application-JWT
.. _User-JWT token: https://developer.loadsmart.com/api/#section/Authentication/Available-contexts/User-JWT
.. _List Loads: https://developer.loadsmart.com/api/#tag/Load-Offers/paths/~1api~1v2~1load-offers~1loads~1/get
.. _Drop a Load: https://developer.loadsmart.com/api/#tag/Load-Offers/paths/~1api~1v2~1load-offers~1loads~1{load_id}/delete
.. _webhooks: https://developer.loadsmart.com/api/#tag/Load-Offers/paths/~1api~1v2~1load-offers~1webhooks/get
.. _Rate Confirmation endpoint: https://developer.loadsmart.com/api/#tag/Load-Offers/paths/~1api~1v2~1load-offers~1loads~1%7Bload_id%7D~1rate_confirmation/get
.. _List Accepted Loads endpoint: https://developer.loadsmart.com/api/#tag/Load-Offers/paths/~1api~1v2~1load-offers~1loads~1/get