NAV Navbar
JSON
Agilant Solutions, Inc.
TOGa Order API v2.0.2
Updated 11/8/2021

Overview

Introduction

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

Endpoints

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


Production Environment
https://api.agilantsolutions.com

Structure & Schema

Authentication & Authorization

Required Request Headers for Every Transaction

Header FieldTypeDescription
Content-TypeStringMust be set to application/json
TimestampStringThe current timestamp of your transaction in ISO 8601 notation.
Example: 2019-01-02T17:34:52-05:00
AuthorizationStringConcatenated string of your public API key, followed by a literal period (.), followed by your signature. Your signature is your timestamp value, signed using your secret API key through the HMAC-SHA-256 cryptographic hash algorithm in a raw binary format and then Base64 encoded.
Format: {publicKey}.{signatureOfTimestampUsingSecretKey}

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.

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$secretApiKeytrue)))
];

?>

Responses

Sample Response Headers


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

Response Headers for Every Transaction

Header FieldTypeDescription
Content-TypeStringWill always be set to application/json
Content-LengthIntegerLength of the response payload in bytes.

Response Codes

HTTP CodeMeaningRequired Action
200 OKThe transaction was successful.
(Applicable to GET, PUT, and DELETE requests)
N/A
201 CREATEDThe record was successfully created.
(Applicable only to POST requests)
N/A
400 BAD REQUESTA logic error was encountered or the request was missing a required parameter.Review the returned errors and correct the issue.
401 UNAUTHORIZEDAuthentication or authorization of the request headers failed.Review the returned errors and correct the issue in the Request Header.
403 FORBIDDENAccess was denied when trying to retrieve data for a record.Ensure you have proper authorization to access the record.
404 NOT FOUNDThe record could not be located.Ensure you have requested a record that exists.
405 METHOD NOT ALLOWEDThe requested action is not supported.Ensure that you are calling a valid API method and using the correct method and route.
408 REQUEST TIMEOUTA connection error was encountered and the request may or may not have completed successfully.Retry the transaction and/or perform other GET requests to check if the previous request succeeded.
422 UNPROCESSABLE ENTITYThe request structure is correct and the server understands the request but is unable to process the transaction. This typically can occur in a POST request if the record being created or changed already exists.Ensure you are not trying to create the same record that was already processed in a previous transaction.
500 INTERNAL SERVER ERRRORAn unexpected internal server error was encountered.Contact the administrator. Further analysis and debugging may need to be performed.
502 BAD GATEWAYA temporary network issue occurred when receiving the request. This is rare and typically caused by a very temporary network issue which should resolve within a few seconds.Retry the transaction or try again later. If the problem persists, please contact the administrator.
504 GATEWAY TIMEOUTA network issue occurred when receiving the request.Retry the transaction or try again later. If the problem persists, please contact the administrator.

PHP Example

<?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$secretApiKeytrue)))
];
$ch curl_init($url);
curl_setopt($chCURLOPT_CUSTOMREQUEST$method);
curl_setopt($chCURLOPT_POSTFIELDS$payload);
curl_setopt($chCURLOPT_RETURNTRANSFERtrue);
curl_setopt($chCURLOPT_SSL_VERIFYPEERfalse);
curl_setopt($chCURLOPT_HTTPHEADER$headers);
$responseBody curl_exec($ch);
$responseCode curl_getinfo($chCURLINFO_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

Order Types

Defines the type of order

Values

ValueDescription
NEWThe order is for a new computer setup.
EXISTINGThe order is for an existing computer setup.
REFURBThe order is for a computer refurbishment.

Orders

Retrieve an OrderGET /order/{orderNumber}

Use this request to retrieve the details of an order

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

FieldTypeDescription
successBooleanWill return true or false for whether or not the transaction was successful.
errorStringIntelligible string of the error that occurred. Will be empty if no error occurred.
orderNumberIntegerThe order number this transaction is referring to.
firstNameStringThe first name on the account.
lastNameStringThe last name on the account.
emailAddressStringThe email address on the account.
associateIdStringThe associate number who initiated the order.
storeNumberStringThe store number the order originated in.
typeStringThe type of order the record is referring to. See Order Types for all possible values.

Typical Response Codes

HTTP CodeMeaningRequired Action
200 OKThe transaction was successful.
(Applicable to GET, PUT, and DELETE requests)
N/A
400 BAD REQUESTA logic error was encountered or the request was missing a required parameter.Review the returned errors and correct the issue.
404 NOT FOUNDThe record could not be located.Ensure you have requested a record that exists.

Create an Order DiagnosticPOST /order/{orderNumber}/diagnostic

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

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

FieldTypeDescription
resultCodeStringResult code from the diagnostic performed.
windowsUpgradeEligibilityBooleanSet as true to mark this device as eligible for an upgrade to the next Windows version, false if the device is not eligible.
documentStringThe reference to the results document. This value may be a URL linking to the document file OR a Base64-encoded string of the document file.
systemInformationStringThe system information details

Sample Response

HTTP/1.1 201 OK

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

Output/Response Parameters

FieldTypeDescription
successBooleanWill return true or false for whether or not the transaction was successful.
errorStringIntelligible string of the error that occurred. Will be empty if no error occurred.
orderNumberIntegerThe order number this transaction is referring to.

Typical Response Codes

HTTP CodeMeaningRequired Action
201 CREATEDThe record was successfully created.
(Applicable only to POST requests)
N/A
400 BAD REQUESTA logic error was encountered or the request was missing a required parameter.Review the returned errors and correct the issue.
404 NOT FOUNDThe record could not be located.Ensure you have requested a record that exists.