API Gateway Integration

The purpose of the NovAtel e-Commerce System (NeCSClosed NovAtel e-Commerce System) RESTClosed Representational State Transfer APIClosed Application Programming Interface is to facilitate electronic transactions to purchase and manage NovAtel products and services. This section provides the basic information needed to integrate your application with the NeCS REST API via the Azure API GatewayClosed The Azure API Gateway provides a secure end-point for customers accessing NovAtel REST API services..

Overview

The REST API Gateway Request is a two step process.

  1. Use your client ID and client secret to generate an API access token. (refer to API Subscriptions, Client ID and Client Secret)

  2. Send an API request with the access token.

API Subscriptions, Client ID and Client Secret

A new customer needs to subscribe to the Hexagon A&P API Gateway. Hexagon A&P supports two environments:

  • User Acceptance Test (UAT) Gateway: https://ecommportaluat.hexagonap.com/

    This portal is used to support integration and development testing activities. This is a sandbox environment and will not result in any product charges.

  • Production Gateway: https://ecommportal.hexagonap.com/

    This portal connects to the production Hexagon A&P NeCS environment. Any transactions completed on this interface will result in actual production transactions, potentially resulting in product invoicing.

The following overview focuses on guiding you through setting up and using the UAT environment. After you have successfully integrated to the UAT system and are comfortable with the functionality, you can repeat the setup on the production system.

A new customer needs to sign-up to the UAT Gateway and subscribe to the available REST API products for the development. Refer to API Gateway Quick Start Guide for instructions about signing up and subscribing to APIs.

After successfully subscribing, you will be assigned a client ID and client secret by the NovAtel support team. The client ID and client secret are used to authenticate an API user through https://login.microsoftonline.com. Upon successful login, you will receive an access token.

Client IDs and client secrets are different between the UAT API Gateway and Production API Gateway.

The assigned client ID and client secret are provided in a JSON format file (UAT.postman_collection.json).

To open the JSON file, download and install postman from https://www.postman.com/downloads/

Use the postman Import function to upload the JSON file. The client ID and client secret will be imported with the correct request format.

User Authentication to get Access Token (Postman Example)

For concept proofing purposes, you can use Postman to send login requests.

  1. Import the client ID and client secret JSON file into Postman.

  2. Click Send. It will generate an access token.

  3. To see the raw request/response message, click Console | Show raw log.

Postman provides a way to quickly test and see the request/response raw message. It helps you to develop your M2MClosed Machine-to-Machine client and send login messages to get access tokens from https://login.microsoftonline.com. The value of the access token is in the access_token field in the response message. The access token expires after one hour, so you will need to generate new ones on a regular basis. This can be automated in your application communicating with our system.

Send API Request Through Azure Gateway (Use the Azure API Test Function)

For concept proofing purposes, you can send a request to https://ecommportaluat.hexagonap.com/ using the generated access token.

  1. Login to the Azure Gateway website, using one of the URLs above.

  2. Select API.

  3. Select one of the API methods and click Try It.

  4. The following parameters need to be input:

    HTTP Headers (for all API methods):

    CustomerNumber: the customer number assigned by NovAtel.

    UserName: the email address of the API account.

    Authorization: the value of Access_Token returned in the authentication step.

    Subscription key: subscription key should be selectable in the page, if not, please contact NovAtel support to approve your subscription. Once selected, a subscription key, Ocp-Apim-Subscription-Key, will be populated.

  5. Depending on the API method definition, you may input other parameter(s) such as PSN.

  6. Click the Send button in the bottom of right hand panel. An API request will be sent to the Gateway and a response will be received. The request message and response message will be displayed.

There are 2 types of REST APIs in the gateway:

  • REST GET: Primarily used for retrieving data from a server.

  • REST POST: Used for sending data to the server with the intent to create or update a resource.

You can review the raw HTTP request and response message. The information can help you to build your REST API client application.

HTTP Request Sample Message

 

HIDE SECRETS COPY

 

GET https://ecommuat.hexagonap.com/receivermmt1/v1/VMHR18040051C/information HTTP/1.1

CustomerNumber: UUABCDE

UserName: Tony.Shu@hexagon.com

