REST API for developers

This topic is an overview of all ins & outs of the REST API.

General

AFAS offers by default an API to exchange data for all customers. This API is reactive, has dynamic endpoints for getting data and fixed endpoints for receiving data. You can read how you call the API and which options and limitations there are in this description.

Please note:

You will find all endpoints for connectors on the central page URLs of REST Services.

Requirements

To call the API, you need and environment ID and token. The AFAS environment administrator with whom you make the connection can provide this information.

Protocols

The AFAS Software API can be accessed through both REST(JSON) and SOAP(XML).

TLS 1.2 is required for all requests.

Tools

AFAS has its own testing platform for the development and testing of requests, that is, AFAS Connect. AFAS Connect is available to everybody who creates an account. This account is not linked to other AFAS accounts.

Call

For a call, you need the following:

• Token
• Environment ID
• Environment type

Endpoints

The endpoint basis consists of the following elements:
https://OmgevingsID.webservicetypeOmgevingstype.online

Please note:

You will find all endpoints for connectors on the central page URLs of REST Services.

Header

The header is only used for authorisation.

Key: "Authorization"

Value: "AfasToken PHRva2VuPjx2ZXJzaW9uPjE8L3ZlcnNpb24+PGRhdGE+NTQ3NDAwOTM4MzI0OTYwODE4NDU0Nz
RhYmNkZWZnaGlqa2xtbm9wcTc0MDA5MzgzMjQ5NjA4MTg0MTIzNDEyNzwvZGF0YT48L3Rva2VuPg=="

The value is the Base64 string of the token including XML tags. For this, the following applies AfasToken + space.

Example: token conversion

Token

<token><version>1</version><data>54740093832496081845474abcdefghijklmnopq740093832496081841234127</data></token>

Base64 string:

PHRva2VuPjx2ZXJzaW9uPjE8L3ZlcnNpb24+PGRhdGE+NTQ3NDAwOTM4MzI0OTYwODE4N
DU0NzRhYmNkZWZnaGlqa2xtbm9wcTc0MDA5MzgzMjQ5NjA4MTg0MTIzNDEyNzwvZGF0YT48L3Rva2VuPg==

Meta information request

The meta information request gives information about the environment, the available GetConnectors and the available UpdateConnectors.

URL of the request: https://12345.rest.afas.online/ProfitRestServices/metainfo

Header: "Authorization: AfasToken PHRva2VuPjx2ZXJzaW9uPjE8L3ZlcnNpb24+PGRhdGE+NTQ3NDAwOTM4MzI0O
TYwODE4NDU0NzRhYmNkZWZnaGlqa2xtbm9wcTc0MDA5MzgzMjQ5NjA4MTg0MTIzNDEyNzwvZGF0YT48L3Rva2VuPg=="

OTP

AFAS offers the option of using a One Time Password (OTP) instead of a token. This is useful in situations in which users must register in an application.

Also see:

• Generate a token for the Profit Rest Services

GetConnector - REST

An external application can get records from the Profit database with a GetConnector. There are dynamic endpoints for this that you can use to get configured datasets yourself. An AFAS administrator can compile these GetConnector definitions.

You can only call GetConnectors that have been activated in the App connector.

Result example:

{

"skip": 0

"take": 1

"rows": [

{

"BcCo": "1000001"

"Type": "Organisation"

"SearchName": "AFAS Software B.V."

}

]

}

Filtering

A GetConnector definition may contain an integrated filter, for example, the current year. In addition, you can apply a filter per request. For compiling the filter, the best option is to use the tools that are available on connect.afas.nl.

The following filter operators are available:

These operators can be applied in the following way:

AND Filter(OPERATOR)/connectors/XXXXX?filterfieldids=fieldid,fieldid&filtervalues=value,value&operatortypes=type,type

OR Filter(OPERATOR)/connectors/XXXXX?filterfieldids=fieldid;fieldid&filtervalues=value;value&operatortypes=type;type

Sorting

URL/connectors/GetConnectorName?orderbyfieldids=TechnicalFieldId

The Sort operator can be used to implement sorting with regard to data. Select a code value such as an ID for this. This includes a good index. The sorting is set to ‘Ascending’ by default. By entering a minus sign (‘-‘) in front of the field based on which you are filtering, you can sort in a ‘Descending’ manner.

Skip/Take

URL/connectors/GetConnectorName?skip=0&take=20

The Skip/Take operator offers the option of getting data in bits. If the operator is not included, the first 100 lines will always be returned. If you set both skip and take to '-1’, all lines will be retrieved (we do not recommend this!).

Always use skip/take in combination with sorting. The sorting may otherwise change during the retrieval of the data.

UpdateConnector - REST

An external application can use an UpdateConnector to add, change or delete records in the Profit database (options vary per connector). Also see the overview of all UpdateConnectors.

You can only call UpdateConnectors that have been activated in the App connector.

Available methods:

• POST: add data (INSERT)
• PUT: change data (UPDATE)
• DELETE: delete data

You must provide special characters (e.g. é, ü and ï) in the UTF-8 format. If you do not, Profit will show a question mark instead of, for example, é, ü or ï.

Meta information

