Configuration

Flow

When using the web widget, there are a few recommendations to keep in mind to ensure the best user experience.

We recommend integrating our widgets into iframes and we recommend using full-screen screens in your application.

Another key recommendation is to use tokens to authenticate and access the widgets. In the following steps, we will discuss how to generate tokens to use with Tchek's widgets.

Finally, we recommend testing the integration thoroughly to ensure it meets your needs and provides a smooth experience for your users. Don't hesitate to reach out to our support team if you have any questions or need assistance.

Generate a Self Inspection SSO Token

In this section, we will describe how to generate an SSO Token that can be used to display a widget within your application. Specifically, we will be using the example of using a widget to perform a Shoot Inspect, but you can also open any of the other views (fast track, report). It's important to note that widgets are displayed within an iframe, so we recommend using full-screen displays for the best user experience. In the next section, we will go into more detail about how to use the generated SSO Token to display a widget within your application.

Get your unique temporary token by using the following request (replace values where required as explained on Create Self Inspection Token Example:

curl --location 'https://alto.tchek.fr/apiV1/tokenmanager/token' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "validity": 90,
  "options": {
    "shootInspect": true,
    "fastTrack": false,
    "cost": false,
    "report": false,
    "downloadRoi": false
  },
  "tradeIn": {
    "tradeinVehicle": true,
    "immat": "AB123CD",
    "sendingType": null
  },
  "customer": {
    "clientType": "customer",
    "email": "customer@test.com",
    "firstname":"John",
    "lastname": "Doe",
    "gender": null,
    "phone": "0033600000000",
    "locale": "en"
  }
}'

/* curl response example */
{
    "token": {
        "expired": false,
        "id": "pgT4ifBFrr",
        "createdAt": "2025-06-13T09:17:18.144Z",
        "updatedAt": "2025-06-13T09:17:18.144Z",
        "tradeinVehicle": true,
        "tradeinStatus": 0,
        "tradeinStatusUpdatedAt": "2025-06-13T09:17:18.111Z",
        "sendingType": 1,
        "vehiclePtr": {
            "id": "9RIHTkcQr5"
        },
        "customerPtr": {
            "id": "kyW5UphEt5"
        },
        "uid": "T6F2644",
        "expiresIn": "2025-09-11T09:17:17.983Z",
        "options": {
            "fastTrack": true,
            "shootInspect": true,
            "cost": false,
            "report": false,
            "downloadRoi": false,
            "loadTchek": true
        },
        "APITokenPtr": {
            "id": "xXIgFxxxx"
        }
    },
    "webApiVersion": "v2.5"
}

Create Shoot Inspect view

Now that we have created the self inspecton token, let us build the URL to the Shoot inspect widget view. Shoot inspect Widget URL:

Shoot Inspect

https://webapp.tchek.fr/{language}/services/{Tokenuid}

Fast track

https://webapp.tchek.fr/{language}/services/{Tokenuid}/fast-track

To create the view, simply replace {Tokenuid} by the actual uid obtained in the previous response, and {language} by the language code depending on your customer's language:

en for English,
fr for French,
de for German,
nl-BE for Dutch,
it for Italian,
es for Spanish,
sv for Swedish,
no for Norwegian

This will allow you to open the Shoot Inspect widget and start the inspection process.

Remember to use full-screen mode for the best user experience.

We will discuss how to create a bridge between your application and our widget. This is important because some of the buttons, such as the close button at the end of our Shoot Inspect, are located within our widget. By creating this bridge, you can be notified when certain actions occur within the widget, allowing you to close the iframe or perform other desired animations within your application.

You need to inject this javascript code in your application

document.addEventListener("DOMContentLoaded", function () {
     window.addEventListener("message", function (e) {
         console.log(JSON.parse(e.data));
     });
 });

To receive information directly from our widget, you can use a response like the one shown below :

/* console.log(data) */
{
    "status": 200,
    "message": "Tchek successfully created !",
    "date": 1652050366222,
    "tchek": {
        "tchek": {...},
        "damages": [...],
        "images": [...],
        "thirdPartyReport": {...}
    }
}

Keep in mind that our API also includes webhooks if you want to handle real-time responses.

See the diagram in ✨ Web Widget for

