Advance Positioning APIs

Introduction and Background

Introduction

Today, the usage of REST APIs provides a modern communication standard between IT systems. In order to improve customer experience and respond to increased customer demands, Trimble’s - “TAP Business Systems Technology and Strategy” team is introducing a new REST API service that will process and manage Orders.

For customers who want to integrate Process/manage Order from their own custom application, REST API is an alternative communication interface that enables a partner to integrate create order/activation functionalities into their application easily and quickly.

This document provides you an overview of the new REST API, the methods supported during the initial Pilot Phase, the On Boarding and initial test procedures as well as the contact details of the TAPStore API v1.0 Support Team.

Business Need

Large resellers are looking for an easy, fast and affordable way to process the order and manage renewals, in a way that the cost wont exceed the margin for the subscriptions. The approach is to offer an API to the resellers/OEM’s to simplify the ordering process, provide device/activation and sales order related information on demand. Resellers will be able to use their existing applications for trimble products that makes doing business easier with Trimble. The API should also reduce the requests for order placing and trouble shooting to large sellers, their retail outlet and TAP customer care.

Technical Overview

API v1.0 Technical Spec

The REST API is secured using Oauth2 and ‘OpenID Connect’. When the customer is on-boarded they will be provided with the client_id and client_secret for authenticating and accessing the API services. This API is complementary in usage to the existing TAP store functionalities.

Authentication Mechanism

Please refer to the URL https://developer.trimble.com/docs/authentication for more information on how to generate access_token. We are using grant type as Client Credentials.

API Limits

Connection Timeout: Within how much time API should respond to get success/failure response from the backend system. If the limit is crossed then a Timeout error will occur. Value for this parameter is set to 55 (fifty five) seconds. If there is no response from API within this time, connection will timeout.

Spike Arrest: Spike Arrest is the number of concurrent requests that can be sent per second. After this limit is reached the Trimble cloud server will reject the request. The value for this parameter is set to - 1,500 (fifteen hundred) requests per second.

Supported Methods

This section defines the basic requirements, inputs and outputs payload for the below mentioned API’s:

1. TAP_GET_CUSTOMERS_API
2. TAP_GET_MFG_MODELS_API
3. TAP_GET_PRODUCTS_API
4. TAP_GET_ORDER_API
5. TAP_GET_ACTIVATION_STATUS_API
6. TAP_CREATE_ORDER_API
7. TAP_RESEND_ACTIVATION_API

There are five GET APIs and two POST APIs

API flow diagram

API Usage notes applicable to API’s

1. All request parameters will be validated. If a different field is passed in the payload other than the expected, API will respond with error for that field.
2. Every API will have a uniqueId in the response payload. This can be helpful in tracking/debugging that specific request.
3. Date/time format will be in UTC format. “YYYY-MM-DD hh:mm:ssZ” where Z is UTC

APIs in detail

TAP_GET_CUSTOMERS_API

Returns a list of reseller and end customer associated to Consumer’s identifier(clientId)

Base URI

https://cloud.stage.api.trimblecloud.com/cloud/TAPStoreAPIs/v1?request={"ProcName": "TAP_GET_CUSTOMERS_API","ProcRequester": "TAP"}

https://cloud.api.trimble.com/cloud/tapstoreapis/v1?request={"ProcName": "TAP_GET_CUSTOMERS_API","ProcRequester": "TAP"}

URI with search parameters

https://cloud.stage.api.trimblecloud.com/cloud/TAPStoreAPIs/v1?request={"ProcName": "TAP_GET_CUSTOMERS_API","ProcRequester": "TAP","request": {"region": "AMERICA","resellerName": "Trimble","endCustomerName": "","customerCreationDate": "2023-01-20"}}

https://cloud.api.trimble.com/cloud/tapstoreapis/v1?request={"ProcName": "TAP_GET_CUSTOMERS_API","ProcRequester": "TAP","request": {"region": "AMERICA","resellerName": "Trimble","endCustomerName": "","customerCreationDate": "2023-01-20"}}

Search Parameters details:

Success Response Payload:

