Getting Started

This document provides instructions on how to start with the Financials GraphQL API.

Prerequisites

Before you can call the Financials GraphQL API, you need to obtain an API subscription key and an instance-specific access token or HMAC key.

Obtaining API Subscription Key and Access Token or HMAC Key

To obtain the API subscription key and access token or HMAC key, follow these steps:

1. Navigate to the workspace.
2. Create a new tab.
3. Click on the Add App button.
4. Locate ERP Application Register section. ERP Application Register has to be explicitly enabled for your organisation (if not already enabled). Note that only organisation administrator users can access the ERP Application Register.

6. Use the following Workspace applications available in the ERP Application Register:

• ERP Subscription Manager: Use this Workspace application to create API subscriptions, get API subscription keys, and regenerate API subscription keys. It is recommended to segregate API subscriptions per application/service/system that calls our APIs. Each subscription has two keys to allow key rotation.

  

• ERP API Usage: Use this Workspace application to monitor the volume of API calls.

  

• ERP Token Generator: Use this Workspace application to get your instance-specific access token. It is recommended to generate a new token for every application/service/system that calls our APIs. Tokens can have a maximum lifetime of 1 year, after which you need to generate a new token.

  

  warning

  Tokens have a maximum lifetime of 365 days, depending on the settings at the time of generation. Once a token expires, it must be manually regenerated and updated on the client side. Failure to do so will result in API calls failing after the token has expired.

• ERP HMAC Key Generator: Use this Workspace application to get your instance-specific HMAC key, along with a Tenant ID and a Key ID. It is recommended to generate a new key for every application/service/system that calls our APIs.

  

Regenerating an Access Token

When a token is nearing expiration or has already expired, the ERP Token Generator will highlight it with a yellow or red background. A red background indicates the token is expired and cannot be used for requests. To regenerate a token, simply select it and click the Regenerate Token button. A popup will display your new token, which will have the same lifetime as the original.

Expiring access token and the Regenerate Token button:

Alternatively, you can also regenerate the token by sending a POST request to the token regeneration endpoint: https://api.erp.accessacloud.com/app-register/api/Tokens/regenerate, including your old Access Token in the Authorization header.

Making a Request using Access Token

Once you have obtained your API subscription key and access token, you can make a request to the Financials GraphQL API.

Here's an example of how to make a request:

curl -X POST -H "Content-Type: application/json" \
    -H "Ocp-Apim-Subscription-Key: <Your-API-Subscription-Key>" \
    -H "Authorization: Bearer <Your-Access-Token>" \
    -d '{ "query": "{debtors { masterRecords { customers { records { items { customerDetails { code name } } } } } }}" }' \
    https://api.erp.accessacloud.com/financials-graphql

Replace <Your-Subscription-Key> and <Your-Access-Token> with your actual subscription key and access token.

This request will return a list of customers, with each item's code and name.

Making a Request using HMAC Key

Before being able to make a request to the Financials GraphQL API, you need to generate a signature using the HMAC key you previously obtained. To be able to generate a signature, you need to concatenate the following variables (all converted to lowercase): <Tenant-Id>, <Path>, <Query-String>, <Subscription-Key>, and <Timestamp>.

• <Tenant-Id>: Your assigned Tenant ID.
• <Path>: The path portion of the request URL (for example, /Financials-vNext/graphql).
• <Query-String>: The query parameters from the request URL, if any (for example, ?param1=value1&param2=value2). If there are no query parameters, use an empty string.
• <Subscription-Key>: Your API subscription key.
• <Timestamp>: The current timestamp in UTC format (for example, 2025-02-03T12:00:00Z). The timestamp must be within 5 minutes before or after the current time to be considered valid.

Concatenate these values in the order shown above, then sign the resulting string using your HMAC key to generate the signature.

Below is an example of a C# code that can be used to generate the signature:

string subscriptionKey = "<Your-Subscription-Key>";
string tenantId = "<Your-Tenant-Id>";
string requestPath = "<Path>"; // e.g., "/Financials-vNext/graphql"
string queryParams = ""; // e.g., "?param1=value1&param2=value2" or empty string if none
string timestamp = "<Timestamp>"; // e.g., "2025-02-03T12:00:00Z"
string hmacKeyHex = "<Your-HMAC-Key>";

string messageToSign = tenantId.ToLower() + requestPath.ToLower() + queryParams.ToLower() + subscriptionKey.ToLower() + timestamp.ToLower();
byte[] hmacKeyBytes = Convert.FromHexString(hmacKeyHex);
using var hmac = new HMACSHA512(hmacKeyBytes);
byte[] signatureBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(messageToSign));
string signatureHex = Convert.ToHexString(signatureBytes);

Console.WriteLine($"Generated HMAC Signature: {signatureHex}");

Once you have generated the signature, you can make a request to the Financials GraphQL API.

Here's an example of how to make a request:

curl -X POST -H "Content-Type: application/json" \
    -H "Ocp-Apim-Subscription-Key: <Your-API-Subscription-Key>" \
    -H "X-Signing-Key-Id: <Your-HMAC-Key-Id>" \
    -H "X-Tenant-Id: <Your-Tenant-Id>" \
    -H "X-Timestamp: <Timestamp>" \
    -H "Authorization: HMAC <Generated-Signature>" \
    -d '{ "query": "{debtors { masterRecords { customers { records { items { customerDetails { code name } } } } } } }" }' \
    https://api.erp.accessacloud.com/financials-graphql

Replace <Your-Subscription-Key>, <Your-HMAC-Key-Id> and <Your-Tenant-Id> with your actual Subscription Key, HMAC Key ID and Tenant ID. Replace <Timestamp> with the same timestamp you used when generating the signature. Replace <Generated-Signature> with the signature you previously generated.

This request will return a list of customers, with each item's code and name.

Handling the Response

The response from the Financials GraphQL API will be a JSON object. Here's an example of a typical response:

{
  "debtors": {
   "masterRecords": {
    "customers": {
      "records": {
       "items": [
        {
          "customerDetails": {
           "id": "1",
           "name": "Customer 1"
          }
        },
        {
          "customerDetails": {
           "id": "2",
           "name": "Customer 2"
          }
        }
        // More customers...
       ]
      }
    }
   }
  }
}

Each item in the items array represents a customer, with its id and name.

Explore our API

API can be tested live using API Reference. To understand how interact with our API in order to perform read and write operations please refer to: Queries, Mutations.

When testing/exploring API, make sure you set the Ocp-Apim-Subscription-Key and all the mandatory headers in the HTTP Headers tab from the Connection Settings popup.