QR Code Associations API Developer Guide

Overview

The QR Code Associations API provides the functionality to retrieve asset information based on the QR code assigned to an asset.

Important! QR code associations are created by Caterpillar. Non-Caterpillar users (for example, dealers) can use the API to retrieve the asset information that can then be consumed by their applications.

Workflow

Each manufactured machine is assigned a QR code. The QR code is associated with the basic information about the machine, such as build year, manufacturer and product family, etc. The information can be accessed by scanning the QR and navigating to an encoded web URL, as in this example QR code for Caterpillar 926M wheel loader:

The encoded URL in this example is HTTPS://QR.CAT.COM/CMDZ18G9RYCCW8Y.

When the user scans the QR code in this example, they are redirected from the encoded URL to a Caterpillar web application page that makes the call to QR Code Associations API to retrieve the asset information and displays it.

To retrieve the asset metadata with the QR Code Associations API use this workflow:

1. Read the URL from the scanned QR code attributes. In the example above it is HTTPS://QR.CAT.COM/CMDZ18G9RYCCW8Y.
2. Parse the QR code association ID from the URL. In the example above, it is CMDZ18G9RYCCW8Y, after the last forward-slash (/).
3. Use the QR code association ID with the GET /qrCodeAssociations/{qrCodeId} endpoint to retrieve asset information.

Note: QR code associations link QR Codes to existing assets (by asset serial number and make). If make is not provided, the default is set as CAT.

Subscribing to the API

To access the QR Association API, you must first request a subscription:

• Fill out the API Subscription Request Form - QR Association API.
• The form will open in a new window without closing this page.
• You may be asked to login to the Digital Marketplace again before completing the form.
• After completing your subscription, you may close the subscription window to return to this page.
• You will receive an email with your credentials when your subscription is approved. This process may take approximately two (2) weeks.

Security

The API uses the OAuth 2.0 protocol for authorization. In order to access the API, an OAuth access token is required in the request headers of each API call. A valid OAuth client ID and client secret is required to obtain an OAuth access token.

The following basic information is required to authenticate and generate the token.

An OAuth token expires after 60 minutes. An expired token will need to be replaced with a new token.

Additional OAuth information can be found in Caterpillar OAuth 2.0 Documentation

Accessing the API

The API is only available in the production environment: https://services.cat.com/catDigital/qrCodeAssociations/external/v1

Use the production environment for development and testing.

API Reference Information

For detailed information about the API input parameters, response structure, and error messages, see the API reference documentation.

Get Asset Information for a QR Code

After parsing the association ID from the URL in the scanned QR code, you can retrieve asset information using the GET /qrCodeAssociations/{qrCodeId} endpoint. The API takes QR Code in the path param and returns the Associated data for the authorised request.

Request

curl -X 'GET' \
  'https://services.cat.com/catDigital/qrCodeAssociations/external/v1/qrCodeAssociations/JD81N5L8RV1NKDL' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {access token}'

Response

{
    "serialNumber": "2MJ23425",
    "smcsCode": "79L0",
    "catrecid": "",
    "associationOriginator": "TD00",
    "createTime": "2022-11-09T09:37:11.259073Z",
    "make": "CAT",
    "assetMetadataUpdateStatus": "PENDING",
    "principalWork": {
        "code": "255",
        "description": "BUILDING",
        "codeType": "Engine",
        "codeAssignmentTime": "2022-06-28 10:16:56:000"
    },
    "marketSegment": {
        "code": "GC",
        "description": "AGRICULTURE",
        "subSegmentCode": "LGRB",
        "subSegmentDescription": "LIVESTOCK PRODUCTION"
    }
}

Additional Documentation

The following additional documentation is available:

• QR Code Associations API Postman Collection: https://digital.cat.com/knowledge-hub/document/qr-code-associations-api-postman-collection-0

Glossary

Change History