Partner Integration
===================

The partner integration is a little more complex to set up,
but it's more powerful. In order to use the Partner Integration,
you will need to be initially configured by Loadsmart, just as
if you were using the Carrier Integration, however, some
data is dynamically generated.

The main difference between these two integrations, is that
with a Carrier Integration, we will inform you once you are
set up on our side, two pieces of information: **issuer** and
**account uuid**.

With the partner integration, you still need both pieces, both
you are required to make a separate set of calls to determine
or get the **account uuid** - in order to be able to sign
:code:`User-JWT` calls.

The authentication and authorization of our API, when we discuss
**User-JWT** API calls is determined by both of those claims signed
in the token.

When you sign up a token with a **usr:<account uuid>**, we will
verify if you are allowed to impersonate such carrier. This is
controlled by a set of :code:`integration requests`.

Initial Workflow
****************

The initial workflow for the Partner Integration is quite
similar with the Carrier Integration:

1. Send our team your public key
2. We will set you up on our *sandbox* environment and
   will return you a single piece of information: :code:`issuer`.
   This will only allow you to do :code:`sys` calls to our API.
3. In your application, configure this value. You will need
   this information to integrate with new carriers and
   determine subsequent :code:`account uuid` needed to
   do :code:`User-JWT` calls.

Scopes
******

There are scopes for each sys endpoint that you must
have enabled.

For all partners going this route, the minimum set of
scopes necessary are:

1. :code:`carrier_search`
2. :code:`carrier_read`
3. :code:`request_integration_write`
4. :code:`request_integration_read`

These scopes should be configured by the Loadsmart team
to you. You don't have to do anything on that regard.

Once your token is configured, you can move on to making
calls to **integrate** with carriers and impersonating them
in our platform.

The scopes for the integrated carriers will be determined
by Loadsmart's application at runtime, but usually they will
contain the scopes necessary to fully operate the features for
:doc:`/features/carrier-management`, :doc:`/features/truck-matching`,
:doc:`/features/load-offers-api` and :doc:`/features/shipment-apis`.

Impersonating a carrier
***********************

Your token, by itself, does not have a lot of scopes associated
with it.

In order to do more in the platform, you need to impersonate a
carrier.

The basic workflow for this is the following:

1. `Search Carrier`_ (in order to find his primary key on Loadsmart);
2. `Request Integration`_ with a Carrier;
3. `Check Integration`_ request to see if it was accepted **by the carrier**;
4. Do requests on behalf of this carrier

The workflow is simple, however there are exceptions scenarios
of several endpoints, that we will try to cover as clear as possible.

There are different steps you need to take in order to be have a fully
configured carrier in out platform, depending on it's initial state.

The following starting states are possible for a carrier in Loadsmart:

1. :code:`NEW`
2. :code:`PENDING`
3. :code:`READY`

For carriers that are :code:`NEW` in Loadsmart, you will need to provide
data for the first user and the documents associated with that carrier
(W9, Insurance, Authority).

For carriers that are :code:`PENDING` or :code:`READY`, you will
need to wait for the carrier owner acceptance.

Once the integration is accepted and the carrier still :code:`PENDING`,
it means that one or more documents are missing (check on `Check Integration`_)
or an approval is needed on Loadsmart side.

You can poll the `Check Integration`_ endpoint to see if the integration got accepted.

The basic steps you need to take are:

+------+---------------------------------------+------------------------------------------+
| Step | Initial Carrier State = PENDING/READY | Initial Carrier State = NEW              |
+------+---------------------------------------+------------------------------------------+
| 1    | `Search Carrier`_ (GET)               | `Search Carrier`_ (GET)                  |
+------+---------------------------------------+------------------------------------------+
| 2    | Carrier status = PENDING/READY        | Carrier Status = NEW                     |
+------+---------------------------------------+------------------------------------------+
| 3    | `Request Integration`_ (POST)         | `Request Integration`_ with Owner (POST) |
+------+---------------------------------------+------------------------------------------+
| 4    | Poll `Check Integration`_ (GET)       | Integration Auto Accepted                |
+------+---------------------------------------+------------------------------------------+
| 5    | Proceed with Usr-JWT calls            | Proceed with Usr-JWT calls               |
+------+---------------------------------------+------------------------------------------+

