Exact Online API SQL Driver

Invantive SQL is the fastest, easiest and most reliable way to exchange data with the Exact Online API.

Use the "Search" option in the left menu to search for a specific term such as the table or column description. When you already know the term, please use the "Index" option. When you can't find the information needed, please click on the Chat button at the bottom or place your question in the user community. Other users or Invantive Support will try to help you to our best.

The Exact Online API offers over 1.000 APIs grouped over a range of XML APIs, REST APIs and historically some CSV APIs.

The Exact Online driver covers 1127 tables and 25028 columns.

Exact Online API Clients

Invantive SQL is available on many user interfaces ("clients" in traditional server-client paradigma). All Invantive SQL statements can be exchanged with a close to 100% compatibility across all clients and operating systems (Windows, MacOS, Linux, iOS, Android).

The clients include Microsoft Excel, Microsoft Power BI, Microsoft Power Query, Microsoft Word and Microsoft Outlook. Web-based clients include Invantive Cloud, Invantive Bridge Online as OData proxy, Invantive App Online for interactive apps, Online SQL Editor for query execution and Invantive Data Access Point as extended proxy.

The Exact Online Power BI connector is based on the Invantive SQL driver for Exact Online, completed by a high-performance OData connector which works straight on Power BI without any add-on. The OData protocol is always version 4, independent whether the backing platform uses OData, SOAP or another protocol.

For technical users there are command-line editions of Invantive Data Hub running on iOS, Android, Windows, MacOS and Linux. Invantive Data Hub is also often used for enterprise server applications such as ETL. High-volume replication of data taken from the Exact Online API into traditional databases such as SQL Server (on-premise and Azure), MySQL, PostgreSQL and Oracle is possible using Invantive Data Replicator. Invantive Data Replicator automatically creates and maintains Exact Online datawarehouses, possibly in combination with data from over 70 other (cloud) platforms. Data Replicator supports data volumes up to over 1 TB and over 5.000 companies. The on-premise edition of Invantive Bridge offers an Exact Online ADO.net provider.

Finally, online web apps can be build for Exact Online using App Online of Invantive Cloud.

Monitor API Calls

When a query or DML-statement has been executed on Invantive SQL a developer can evaluate the actual calls made to the Exact Online API using a query on sessionios@DataDictionary. As an alternative, extensive request and response logging can be enabled by setting log-native-calls-to-disk to true. In the %USERPROFILE%\Invantive\NativeLog folder Invantive SQL will create log files per API request and response.

Specifications

The SQL driver for Exact Online supports partitioning: data from multiple companies are all listed together in one table. The value of the column Division indicates which company the data belongs to.

An introduction into the concepts of Invantive SQL such as databases, data containers and partitioning can be found in the Invantive SQL grammar.

The configuration can be changed using various attributes during log on and use. A full list of configuration options is listed in the driver attributes.

The catalog name is used to compose the full qualified name of an object like a table or view. The schema name is used to compose the full qualified name of an object like a table or view. On Exact Online the comparison of two texts is case sensitive by default.

Changes and bug fixes on the Exact Online SQL driver can be found in the release notes. Get access to the Exact Online community through the Exact Online section of the Invantive forums.

Driver code for use in settings.xml: ExactOnlineAll

Alias: eol

Recommended alias: eol

Partition Label: Administration

More technical documentation as provided by the supplier of the Exact Online API on the native APIconnection used can be found at https://developers.exactonline.com.

For Exact Online apps it was discouraged to use the CSV APIs and starting 2019 the use is almost impossible and requires techniques that can lead to delisting or app blocks. Therefore Invantive SQL includes the XML APIs and REST APIs. Both documented as the many undocumented Exact Online APIs are included.

A graphical representation of the essential Exact Online API tables available with Invantive SQL is at https://go.invantive.com/eolerd. It includes individual entity relationship data models per area and industry and includes manufacturing, PSA, trade, accounting and accountancy.

API Authentication

The Invantive SQL driver for Exact Online allows multiple authentication models:

- OAuth Code Grant Flow

- OAuth Implicit Grant Flow without MFA

- OAuth Implicit Grant Flow with MFA

Scraping

The functionality of all APIs is identical independent of the chosen authentication models. Business professionals, finance professionals and developers can choose the authentication model most suitable for API access.

All Invantive products include "OAuth client" settings such as client ID. In compliance with OAuth security recommendation, the code grant flow with an Invantive-controlled client ID and client secret is only used when the software runs on a device controlled by Invantive, such as on the Exact Online Power BI driver on Invantive Cloud.

The OAuth Implicit Grant Flow is used for interactive products such as the Excel add-in: Invantive Control for Excel. By default, a re-authentication is necessary every ten minutes. The user password is automatically provided when "Remember Password" was checked on log in. The MFA verification code (also known as "TOTP") must be entered every ten minutes. You can specify the secret key used for MFA verification process in the client software for an auto-generated verification code, but this reduces the security.

The OAuth security rules require the Implicit Grant Flow for deployment on a device not under control of the client app owner. However, you or a your developers can register your own company client on apps.exactonline.com. Use the client ID and client secret generated by Exact and use the form "Pre-authenticate" on Invantive Cloud to generate a refresh token. Optionally, you can request through Invantive Support that obsoletion of the refresh tokens is disabled for your client.