{
  "statusCode": "Number",
  "status": "String",
  "uniqueId": "Number",
  "resellers": [
    {
      "name": "String",
      "billTo": [
        {
          "siteUseId": "Number",
          "address":  "String",
          "region":  "String",
          "autoRenewFlag":  "String"
        }
      ],
      "shipTo": [
        {
          "siteUseId": "Number",
          "address":  "String",
          "region":  "String"
        }
      ],
      "endCustomer": [
        {
          "name": "String",
          "shipTo": [
            {
              "siteUseId": "Number",
              "address": "String",
              "region": "String"
            }
          ]
        }
      ]
    },
    {
      "name": "String",
      "billTo": [
        {
          "siteUseId": "Number",
          "address": "String",
          "region": "String",
          "autoRenewFlag": "String"
        }
      ],
      "shipTo": [
        {
          "siteUseId": "Number",
          "address": "String",
          "region": "String"
        }
      ],
      "endCustomer": [
        {
          "name": "String",
          "shipTo": [
            {
              "siteUseId": "Number",
              "address": "String",
              "region": "String"
            }
          ]
        }
      ]
    }
  ]
}

Error Response Payload:

{
    "statusCode": "String",
    "status": "String",//”ERROR”
    "uniqueId": "Number",
    "errorMessage": "string"
}

Responses:

Usage Notes:

1. The API will validate the ‘ClientId’ (provided to the consumer during onboarding) against the Reseller account to get the information of the Reseller and associated End-Customers, which will be required for creating the order via API.
2. End-customer information will be obtained based on their association with the reseller.
3. In cases where no records are found for the parameters in the request, the API will respond with an error message ‘No data found’ accompanied by a status code of 400.
4. Only Active Reseller/End-Customer information will be retrieved by the API.
5. Valid values for region parameters are AMERICA, EUROPE, APAC , EMEA and SOUTH AFRICA

TAP_GET_MFG_MODELS_API

This API will be designed to handle requests for retrieving information about the Manufacturer and Models supported by Trimble. Upon request, users will be given a list of concatenated manufacturers and models, they will be separated by a double pipe (||) symbol (example Trimble||R12 Trimble is the Manufacture and R12 is the Model). Consumers of the API will have to separate the Manufacturer and Models before sending to “TAP_GET_ORDER_API” API.

Base URI

https://cloud.stage.api.trimblecloud.com/cloud/TAPStoreAPIs/v1?request={"ProcName": "TAP_GET_MFG_MODELS_API","ProcRequester": "TAP"}

https://cloud.api.trimble.com/cloud/tapstoreapis/v1?request={"ProcName": "TAP_GET_MFG_MODELS_API","ProcRequester": "TAP"}

URI with search parameters

https://cloud.stage.api.trimblecloud.com/cloud/TAPStoreAPIs/v1?request={"ProcName": "TAP_GET_MFG_MODELS_API","ProcRequester": "TAP","request": {"manufacturer":"Trimble"}}

https://cloud.api.trimble.com/cloud/tapstoreapis/v1?request={"ProcName": "TAP_GET_MFG_MODELS_API","ProcRequester": "TAP","request": {"manufacturer":"Trimble"}}

Search Parameters details:

Success Response Payload:

{
    "statusCode": "Number",
    "status": "String",
    "manufacturerModel": [
        "String1",
        "String2",
    ]
}

Error Response Payload:

{
    "statusCode": "Number",
    "status": "String",
    "errorMessage": [
        "String1",
        "String2",
    ]
}

Responses:

Usage Notes:

1. If the consumer of the API supplies a manufacturer value as an input parameter, the system will validate it against the Brand to Model mapping. Subsequently, the corresponding Manufacture||Models will be provided to the user.
2. In the absence of any input, the system will retrieve all eligible manufacturer models and send them as part of the response payload.
3. Should the request parameters yield no results, the API will respond with an error message “No data found” along with a status code of 400.

TAP_GET_PRODUCTS_API

This API has been developed to manage requests aimed at retrieving details concerning eligible part numbers for a specified customer and device model. Depending on the input provided by the consumer of the API, relevant services along with their details will be returned.