Carrier Compliance and "Load Offers" feature
********************************************

While the process for onboarding a new carrier on our platform
is simple, there are specific checks we make in order to make
sure the carriers we are allowing to take in freight, are
compliant with our customers.

Each customer has a threshold for insurance and safety checks,
so, while you might see freight available, not all freight will
be available for any carrier. The carrier must be compliant with
what each of our customers specify.

Right now, there is no API to find out these constraints and they
are handled internally and will be reflected in the acceptance
endpoints if the carrier does not meet the shipper requirements.

However, if you aim to use the :doc:`/features/truck-matching` and/or
:doc:`/features/load-offers-api` in order to book loads for carriers,
you need to send a set of documents using our API so our operations
team can validate them and authorize this impersonated carrier to
source loads.

The `Document Upload`_ endpoint allows you to send a PDF or a image for the
type of document you are sending. There are three types that are required
in order for the carrier to **source loads**.

1. :code:`W9`
2. :code:`insurance`
3. :code:`authority`

Since, for now, this check is a semi-automated process, it can take
some time from the upload to the validation of each piece of document.

You can poll the `Check Integration`_ endpoint to check the status for
each document.

A carrier is fully "onboarded" and allowed to take freight when the response
of this endpoint is the following:

.. code-block:: JSON

    {
        "id": "fe17b7e7-6453-4520-b99d-2d2b44972468",
        "account_id": "bc32c4d4-5732-7845-aa32-132cdab5467b",
        "carrier": {
            "id": "9f87d040-f843-42e7-887a-45bea55e76f3",
            "mc": "12345",
            "dot": "54321",
            "name": "John Doe Freights",
            "status": "ready",
            "eligible": true
        },
        "status": "ACCEPTED",
        "documents": [
            {
            "type": "w9",
            "status": "accepted"
            },
            {
            "type": "insurance",
            "status": "accepted"
            },
            {
            "type": "authority",
            "status": "accepted"
            }
        ]
    }

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

In order to make sure that all steps are been correctly followed, there are
a test-case to execute in **sandbox** environment. Here follows the sequence of
actions to be executed:

1. Generate an `Application-JWT token`_;
2. `Search Carrier`_ with MC# 9999 or DOT 1667640;
3. `Request Integration`_ for this Carrier;
4. `Check Integration`_ and verify the `status` field, it must be `ACCEPTED`;

Case the integration supports document exchange, it is recommended to test the
documents upload;

5. Generate an `User-JWT token`_, use the `account_id` value retrieved on step 3 (also on step 4)
   to build the token and impersonate the carrier;
6. `Document Upload`_ the `W9`, `insurance` and `authority` documents and then reach the
   `document_url` of each response in order to verify if the file was correctly uploaded.

.. _Search Carrier: https://developer.loadsmart.com/api/#tag/Carrier/paths/~1api~1v2~1carrier~1search/get
.. _Request Integration: https://developer.loadsmart.com/api/#tag/Carrier/paths/~1api~1v2~1carrier~1integration-request/post
.. _Check Integration: https://developer.loadsmart.com/api/#tag/Carrier/paths/~1api~1v2~1carrier~1integration-request~1{id}/get
.. _Document Upload: https://developer.loadsmart.com/api/#tag/Carrier/paths/~1api~1v2~1carrier~1documents/post
.. _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

The following diagram represents the flow of requesting integration to a carrier and
be able to use Load Offers API.

.. mermaid:: ../assets/onboard-carrier.mmd

Notes: each box on the diagram above represents a request, the following image describes
which token signature must be used on each request.

.. mermaid:: ../assets/tokens.mmd