Agilant Solutions, Inc.

TOGa Order API v2.0.2

Updated 11/8/2021

Overview

This API implements functionality for managing the ordering features of Agilant’s TOGa system through a RESTful HTTP transaction containing a JSON payload.

Beta/Test/Sandbox Environment
https://api.beta.agilantsolutions.com

Production Environment
https://api.agilantsolutions.com

• All requests and responses are formatted in JSON notation.
• Any whitespace in the request payload is disregarded. The JSON examples in this document are shown in a "pretty print" structure for easier legibility but JSON is not required to be in "pretty print" when performing the actual transactions.
• This API is intended for businesses-to-businesses (B2B) and must be implemented on your server-side. Requests to this API should never be sent from or processed by a user on the client-side.
• There are no data or structural differences between our beta and production environment. The only change you must make to initiate a request in production is that it must be sent to our production URL endpoint.
• All parameter names are case-sensitive and all values are handled with case sensitivity.
• Connection timeouts should be set to 15 seconds.
• Date and times in any inputs and outputs are formatted in ISO 8601 notation.
• For example: 1994-11-05 corresponds to November 5, 1994.
• For example: 1994-11-05T08:15:30-05:00 corresponds to November 5, 1994, 8:15:30 am, US Eastern Standard Time.
• For example: 08:15:30-05:00 corresponds to 8:15:30 am, US Eastern Standard Time.

• During the onboarding process, Agilant will provide you with two GUID keys which you are to store. One key is a public API key and the other key is a secret API key. You must ensure that the secret key is not disclosed anywhere in your code to the public.
• In the header of every transaction, you will need to provide a timestamp, your public key, and a signature of your transaction comprising of the timestamp field signed by your secret API key using the HMAC-SHA-256 cryptographic hash algorithm.
• The timestamp must be within 120 seconds (2 minutes) of the actual time or your transaction will be rejected. Therefore, you must ensure that your system time is maintained accurately within 2 minutes of the actual universal time.

Required Request Headers for Every Transaction

Sample Authentication Request Headers

Content-Type: application/json
Timestamp: 2019-01-02T17:34:52-05:00
Authorization: 1111AAAA-22BB-33CC-44DD-555555EEEEEE.Omjruf/UNd+rKEbjobxJzky84h6XOE9o9jz6/IKqc7Q=

Sample Authentication Request Headers

See the sample request using the sample information below.

• Using Sample Timestamp of: 2019-01-02T17:34:52-05:00
• Using Sample Public API Key of: 1111AAAA-22BB-33CC-44DD-555555EEEEEE
• Using Sample Secret API Key of: EEEE5555-DD44-CC33-BB22-AAAAAA111111

Sample PHP Code for Assembling Request Headers

<?php

$publicApiKey = '1111AAAA-22BB-33CC-44DD-555555EEEEEE';     // Replace with your Public API Key
$secretApiKey = 'EEEE5555-DD44-CC33-BB22-AAAAAA111111';     // Replace with your Secret API Key

$timestamp = date('c', time());
$headers = [
    'Content-Type: application/json',
    ('Timestamp: '.$timestamp),
    ('Authorization: '.$publicApiKey.'.'.base64_encode(hash_hmac('SHA256', $timestamp, $secretApiKey, true)))
];

?>

• All responses include two fields called success and error.
• The success field is a boolean data type which will return true or false for whether or not the transaction was successful.
• The error field will contain an intelligible string of the error details if one occurred or will be an empty value if no error occurred.
• Additionally, all transactions will respond with the following codes if they are successful:
• 200 OK for all GET, PUT, and DELETE requests.
• 201 CREATED for all POST requests.
• When determining for whether or not the transaction was successful, you should check that the HTTP response code is 200 OK or 201 CREATED and/or check that the success value is set to true.

Sample Response Headers

Content-Type: application/json
Content-Length: 354

Response Headers for Every Transaction

<?php