Base URI

https://cloud.stage.api.trimblecloud.com/cloud/TAPStoreAPIs/v1?request={"ProcName": "TAP_GET_PRODUCTS_API","ProcRequester": "TAP"}

https://cloud.api.trimble.com/cloud/tapstoreapis/v1?request={"ProcName": "TAP_GET_PRODUCTS_API","ProcRequester": "TAP"}

URI with search parameters

https://cloud.stage.api.trimblecloud.com/cloud/TAPStoreAPIs/v1?request={"ProcName": "TAP_GET_PRODUCTS_API","ProcRequester": "TAP","request": {"resellerbillToSiteUseId": "121212","serviceType": "RTX","model": "Trimble R2","partDescription": "Ag Regional"}}

https://cloud.api.trimble.com/cloud/tapstoreapis/v1?request={"ProcName": "TAP_GET_PRODUCTS_API","ProcRequester": "TAP","request": {"resellerbillToSiteUseId": "121212","serviceType": "RTX","model": "Trimble R2","partDescription": "Ag Regional"}}

Search Parameters details:

Success Response Payload:

{
    "statusCode": "Number",
    "status": "String",
    "customerName": "String",
    "products": [
        {
            "manufacturerModel": "String",
            "partNumber": "String",
            "partDescription": "String",
            "currencyCode": "String",
            "listPrice": "String",
            "durationOfItem": "String"
        },
        {
            "manufacturerModel": "String",
            "partNumber": "String",
            "partDescription": "String",
            "currencyCode": "String",
            "listPrice": "String",
            "durationOfItem": "String"
        },
    ]
}

Error Response Payload:

{
    "statusCode": "string",
    "status": "Error",
    "uniqueId": "string",
    "errorMessage": "string"
}

Responses:

Usage Notes:

1. The ‘Get Part Number’ functionality requires the resellerbillToSiteUseId, serviceType, and model as mandatory parameters for retrieving RTX Part Numbers. For the VRS Model, the Service Type is optional.
2. Upon receiving the resellerBillToSiteUseId, the system verifies the associated price list at the customer level. If a price list is assigned, the system proceeds to obtain the part numbers, conducting additional validation based on Model and Service Type. Subsequently, eligible parts are returned to the user.
3. Based on the resellerbillToSiteUseId API will share the geofence details for each item if it is eligible.
4. In case no results are found with the request parameters, the API returns an error message “No data found” along with the status code 400

TAP_GET_ORDER_API

This API fetches details about orders created by either TAP_CREATE_ORDER_API (using the uniqueId that was in response to the createOrder API) or TAP Store.

Base URI

https://cloud.stage.api.trimblecloud.com/cloud/TAPStoreAPIs/v1?request={"ProcName": "TAP_GET_ORDER_API","ProcRequester": "TAP"}

https://cloud.api.trimble.com/cloud/tapstoreapis/v1?request={"ProcName": "TAP_GET_ORDER_API","ProcRequester": "TAP"}

URI with search parameters

https://cloud.stage.api.trimblecloud.com/cloud/TAPStoreAPIs/v1?request={"ProcName": "TAP_GET_ORDER_API","ProcRequester": "TAP","request": {"uniqueID": "13331","serialNumber": "1234567890","poNumber": "HelloWorld"}}

https://cloud.api.trimble.com/cloud/tapstoreapis/v1?request={"ProcName": "TAP_GET_ORDER_API","ProcRequester": "TAP","request": {"uniqueID": "13331","serialNumber": "1234567890","poNumber": "HelloWorld"}}

Request Payload Field details:

Success Response Payload:

{
    "statusCode": "Number",
    "status": "String",
    "uniqueID":"Number",
    "orderHdr": {
        "orderCreationDate": "String",
        "orderNumber": "Number",
        "currencyCode": "String",
        "poNumber": "String",
        "customerOrderRef": "String",
        "billToCustomerName": "String",
        "shipToCustomerName": "String",
        "orderStatus": "String",
        "invoiceNumber": "Number",
        "invoiceAmount": "Number",
        "creditMemoNumber": "Number",
        "creditMemoAmount": "Number",
    },
    "orderLine": [
        {
            "lineNumber": "Number",
            "serviceType": "String",
            "manufacturerModel": "String",
            "serialNumber": "String",
            "partNumber": "String",
            "partDescription": "String",
            "serviceStartDate": "String",
            "serviceEndDate": "String",
            "durationOfService": "Number",
            "quantity": "Number",
            "ssoUserId": "String",
            "deviceKey": "String",
            "autoRenewalFlag": "String"
        }
    ]
}

