FAQ API

the Sage Active Public API is secured by Oauth 2.0 authentication.

The example of obtaining a token is explained:

• Quick start / 5. Test your first query in Postman
• Key concepts / API - Authenticate (web server app)

To have the right to call the APIs, the user must is a Sage Active user.

If this error occurs when using Sage Active Public API:

{
    "statusCode": 401,
    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
}

Check the following points :

• With the sample postman collection :
  Check that the subscriptionKey variable is the correct Subscription primary key or Subscription secondary key in your application.

• With your implementation or from Postman without the example collection :
  Check in the Header of your request if x-api-key is filled in with the correct Subscription primary key or Subscription secondary key in your application.

  

If this error occurs when using Sage Active Public API

{
    "statusCode": 401,
    "message": "JWT not present."
}

Check the following points :

• With the sample postman collection :
  Check that the accessToken variable is filled in with a valid access token.

• With your implementation or from Postman without the example collection :
  Check in the Header of your request if Authorization is filled in with the correct Bearer [access token] retrieved from the authentication of the current user.

  

If this error occurs when using Sage Active Public API

{
    "Message": "Bad Request",
    "Code": null,
    "Path": null,
    "Locations": null,
    "Extensions": null,
    "Exception": null,
    "SyntaxNode": null
}

Check the following points :

• With the sample postman collection :
  1. Check that the X-TenantId variable is filled in.
  2. Check that the X-OrganizationId variable is filled in.
• With your implementation or from Postman without the example collection :
  1. Check in the Header of your request if X-TenantId is filled in with a valid tenant Id.
  2. Check in the Header of your request if X-OrganizationId is filled in with a valid Organization Id.

  

  

In most REST APIs, it’s common to set the modificationDate to the creationDate upon object creation.
This simplifies filtering and sorting by a single field.

However, in a GraphQL API using HotChocolate like the Sage Active Public API, this approach is unnecessary due to the advanced filtering capabilities natively supported.

GraphQL allows you to apply multiple conditions on different fields in a single query, making it easy to filter both creationDate and modificationDate without having to merge the two fields.
You can use logical operators such as or or and and comparison operators like gt (greater than) to handle complex queries efficiently.

For example, with the Sage Active Public API you could filter objects created or modified after a certain date with a query like this:

Query

query ($currentDate : DateTime!) {
    customers (
        where:{
            or: [
                { creationDate: { gt:$currentDate } },
                { modificationDate: { gt: $currentDate } }
            ]
        }
    ) {
        edges {
            node {
                creationDate
                modificationDate
                id   
                socialName
                tradeName
                code
            }
        }
    }   
}

Variables

{
    "currentDate": "2024-10-17"
}

This flexibility eliminates the need for the “trick” of setting modificationDate to creationDate on creation, which is often used in REST APIs to avoid multi-condition queries. Instead, you can directly filter and sort on both dates with ease, offering greater precision and efficiency.

In Sage Active, payment terms used for calculating due dates are not natively linked to the sales invoice itself but rather to the customer.
You need to define the payment terms at the customer level.
Using the API, these terms can be set via createCustomer with paymentTermLines: Customer.

Then, when you create a sales invoice (either via the UI or API), the customer’s payment terms are used to calculate the due dates of the invoice.
It is currently not possible in Sage Active to set specific due dates for an invoice; the due dates are calculated based on the payment terms defined for the customer.
However, this calculation does not occur when the invoice is initially added but only after it is confirmed and posted.

API Steps:

1. Create the draft invoice: Use create Sales Invoice.
2. Confirm the invoice: Call close Sales Invoice.
3. Post the invoice: Use Post Sales Invoice.
   This posting action creates the accounting entry for the invoice and generates the due dates and amounts owed (referred to as open items in the API).

You can then retrieve these open items either by reading the sales invoice or directly via sales Invoice Open Items.
Payments can be applied using sales Invoice Open Items Settlement, which will automatically create the bank accounting entries.

Important Note:

Starting from the December 2024 version, it is now possible to specify the original invoice number (salesInvoices/operationalNumber) when adding a new invoice.

If the operationalNumber is provided, the invoice will automatically be in the Closed status, as an invoice with a number must be confirmed. There is no longer a need to call the close Sales Invoice action.

To generate the due dates:

• Call create Sales Invoice with the operationalNumber filled in.
• Proceed directly to Post Sales Invoice.

Invoices without an operationalNumber will still be imported in draft mode, and a number will be automatically assigned during the close Sales Invoice action.

The Postman collection includes updated examples for creating, confirming, and posting sales invoices: Postman Quickstart Guide.