The meta information of an UpdateConnector can be retrieved via connect.afas.nl.

1. Log into connect.afas.nl
2. Go to REST/JSON
3. Enter the correct data in (Environment ID, type and token)
4. Select the UpdateConnector
5. Click MetaInfo.

   

Combination of PUT and POST

You can change and add data in one call. This only applies to connectors that consists of a main record and subrecords.

It is not possible to activate both to add more than two elements in a web service address.
It is therefore not possible to also add a postal address in relation to the example below. A separate REST request must be executed here.

Possible:
https://xxxxx.rest.afas.online/ProfitRestServices/connectors/KnPerson/KnBasicAddressAdr

Not possible:
https://xxxxx.rest.afas.online/ProfitRestServices/connectors/KnPerson/KnBasicAddressAdr/KnPerson/KnBasicAddressPad

Response after POST

After a POST, a value is returned: the response. See also the explanation below.

Endpoints

POST/PUT = /connectors/{connectorid}
POST/PUT with subelements = /connectors/{connectorid}/{*subelementids}
DELETE: /connectors/{connectorid}/{elementname}/{fieldids}/{*values}

Example: PUT KnPerson

/connectors/KnPerson

Example: POST KnPerson

/connectors/KnPerson

Example: DELETE KnEmployee

/connectors/KnEmployee/AfasEmployee/@EmId,ViSe/FloorA,U

JSON BODY

Basic example of a POST for submitting a Person (KnPerson).

DataConnector - REST

The AFAS API offers a number of special endpoints for the retrieval of data that cannot be retrieved with the Get Connector. These Data Connectors have their own endpoints. These connectors work in the same way as the Get Connectors with regard to filtering and escaping.

These connectors are usually combined with GetConnectors to get the information that is required for the activation. For this, AFAS knowledge is required as well as API knowledge.

VersionConnector

Retrieving the active AFAS version.

Also see: ProfitVersion connector

FileConnector

Get a file from a Profit environment based on a File ID and File Name.

Also see: FileConnector

ImageConnector

Get an image from a Profit environment based on an Image ID and format.

SubjectConnector

Get a file (attachment) from a Profit environment based on a File item ID and File ID.

Also see: SubjectConnector

ReportConnector

Generate a report based on a report GUID.

Also see: ReportConnector

Responses

2xx: Successful

When a call to the AFAS API is successful, a 200 or 201 response will be issued. In both cases, the call was successful. At inserts/posts, a 201 response will be added when the UpdateConnector returns a result. For example, in relation to a calendar appointment. When it has been created, the appointment number will be included in the response body.

4xx: Client Error

Http headers with statuses in the 400 range indicate that a request could not arrive at the server. Specific 400: Bad Request and 401: Unauthorised always indicates that the URL, token or AppConnector is incorrect.

5xx: Internal server error

500 Errors occur in the AFAS business rules. The cause can be different. It often concerns error reports with regard to content such as "General message: To make an appointment, there needs to be participants." This message is included in the Response Header ‘X-Profit-Error’ in Base64. These messages are functional and will always be rejected.

Retry

It is sometimes handy to do a retry but only when there are more than 500 messages. For example, when you execute an Update via FiEntries and you get a message back that the entry layout is currently blocked by another user. What happens here is that a change with regard to the entry takes place from AFAS Profit and that you also try to do this with the UpdateConnector. In such situations, you can perform several retry commands until the entry layout is blocked and the Update can be processed.

More data can be found in the environment logbook of Profit. The AFAS Administrator can offer you support in relation to this.

FAQ

How do I know for sure that my request works?

Execute a meta information request. Based on this, you will know whether the header and token are correct and you will get the GetConnector and UpdateConnector that you are entitled to as a response.

Does the AFAS API work asynchronously or synchronously?

Synchronous.

A check will be performed in the AFAS business rules to determine whether the request is valid after executing the request. Next, the data is retrieved or changed in the database. Next, the response returns to the connection that must stay open in the intervening time.

Does the AFAS API have webhooks?

Currently, no webhooks are available. If there are plans for this, this will be added to the roadmap.

How can I ensure that the data in my application is synchronous with AFAS?

You can keep the data synchronous by regularly polling to see whether new or changed records are available. It is possible to add the 'created on' and 'changed on' fields in nearly all GetConnector definitions. By filtering based on this, you ensure that you only get the changed data. Bear in mind the process and the AFAS fair use policy with regard to this.

Limitations

Time-out

If the connection with the API is more than approximately 15 minutes, the call will time out. The following methods can be used to prevent the time-out:

• You can filter or apply a skip/take with ORDER BY in relation to a GET. In relation to an UPDATE, you can distribute the dataset over several calls. You can then execute it in parallel.
• Use a filter in the call to manage the dataset. You can, for example, use a filter on a period to get fewer financial entries instead of all financial entries.
• Then also distribute the datasets over different calls so that there can be no issues with the 15 minute limit.

Data/Fair use

AFAS Online's platform uses a fair use policy when getting data. If the same dataset of 15 MB is retrieved every minute, contact will be made about this as an example.

Filter length

The URL has a limited length when using the web services. This means that the filter options are also limited. The maximum number of characters is 2,048.