Integrate this HTML page in your website to easily start testing a self-inspection.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Title</title>

    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        width: 100%;
        height: 100%;
      }

      #iframe {
        position: fixed;
        left: 0;
        top: 0;
        border: none;
        display: none;
      }
    </style>
  </head>
  <body>
    <iframe
      id="iframe"
      scrolling="no"
      src=""
      frameborder="0"
      allow="camera *;microphone *"
    ></iframe>

    <script>
      async function generateToken(apiKey) {
        // read from url, shootInspect, fastTrack, cost, report
        const fastTrack = getUrlParams("fastTrack") || false;
        const cost = getUrlParams("cost") || false;
        const report = getUrlParams("report") || false;
        const locale = getUrlParams("locale") || "en";

        const body = {
          options: {
            shootInspect: true, // whether the final user must take the pictures for the self inspection
            fastTrack, // whether the final user must do the damage validation after taking the pictures; false if the damages are reviewed by your team or by Tchek
            cost, // always false for a self-inspection
            report, // whether the final user must fill the inspection report after the damage validation; false if the report is issued by you or by Tchek
            downloadRoi: false, // always false for a self-inspection
          },
          tradeIn: {
            tradeinVehicle: true,
            immat: "AB123CD", // the vehicle's license plate
            sendingType: null, // see table below
          },
          customer: {
            clientType: "customer", // required: "customer" or "company"
            email: "test@test.com",
            firstname: "xxxxx",
            lastname: "xxxxx",
            gender: null, // "men" / "women"
            phone: "00336xxxxxxxx", // the country code is required
            locale: locale, // available: en,fr,it,de,es,sv,nl-BE
          },
          creatorUserId: "", // optional: the creatoruserId of the user that is responsible for the creation of the lead
          validity: 90 // the validity of the token in days
        };

        // make a http call to generate the token
        const response = await fetch(
          "https://preprod.alto.tchek.fr/apiV1/tokenmanager/token",
          {
            method: "POST",
            body: JSON.stringify(body),
            headers: {
              "Content-type": "application/json; charset=UTF-8",
              "X-API-Key": apiKey,
            },
          }
        );
        const data = await response.json();
        console.log(data);
        return data.token.uid;
      }

      function resizeIframe() {
        const iframe = document.getElementById("iframe");
        // get parent document width

        // get body width pixel displayed on the screen
        const pageWidth = iframe.parentElement.clientWidth;
        // get body height pixel displayed on the screen
        const pageHeight = iframe.parentElement.clientHeight;

        // console.log(pageHeight, pageWidth);
        // set iframe width and height
        iframe.style.width = `${pageWidth}px`;
        iframe.style.height = `${pageHeight}px`;

        // Fix bug on safari 16, iframe is half visible
        iframe.style.top = "0";
      }

      function getUrlParams(key) {
        return new URLSearchParams(window.location.search).get(key);
      }

      function generateIframe(token) {
        const locale = getUrlParams("locale") || "en";
        // add iframe to the page
        const iframe = document.getElementById("iframe");
        // set style display block
        iframe.style.display = "block";
        iframe.src = `https://webapp.tchek.fr/${locale}/services/${token}`;

        resizeIframe();
      }

      window.addEventListener("resize", function () {
        resizeIframe();
      });

      window.addEventListener("DOMContentLoaded", async (event) => {
        // read ApiToken from url
        const apiKey = getUrlParams("apiKey");
        // get token from URL
        const token = getUrlParams("token");

        if (apiKey) {
          // send message to iframe
          const tokenGenerated = await generateToken(apiKey);
          generateIframe(tokenGenerated);
        } else if (token) {
          generateIframe(token);
        }
      });

      //adding event listener to read the incoming message from Tchek iframe:
      window.addEventListener("message", (event) => {

        if (
          typeof event.data === "string" &&
          event.data.indexOf("Tchek successfully created") > -1
        ) {
          const messageReceived = JSON.parse(event.data);
          if (messageReceived.message === "Tchek successfully created !") {
            console.log(
              ">>> PostMessage from TCHEK received !",
              messageReceived
            );
            alert(JSON.stringify(messageReceived));
          }
        }
      });
    </script>
  </body>
</html>

When opening the page from your browser, some parameters in your URL are required:

apiKey: your API Token provided when signing up
locale: the customer language code

Other parameters are optional:

fastTrack: true to let the user do the damage review (AKA Fast track) after taking the pictures.

Once integrated, call the URL like so:

https://[your-website]/inspection?apiKey=[your_api_token]&locale=[locale] to start the self inspection.

To call the staging environment, remember to edit the url in this line and use https://preprod.webapp.tchek.fr/ instead:


iframe.src = https://webapp.tchek.fr/${locale}/services/${token};

To obtain a SSO token to see the final inspection web report, you must query the tokenManager API by entering the tchekId obtained at the end of the inspection in the Post message from the widegt, or via webhook, or by querying the Self inspection token status API endpoint. Here's an example :

 curl --location 'https://alto.tchek.fr/apiV1/tokenmanager/token' \
--header 'x-api-key: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
    "validity": 30,
    "tchekId": "yourTchekId",
    "options": {
  "thirdParty": false,
  "fastTrack": false,
  "shootInspect": false,
  "cost": true,
  "report": true,
  "downloadRoi": false,
  "loadTchek": true
    }
}'

field

type

Description

validity

integer

The validity of the report token in days, past which the token will expire:

tchekId

string

The inspection id obtained at the end of the inspection.

options.cost

boolean

Set to true to obtain the report with repair cost, or false to obtain the report without repair cost.

options.thirdParty

boolean