Error Response Payload:

{
    "statusCode": "string",
    "status": "Error",
    "uniqueId": "string",
    "errorMessage": "string"
}

Responses:

Usage Notes:

1. To retrieve the status and order information of orders created by the TAP_CREATE_ORDER_API API, the uniqueId produced by the TAP_CREATE_ORDER_API API should be included in the subsequent request payload.
2. Consumers can also obtain order information for orders not created via the API and existing in the TAP Store by providing the serialNumber or poNumber parameters.
3. If the clientId of the customer for which order is placed and the clientId in the request doesn’t match, order info will not be retrieved. There will be an error as “No records found for requested parameters”.
4. If the order is being processed or is on hold, appropriate status will be populated in the orderStatus field that has status as ORDER_CREATION_INPROGRESS, ORDER_ON_HOLD, SUCCESS and ERROR.
5. If no results are found with the provided request parameters, the API will return an error message “No records found for requested parameters” with the status code 400.

TAP_GET_ACTIVATION_STATUS_API

This request will retrieve the activation status according to the customer’s input, and it will also provide the user with the passcodes associated with the provided serial number or order.

Base URI

https://cloud.stage.api.trimblecloud.com/cloud/TAPStoreAPIs/v1?request={"ProcName": "TAP_GET_ACTIVATION_STATUS_API","ProcRequester": "TAP"}

https://cloud.api.trimble.com/cloud/tapstoreapis/v1?request={"ProcName": "TAP_GET_ACTIVATION_STATUS_API","ProcRequester": "TAP"}

URI with search parameters

https://cloud.stage.api.trimblecloud.com/cloud/TAPStoreAPIs/v1?request={"ProcName": "TAP_GET_ACTIVATION_STATUS_API","ProcRequester": "TAP","request": {"orderNumber": "123456","serialNumber": "1234567890"}}

https://cloud.api.trimble.com/cloud/tapstoreapis/v1?request={"ProcName": "TAP_GET_ACTIVATION_STATUS_API","ProcRequester": "TAP","request": {"orderNumber": "123456","serialNumber": "1234567890"}}

Search Parameters Details:

Success Response Payload:

{
    "statusCode": "Number",
    "status": "String",
    "activations": [
        {
            "serialNumber": "String",
            "partDescription": "String",
            "serviceStartDate": "String",
            "serviceEndDate": "String",
            "activationRequestType":"String",
            "passcode": "String",
            "masterUnlock": "String",
            "masterUnlockQrcode": "String",
            "qrCodeLink": "String",
            "passcodeActivationStatus": "String",
            "passcodeActivationErrorMsg": "String",
            "otaActivationStatus": "String",
            "otaActivationErrorMsg": "String",
            "passcodeFileType": "String",
            "passcodeFileContent ": "String",
            "masterUnlockFileType": "String",
            "masterUnlockFileContent": "String"
        },
    ]
}

Error Response Payload:

{
    "statusCode": "string",
    "status": "Error",
    "uniqueId": "string",
    "errorMessage": "string"
}

Responses:

Usage Notes:

1. The system will validate whether there is an active or future subscription for the given serial number. If such subscriptions are available, the system will provide details for both the active and future subscriptions.
2. Similarly, the system will validate the other input parameters and return the response with the respective information to the customers.
3. If customers are sending only order number parameters in the request payload and if some of the lines within the order are canceled, then only active subscriptions details will be retrieved and sent in the response.
4. If customers are sending only order number parameters in the request payload and all subscriptions within the order are expired then the API will send an error “No active subscriptions found for the order” response in the payload.
5. If a customer is sending only serial number parameters in the request payload and it has active subscriptions, the API will return the corresponding data. However, if there are no active subscriptions (terminated, canceled, or expired) associated with the serial number then the API will send an error “No active subscriptions found for the serial number.”
6. If no results are found with the provided request parameters, the API will return an error message “No data found” with the status code 400.
7. Manual resend via BcApp will not be retrieved in this API.