$endpoint = 'https://api.beta.agilantsolutions.com';        // SANDBOX ENDPOINT
//$endpoint = 'https://api.agilantsolutions.com';           // PRODUCTION ENDPOINT

$publicApiKey = '1111AAAA-22BB-33CC-44DD-555555EEEEEE';     // Replace with your Public API Key
$secretApiKey = 'EEEE5555-DD44-CC33-BB22-AAAAAA111111';     // Replace with your Secret API Key

$method = 'GET';
$route = '/provider';
$payload = '{"providers":["C638C170-3EC1-4DF2-942C-1D1C3AD74FBC","16527A9E-4048-452CA8DF-605E1038A313"]}';

//////////////////////////////////////////////////

$url = ($endpoint . $route);
$timestamp = date('c', time());
$headers = [
    'Content-Type: application/json',
    ('Timestamp: '.$timestamp),
    ('Authorization: '.$publicApiKey.'.'.base64_encode(hash_hmac('SHA256', $timestamp, $secretApiKey, true)))
];
$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$responseBody = curl_exec($ch);
$responseCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo 'responseCode=' . $responseCode . '<br>';
echo 'responseBody=' . $responseBody;

///////////////////////////////////////////////

/*

EXAMPLE OUTPUT:

responseCode=200
responseBody=
{
    "success": true,
    "error": "",
    "providers": [
        {
            "providerId": "C638C170-3EC1-4DF2-942C-1D1C3AD74FBC",
            "providerName": "Porch",
            "avgRating": 4.3,
            "reviews": [
                {
                    "name": "Jane Doe",
                    "rating": 4.7,
                    "review": "I like this service very much!"
                },
                {
                    "name": "John Smith",
                    "rating": 3.5,
                    "review": "I was quite happy!"
                }
            ]
        },
        {
            "providerId": "16527A9E-4048-452C-A8DF-605E1038A313",
            "providerName": "Hello Tech",
            "avgRating": 3.1,
            "reviews": [
                {
                    "name": "Mary Doe",
                    "rating": 2.7,
                    "review": "I was not happy with this service.
                },
                {
                    "name": "Jim Dean",
                    "rating": 4.1,
                    "review": "This looks really nice!"
                }
            ]
        }
    ]
}
*/

Enumerated Lists

Defines the type of order

Values

Orders

Use this request to retrieve the details of an order

• The {orderNumber} value in the route is an integer which references the order number keyed in by the user.

Sample Request

GET /order/12345678

Content-Type: application/json
Timestamp: (See Authentication & Authorization)
Authorization: (See Authentication & Authorization)

Input/Request Parameters

No input/request parameters are accepted.

Sample Response

HTTP/1.1 200 OK

{
    "success" : true,
    "error" : "",
    "orderNumber" : 12345678,
    "firstName" : "John",
    "lastName" : "Smith",
    "emailAddress" : "jsmith@testco.com",
    "associateId" : "0975312",
    "storeNumber" : "758246",
    "type" : "NEW"
}

Output/Response Parameters

Typical Response Codes

Use this request to create a diagnostic record to an order.

• The {orderNumber} value in the route is an integer which references the order number keyed in by the user.

Sample Request

POST /order/12345678/diagnostic

Content-Type: application/json
Timestamp: (See Authentication & Authorization)
Authorization: (See Authentication & Authorization)

{
    "resultCode" : "Has A/V, No problem(s) found",
    "windowsUpgradeEligibility" : true,
    "document" : "JVBERi0xLjcKCjQgMCBvYmoKKElkZW50aXR5KQplbmRvYmoKNSAwIG9iagooQWRvYmUpCmVu...",
    "systemInformation" : "{\n\"Win32_BIOS\":\n{\n \"BiosCharacteristics\":\"{7, 9, 11..."
}

Input/Request Parameters

Sample Response

HTTP/1.1 201 OK

{
    "success" : true,
    "error" : "",
    "orderNumber" : 12345678
}

Output/Response Parameters

Typical Response Codes