Authorization: eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Ii1LSTNROW5OUjdiUm9meG1lWm9YcWJIWkdldyJ9.eyJhdWQiOiIzNmE1N2Y3MS01M2ZjLTQ2ZDMtOTU2MS0wNzE3YzI5YjYyZTUiLCJpc3MiOiJodHRwczovL2xvZ2luLm1pY3Jvc29mdG9ubGluZS5jb20vMWZlMzcxMmMtNzc3NC00OTRiLTg1MjEtZDZhODE1MjM5MTk0L3YyLjAiLCJpYXQiOjE2ODY2ODk5NTEsIm5iZiI6MTY4NjY4OTk1MSwiZXhwIjoxNjg2NjkzODUxLCJhaW8iOiJFMlpnWUpDZUtxRElXdUV6L2VQcE13dnY5Vis4THhCN2dmbVl1b08xYy8rcDBPOHplWG9BIiwiYXpwIjoiMTI2MDMxNDItOGJkNS00MTYyLThhM2EtYjA1YzZkMTFiNzQ4IiwiYXpwYWNyIjoiMSIsIm9pZCI6IjRkOTM0MmFjLTk1MGYtNDc2ZC05Y2U2LWQxMjhjNmQ4MzVmOSIsInJoIjoiMC5BUjBBTEhIakgzUjNTMG1GSWRhb0ZTT1JsSEZfcFRiOFU5TkdsV0VIRjhLYll1VWRBQUEuIiwicm9sZXMiOlsiQWNjZXNzLkJVWSJdLCJzdWIiOiI0ZDkzNDJhYy05NTBmLTQ3NmQtOWNlNi1kMTI4YzZkODM1ZjkiLCJ0aWQiOiIxZmUzNzEyYy03Nzc0LTQ5NGItODUyMS1kNmE4MTUyMzkxOTQiLCJ1dGkiOiJnTnFfRmpaUWgwdWJycGlVVGJKUEFBIiwidmVyIjoiMi4wIn0.ZJrBaG7LGGc-4hu2LbY1jbZn7M7yqg9OGq4U2LOOKCOjk55Lk9cmFL93KuuMuhMuJZgXfz1c2yTEKXU5OzyonWGkw3h2m462yohhw0qUQy9RD7u2RfdjtaAbEMgKRLMV4GYo0PohdmRLb3x5hXbQk1CJ7KJn8BN8bTQdC-YIc4UT-WLeBcxyhdRhq-HYKEhm30QPV0OskAu30XBPoOeSxTJUzQ81g1363WlmRff6fgXqH8Oxw3ktZkhkzCC0xYd3XBWrozIEEURbmJYEyoBCiMESJilI5eWXRbojYZwbVFCn_dP243aj8sCTOgbmOB6eGuBbEW1ArNqhAexj-tEr-w

Cache-Control: no-cache

Ocp-Apim-Subscription-Key: ***********************

HTTP response

HTTP/1.1 200 OK

 

content-length: 764

content-type: application/json; charset=utf-8

date: Tue, 13 Jun 2023 21:04:56 GMT

strict-transport-security: max-age=2592000

x-powered-by: ARR/3.0

 

{

    "receiverDetails": [{

        "psn": "VMHR18040051C",

        "description": "OEM7700 Card",

        "hardwarePlatform": "OEM7700",

        "hardwareRevision": "1.01",

        "warrantyExpiry": "2020-02-27T17:16:38Z",

        "currentPaidModel": "FFNRNNTBN",

        "paidModels": [

            "FFNRNNTBN",

            "CDNRNNTBES1",

            "CDNRNNTBN",

            "CFNRNNTBN",

            "DDNLNNTMN",

            "DDNPNNTMN",

            "DDNRNNTBN",

            "DDNXNNTBN",

            "FDNLNNTBN",

            "FDNRNNTBN",

            "GSNNNNNNN"

        ],

        "testReceiverType": "InternalUse"

    }],

    "responseDetails": {

        "requestId": "dc771f17-ce71-4c58-8256-9f615ad334cf",

        "responseCode": 0,

        "responseMessage": "Request Completed Successfully"

    }

}