TAP_CREATE_ORDER_API

Create New Order: Consumers can submit relevant information to commence the creation of an order for a specified customer and product.

Base URI

https://cloud.stage.api.trimblecloud.com/cloud/TAPStoreAPIs/v1

https://cloud.api.trimble.com/cloud/tapstoreapis/v1

URI with search parameters

NA

Request payload Parameters details:

Request Payload:

{
      "ProcName": "TAP_CREATE_ORDER_API",
      "ProcRequester": "TAP",
      "request": {
            "custPONumber": "String",
            "customerOrderRef": "String",
            "currencyCode": "String",
            "activationCountry": "String",
            "promoCode": "String",
            "billToSiteUseId": "Number",
            "shipToSiteUseId": "Number",
            "billToContactEmail": "String",
            "billToContactPhone": "String",
            "shipToContactEmail": "String",
            "shipToContactPhone": "String",
            "lines": [
                  {
                        "lineNumber": "Number",
                        "serviceStartDate": "Date (YYYY-MM-DD)",
                        "partNumber": "String",
                        "serialNumber": "String",
                        "serviceType": "String",
                        "manufacturerModel": "String",
                        "autoRenewal": "String (Y or N)",
                        "geofenceRegion": "String",
                        "activationType": "String",
                        "activationDate": "Date (YYYY-MM-DD)",
                        "activationTime": "String",
                        "couponNumber": "String",
                        "ssoUserEmailAddress": "String",
                        "simIncludedFlag":"String",
                        "simNumber": "Number (20 Digits)",
                        "deviceKey": "String",
                        "carrierName": "String"
                  }
            ]
      }
}

Success Response Payload:

{
    "statusCode": "Number",
    "status": "String",
    "uniqueId":"Number"
}

Error Response Payload:

{
    "statusCode": "Number",
    "status": "String",
    "errorMessage": [
        "String1",
        "String2",
    ]
}

Responses:

Usage Notes:

1. “Payment Term” and “Payment Method” which is available at Customer level in the TAP store will be used for order creation.

2. “Industry” which is available at Customer level in the TAP store will be used for order creation.

3. “Salesperson” which is available at Customer level in the TAP store will be used for order creation, if customer level is null then salesperson on the orders created will also be null.

4. “Price list” which is available at Customer level in the TAP store will be used for order creation. If there is no price list associated at customer level then the price list will be fetched based on the country to pricelist external mapping.

5. The system will validate the serial number for the RTX SerialNumbers based on the model. If a validation error occurs, the system will generate an error message.

6. If a timeout error is received from the createOrder API, the validation on the payload or the Order creation request is already started in the backend in the TAP Store. If a consumer tries to retry createOrder with the same serialNumber’s, API will throw an error stating that Order creation is in progress for the serialNumber please try after some some. Consumers can use getOrder API with serialNumber parameter to get the status of the order processing.

7. VRS serialNumber are case sensitive, if the serialNumber in the createOrder request payload already exists in TAP Store with a different case (Upper/Lower) we will convert the serialNumber received from the API createOrder request to match the case of the serialNumber in the TAP Store and trigger the order creation process. (Example: If in the TAP Store we have a serialNumber as “TESTApi01” and in the API request we are receiving serialNumber as “TestAPI01”. We will convert “TestAPI01” received from request payload to upper case and compare it with serialNumber in the store - “TESTApi01” (which will also be converted to upper case). If serialNumber matches we will create a Renewal Order for serialNumber “TESTApi01” which is already available in store, if all validations are successful).

8. The standard discount for items or customer level discounts will be verified and applied automatically.

9. AutoRenewal flag - There are some validations in the store for autorenewals if those are not satisfied then even if the consumer has sent the autoRenewal value as Y the order will not have autorenewal checkbox checked.

