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.

Obtaining API Subscription Key and Access Token

To obtain the API subscription key and access token, 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 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 API Usage: Use this Workspace application to monitor the volume of API calls.

  

Making a Request

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.

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 Authorization headers in the Set Headers popup.