Authentication using scraping is possible, for instance for non-browser logins from a console application, but is highly discouraged and might be obsoleted without further notice.

Exact Online REST API and Popular Tables

The Exact Online REST API is most commonly used. Some of the most popular tables from the REST API are:

- TransactionLinesBulk: financial transaction accounting details

- AccountsBulk: customers and suppliers

- GLAccountsBulk: general ledger accounts

- ItemsBulk: articles.

- DocumentAttachmentFilesBulk: documents in binary format such as accounting documents

The REST API has in general great download performance. Additionally, the Exact REST API has filter capabilities on many columns, allowing use of server-side filtering in an translation of where-clauses in Invantive SQL leading to highly optimized REST API calls. Also the REST API allows complex join optimizations leading to highly reduced execution times compared to full downloads of multiple tables and joining them on the client. Incremental download facilities are available for further reducing the number of API calls and meeting Exact's strict rate limit policies.

Exact Online XML API and Popular Tables

Despite that the REST API was introduced by Exact in 2016, the XML API is still thriving and especially for accounting offers many high performance and scalable APIs. Also many APIs are not available in the REST API yet, the XML API offers them nonetheless. The most popular tables from the XML API are:

- BalanceLinesPerPeriod: balances per financial year and period and general ledger account

- AROutstandingItems: open invoices in accounts receivables

- APOutstandingItems: open invoices in account payables

- Settings: Exact Online company settings

- MatchSetLines: bank reconciliation details

Tables based on the XML API typically offer many columns which are mostly empty. This is due to the design chosen for the XML API by Exact developers with a very flexible XSD.

The XML API has even better download performance than the REST API. However, the XML API has limited filtering capabilities. For small environment a full download is acceptable but especially for the top 500 Exact Online customers an out-of-the-box great performance with Invantive SQL requires the use of the REST APIs.

API Rate Limits

The Exact Online APIs limit the number of API calls made in various ways. Invantive SQL has numerous optimizations specifically for Exact Online to achieve optimal API performance without manual fiddling of options or code.

Calls to the XML API are typically limited to 60 calls per minute. Invantive SQL automatically throttles to meet the specified XML API reate limits. These division-specific throttles are also applied when using the UploadXMLTopics table to upload massive amounts of transaction data into one or hundreds of companies in parallel.

Calls to the REST API are limited by minutely rate limits and daily limits. The daily limit per division (an Exact Online company) varies between 5.000 and 50.000 calls per day and client app, depending on agreement. The minute rate limit for the REST API varies between 60 and 300 calls per minute. Once the minute or daily API call rate limit has been reached, no more API calls can be made. Invantive SQL automatically throttles API calls to meet the rate limits reported by the Exact Online REST API. Developers can access the current rate limits and their reported API usage per division using the view RateLimits. The contents of the view RateLimits are automatically updated on every Exact Online API call.

Division and Data Scoping

Starting december 2020, the REST APIs apply division and data scoping. Division scoping means that an API call of an app can only access specific Exact Online companies or all companies granted to the user used to authenticate the app with. After an app was approved for use with Exact Online, the top-level menu "Import/Export" allows changing the division scope using the form "App privileges".

Data scoping means that an API call of an app is first compared to the registered and approved list of APIs for that app on apps.exactonline.com. Data scoping is never active for customer-specific app registrations. However, published apps always must undergo a security check including data scoping for REST APIs.

XML APIs are covered on division scoping, but currently the XML API is not subjected to data scoping.

All Invantive SQL products support division and data scoping for custom and published apps.

Cross-division Queries (Companies)

Every Exact Online company is called a "division". Each division in an Exact Online country has a unique number called the "division code". The column "divisioncode" (REST API tables) or "division_code" (XML API tables) contains the division code. Most REST API tables on Invantive SQL have columns not present in the REST API and added by Invantive SQL for additional data on the division, such as VAT number. This is for use with large accounting or accountancy environments which typically run across thousands of divisions.

For use and billing purposes, each division maps onto one partition. It does not matter whether data is retrieved on the REST API, XML API or from both Exact Online APIs on the division.

Invantive SQL API access to Exact Online is not possible for an archived division or a division of a accountancy customer which has been blocked due to dunning. The last scenario only applies for accountancy use; each accountant can access the divisions of associated customers.

Invantive SQL executes all queries without changes on one division or multiple divisions. The get results from multiple Exact Online divisions are merged into one large table with data from multiple divisions. The retrieval of data is performed in parallel as specified through connector attributes; the default maximum number of divisions queried in parallel is 8 per SQL engine instance.

Graphical products typically contain a division selector, allowing a finance professional to choose all divisions, a specific one or a sub-selection such as on division classification setup (account manager, accountancy office, monthly or quarterly VAT).

A developer can specify the division(s) to use with the Invantive SQL statement "use". The default division can be set using "use default" and all using "use all". Division segmentation across a larger population such as all divisions from the accountancy branch office "Amsterdam" can be selected using "use" with a selection query such as "use select ... from". At all times, at least one division must be selected. For details see the SQL grammar.

15-06-2022 19:32 Version 22.0.232-PROD+3445