10. When a user wishes to redeem a coupon, the validation process for the coupon will be initiated and executed.

11. The promo code will undergo validation and will be applied at the order level.

12. If the activation date in the payload is past dated then the system will take the current system date as an activation Date.

13. If activationCountry is null then for activation ship_to address country will be picked as activation country.

14. The activation type will be validated, and subsequently, the activation date and time will be verified accordingly.

15. For VRS serial number validation, if the service type includes a SIM card, then the API will validate the SIM card details. Additionally, for all VRS lines, the user must provide a Device Key (Password), which will be validated by the system.

16. Geofence information will be retrieved based on the input provided by the customer.

17. The system will conduct standard validations including credit checks, hold status checks, and any other validations configured according to the setup in the TAP Store.

18. If Order is created in HOLD status, customers have to follow a process similar to the current process when they use the TAP IStore. The support team will take the necessary steps along with the customer to get the order hold released manually after which order confirmation and activation email will be sent. This will be reviewed in onboarding sessions and relevant documentation.

19. The subscriptions for AG 392 model that have not activated their first subscription via the RTX activation portal can not proceed to the next subscription purchase and have to first activate the initial subscription that was part of the bundle that was purchased using the RTX website at start.trimblertx.com/

20. For VRS, if ssoUserEmailAddress is a valid id API use this email Id while creating the order. If the ssoUserEmailAddress is not valid then API will use the latest valid ssoUserEmailAddress from the Store for creating the order. If there is no valid ssoUserEmailAddress available, the API will throw an error “ssoUserEmailAddress not found. Please contact Customer Care”.

21. Service End Date: It will be determined by the item unit of measure and the Service Start Date.

