Overview API resources | Sage Active Developer

Caution

Before diving into this section, it’s crucial to begin with the Quick start guide.

This guide will walk you through the initial steps to set up and understand the Sage Active environments, your developer environment to define your applications, and the general logic of the API.

Starting with the Quick start will ensure you have a solid foundation for using the resources mentioned here effectively.

Objective

This section documents the Sage Active Public API V1 objects :

Business description of each resource,
resource fields,
list of authorized enumerations for fields with enumeration,
relationship with other resources,
mutations and queries,
constraints for deletion,
additional information on the use of certain fields.

Useful Information about GraphQL

In GraphQL, a mutation is an operation that changes data on the server.
It’s similar to the concept of HTTP POST (for creating), PUT PATCH (for updating), and DELETE (for removing) requests in RESTful APIs.
Mutations are used when you want to create, update, or delete data and always use the POSTmethod

On the other hand, a query is an operation used to retrieve data from the server.
It’s analogous to an HTTP GET request in RESTful APIs but, in GraphQL Queries use always the HTTP POSTmethod.

Both mutations and queries are defined in your GraphQL schema and are executed using the same mechanism.
The key difference lies in their intended purpose: mutations for data changes and queries for data retrieval.

Remember

Unlike RESTful APIs, there are no GET PUT PATCH DELETE methods utilized.

In GraphQL, whether dealing with mutations or queries, the HTTP POSTmethod is exclusively used.

This uniformity simplifies the request handling and aligns with the GraphQL standard practices.

Other important Points

To see samples of queries and mutations,
download the Postman collection: Quick start / 5. Test your first query in Postman.
Except userProfile and Organizations, it is necessary to mention in the header the X-TenantId (How to find?).
Except userProfile, User, Countries, ZipCodes, DocumentTypes and Organizations it is necessary to mention in the header the X-OrganizationId (How to find?).
In all cases, when making requests, it’s essential to include an Access Token in the header for authentication (How to find?).
Additionally, remember to always include a x-api-key in the header (How to find?).
Please note that the Sage Active Public API V1 is available for these Sage Active environnements.
For more information on the environments and their URLs, please refer to Key concepts / Environments.

Hot Chocolate

The Sage Active Public API V1 is a GraphQL API and is developed using Hot Chocolate.

Hot Chocolate is a GraphQL server for .NET that helps you create and deploy GraphQL APIs for your applications. It provides a variety of features to ease the creation of GraphQL schemas, manage requests and responses, and secure data. Hot Chocolate is an open-source library and can be used with a wide range of .NET frameworks for web development.

Hot Chocolate filter types

With Hot Chocolate filters, you can expose complex filter objects through your GraphQL API that translates to native database queries.

In the Postman collection: Quick start / 5. Test your first query in Postman, you will find examples of queries using all allowed filter operators.

Also, see in this documentation the guide dedicated to GraphQL Hot Chocolate concepts for Sage Active Public API V1 :
GraphQL Hot Chocolate concepts

Property Documentation Information

Rules Depending on the Current Legislation.

Sage Active exists in 3 legislations: FR, ES, or DE.
Depending on the current legislation, specific business rules may apply.
The tabs below will allow you to choose a legislation and see the specific rules that apply to that legislation on all pages.
At any time when you see these tabs, you will be able to change the legislation.

Here you will see elements specific to the FR legislation.

Here you will see elements specific to the ES legislation.

Here you will see elements specific to the DE legislation.

Mandatory property values

Properties whose value is mandatory when creating the resource are marked with an asterisk.
The enumerations, identified by bullets, are also fields whose value is mandatory but they are not identified by an asterisk since it will be necessary to choose one of the values of the enumeration.

Examples: socialName is mandatory and identifiable by an asterisk, status is implicitly mandatory because its value can only be NONE, DISABLED, ENABLED, GDPR_APPLIED, and does not need to be identified by a asterisk.

Fields	Type	Description	Length
socialName *The value of the field or object is mandatory	String	Name	70
status	NONE DISABLED ENABLED GDPR_APPLIED	Status

Unmodifiable system fields

Some fields cannot be assigned in creation or modification. They correspond to system information automatically assigned by the application and are identifiable by the letter S in red.
Example: id is non-modifiable system property.

Fields	Type	Description
idSSystem field that cannot be assigned	String	Id

Read-only fields

Some fields are read-only
They are identified by the letter R in red.
Example : countryName is a read-only field.

Fields	Type	Description
countryNameRThis field is read-only, its value cannot be assigned	String	country Name

Properties cannot be modified after creation

Some fields can be assigned during creation but can no longer be modified.
They are identified by the letter N in red.
Example: code is a property that can be assigned during creation but can no longer be modified afterwards.

Fields	Type	Description
codeNThe value of this field cannot be modified after the record is created	String	Account code

Not visible in the product interface

Some fields technically exist but are not visible from the product interface.
They are identified by the abbreviation Inv in red.
Example: code is a property that can be assigned during creation but can no longer be modified afterwards.

Fields	Type	Description
codeInvThis field is not visible in the product interface	String	Account code

Default value

Some fields can be automatically assigned a default value if they are not filled in.
They are identified by the letter D in red.
Example: code is a property that can be assigned during creation but can no longer be modified afterwards.

Fields	Type	Description
codeDIn creation, this field can have a default value automatically calculated	String	Account code

Field soon to be depreciated

A field may be deprecated in the near future and replaced by another, so it is recommended to anticipate when the depreciation will be active and to update the code accordingly. These fields are identified by the abbreviation SDepr in red.
Example: allowBlankOrDuplicatedIdentificationNumbersSDepr will soon be depreciated.

Fields	Type	Description
allowBlankOrDuplicatedIdentificationNumbersSDepr SDeprThis field will soon be deprecated, so please prepare for upcoming changes	boolean	always true

Depreciated field

A field can be deprecated and replaced by another, so it is imperative to update the code accordingly. These fields are identified by the abbreviation Depr in red.
Example: allowBlankOrDuplicatedIdentificationNumbers is deprecated and replaced by allowBlankIdentificationNumbers

Fields	Type	Description
allowBlankOrDuplicatedIdentificationNumbersSDepr DeprThis field is now deprecated, and we recommend using an alternative solution	boolean	always true