22. Service Start Date: The start date must not exceed 3 days from the current system date.

    1. If the user enters a date more than 3 days in the future, the system will generate an error.
    2. If for a serialNumber there is already an existing active service in TAP Store with the same ProductLine (refer #23 for mapping) the new order StartDate will be overridden by previous subscription end_Date+1. In the case of different ProductLine, the API will generate an error response to contact Customer care.
       1. Exception to the above point is XFill service and Demo parts (explained in above), for which even if there is an active service for other ProductLine exists in store, start_Date of the new order will be payload serviceStartDate.

23. Products to Product Line mapping

    Product	Product Line
    All CenterPoint products	CENTERPOINT
    All RangePoint products	RANGEPOINT
    All ViewPoint products	VIEWPOINT
    All FieldPoint products	FIELDPOINT
    All TPS - RTK 900 MHZ products	TPS - RTK 900 MHZ
    All XFILL products	XFILL

24. The current limit of the maximum number of order lines that can be processed from the API is 20 lines.

25. If the API offers the possibility of purchasing Demo below logic will be in place for DEMO:

    • For a given Serial Number for a specific Product Line the Demo is allowed once per lifetime. However, at the time of the request for Demo/trial the Serial number should not have a prior paid active or expired subscription of the same product line. If there is an existing active or expired paid subscription the API will restrict the order creation.

26. List of valid carrierName name:

    1. T-Mobile Germany
    2. Bell
    3. Rogers
    4. Telekom M2M
    5. Vodafone Germany over third party supplier Horn and Cosifan
    6. Telia Sweden
    7. Vodafone UK
    8. Vodafone UK over third party supplier Wireless Logic
    9. Orange UK over third party supplier Wireless Logic
    10. O2 UK over third party supplier Wireless Logic
    11. Orange Ireland Wireless Logic
    12. Unknown
    13. O2 Ireland Wireless Logic

TAP_RESEND_ACTIVATION_API

The functionality of this API is to resend activation information via OTA to the Device or the passcode will be sent in the email.

Base URI

https://cloud.stage.api.trimblecloud.com/cloud/TAPStoreAPIs/v1

https://cloud.api.trimble.com/cloud/tapstoreapis/v1

URI with search parameters

NA

Request Payload Field details:

Request Payload:

{
      "ProcName": "TAP_CREATE_ORDER_API",
      "ProcRequester": "TAP",
      "request": {
            "serialNumber": "String",
            "partNumber": "String",
            "orderNumber": "String",
            "customerOrderRef": "String",
            "activationDate": "String",
            "activationTime": "String"
      }
}

Success Response Payload:

{
    "statusCode": "Number",
    "status": "String",
    "uniqueId":"Number"
}

Error Response Payload:

{
    "statusCode": "Number",
    "status": "String",
    "errorMessage": [
        "String1",
        "String2",
    ]
}

Responses:

Usage Notes:

1. If the serial number has multiple active subscriptions and the customer wishes to retrieve a specific activation detail, the customer must provide the “partNumber” in the request payload.
2. The activation method will be fetched from the Passcode mapping (OTA, Send by Email)
3. If no results are found with the provided request parameters, the API will return an error message “No data found” with the status code 400.
4. NOTE: Upon Requesting a resend to activate the service through OTA through the resend functionalities it will take 15 minutes to complete the activation

Network Connectivity Error Messages

• Timeout - Httpcode - 504

{
    "fault": {
        "faultstring": "Gateway Timeout",
        "detail": {
            "errorcode": "messaging.adaptors.http.flow.GatewayTimeout"
        }
    }
}

• Timeout - Httpcode - 504 Gateway Time-out error:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<HTML><HEAD><META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<TITLE>ERROR: The request could not be satisfied</TITLE>
</HEAD><BODY>
<H1>504 ERROR</H1>
<H2>The request could not be satisfied.</H2>
<HR noshade size="1px">
CloudFront attempted to establish a connection with the origin, but either the attempt failed or the origin closed the connection.
We can't connect to the server for this app or website at this time. There might be too much traffic or a configuration error. Try again later, or contact the app or website owner.
<BR clear="all">
If you provide content to customers through CloudFront, you can find steps to troubleshoot and help prevent this error by reviewing the CloudFront documentation.
<BR clear="all">
<HR noshade size="1px">
<PRE>
Generated by cloudfront (CloudFront)
Request ID: usgappQVQPPwjCxYORAWaA7TYs2YUEcNuYU62ER-wv9CC7-hyRAU-A==
</PRE>
<ADDRESS>
</ADDRESS>
</BODY></HTML>

• Authentication Failure - Httpcode - 401 Unauthorized

{
    "fault": {
        "status": "401",
        "code": "900903",
        "message": "Authentication Failure",
        "description": "Access Token Expired"
    }
}

• Access is denied - 503 Service Temporarily unavailable.

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html>
<head>
    <title>503 Bad Request</title>
</head>
<body>
    <h1>Bad Request</h1>
    <p>The server will not answer such a request...</p>
    Access is denied
</body>
</html>

POSTMAN Configurations

1. Open Postman application (Download on your laptop or Login via WebBrowser from https://www.postman.com/downloads/

2. There are two options:

   • Create a Blank collection and continue to steps 3-9
   • Import this collection file: “TAPSTOREAPIs Stage Collection.postman_collection.json” that is shared by the Trimble team and proceed to obtain a token.

3. Click “Add a request” hyperlink to create a new request for getting the access token.

4. Rename the new collection as AccessToken and use url as below-

   NONPROD - https://stage.id.trimblecloud.com/oauth/token

   PROD - https://id.trimble.com/oauth/token

   • Select method as POST

   • In the Body add below parameters: Please refer below screenshot:

     grant_type client_credentials

     client_id Will be provided during OnBoarding

     client_secret Will be provided during OnBoarding

     scope tapstoreapis

     

5. After completing Step 4 click the send button and access_token should be generated. In case if the setup is not correct, an appropriate error message will be displayed. This access_token can be used to get the access to the API’s.

6. For Accessing the API’s. Create a new Request using the “Add request” option.

7. Select the appropriate method (GET or POST) and use the API url mentioned in the User Guide document.

8. Navigate to Headers and add new parameter Authorization and value as Bearer <<access_token generated in Step 5>>.

   And Click on Send button. If the request is successful http code 200 will be displayed along with the Response payload.

9. For POST requests like createOrder or resendActivation; request payload needs to be entered in the Body per below screenshot.