` endpoint provinding both your `X-API-KEY` and the end user `X-ACCOUNT-KEY`.
# Odoo
Source: https://docs.maesn.com/integrations/odoo
Integrate Odoo easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `odoo`
| | Read | Create | Update | Delete | Webhook | |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: | - |
| Accounts | | | | | | |
| Async task | | | | | | |
| Bank accounts | | | | | | |
| Bills | | | | | | |
| Bill lines | | | | | | |
| Booking proposals | | | | | | |
| Contacts | | | | | | |
| Customers | | | | | | |
| Credit notes | | | | | | |
| Dimensions | | | | | | |
| Expenses | | | | | | |
| Files | | | | | | |
| Fiscal years | | | | | | |
| Goods receipts | | | | | | |
| Goods receipt lines | | | | | | |
| Invoices | | | | | | |
| Invoice lines | | | | | | |
| Items | | | | | | |
| Journals | | | | | | |
| Journal entries | | | | | | |
| Offers | | | | | | |
| Offer lines | | | | | | |
| Open items | | | | | | , |
| Payments | | | | | | |
| Payment terms | | | | | | |
| Projects | | | | | | |
| Purchase orders | | | | | | |
| Purchase order lines | | | | | | |
| Sales orders | | | | | | |
| Sales order lines | | | | | | |
| Suppliers | | | | | | |
| Tax rates | | | | | | |
| Transactions | | | | | | |
| Trial balance | | | | | | |
| Units | | | | | | |
| Users | | | | | | |
| Vendor credits | | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by Odoo
## How to connect to Odoo
Odoo uses username and password for authentication. To allow your customers to link your application with their Odoo accounts, you need to provide the Odoo instance URL, database, username, and password.
Before you begin, make sure you have the following:
* An Odoo account with administrator permissions.
You can sign-up for a free trial at [https://www.odoo.com/trial](https://www.odoo.com/trial), if you do not have an Odoo account already.
You'll need the following fields to authenticate to Odoo:
**1) Odoo URL**
* Odoo Online: visible in your browser (example: `https://mycompany.odoo.com`)
* Self-Hosted: your provided ERP URL (example: `https://erp.yourcompany.com`)
Use only the base URL (no `/web` or paths).
**2) Database name**
* Odoo Online: usually the subdomain (example: `mycompany`)
* Self-Hosted: ask your Odoo admin if unsure
**3) Username**
Your Odoo login email (example: `admin@company.com`)
**4) Password or API key**
* You can use your password
* Recommended: create an **API key**
* Settings → Users → select user → Security tab → Generate API Key
* Use this API key instead of your password.
Paste your Odoo fields in the maesn Connect and press 'submit'.
Your Odoo account is now connected!
# Pennylane
Source: https://docs.maesn.com/integrations/pennylane
Integrate Pennylane easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `pennylane`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoices lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by Pennylane
## How to connect to Pennylane
To allow your customers to link your application with their Pennylane account, you need to set up a Pennylane App and submit your application credentials to maesn.
Note that there is a manual process required to acquire full access to Pennylane through the API. [Reach out to maesn today](https://www.maesn.com/contact) to learn more about how to partner with Pennylane and get access to the required Pennylane account.
Before you begin, make sure you have the following:
* A Pennylane client configured with:
* callback-URL: `https://api.maesn.dev/auth/callback/pennylane`
* scopes: `customers:all`, `suppliers:all`, `customer_invoices:all`, `supplier_invoices:all`, `ledger`, `file_attachments:all`, `bank_accounts:readonly`, `categories:all`, `products:all`, `quotes:all`, `transactions:readonly`.
* A `client id` and `client secret` for the configured client.
* A Pennylane account.
To get a Pennylane client configured, you need to establish contact with the Pennylane partner programme (see [section below](/integrations/pennylane#becoming-a-pennylane-partner)) and supply them the details of your integration including the scopes required.
Next we configure your API tenant with your client's details:
* Get in touch with your contact person at maesn to submit the client id and client secret.
If you are not sure who your technical contact is, don’t hesitate to [reach out to us](https://www.maesn.com/contact).
## Becoming a Pennylane Partner
To start using the Pennylane API through maesn, it is necessary to establish a direct relation with Pennylane and receive your client credentials from them.
All aspects of a Pennylane partner can be found on their [partner page](https://www.pennylane.com/fr/partenaires/partenaire-technologique).
# Procountor
Source: https://docs.maesn.com/integrations/procountor
Integrate Procountor easily with Maesn's Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `procountor`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offers lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase order | | | | | |
| Purchase order lines | | | | | |
| Sales order | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by Procountor
## How to connect to Procountor
To get started with Procountor integration, you first need to set up a sandbox environment for testing. Once testing is complete, you can proceed to the production environment.
### Setting up the Sandbox Environment
You must request your own test environment from Procountor. Navigate to the [Procountor test environment request form](https://dev.procountor.com/contact/request-testing-environment/) and fill it out with the following information:
1. **Company Information**: Provide details about your company
2. **Purpose**: Select "Integration platform"
3. **Type of Integration**: Choose "Common API Client = Integration will be publicly available to be used by any company"
4. **Redirect URI**: Set to `https://api.maesn.dev/auth/callback/procountor-sandbox`
5. **Transferred Data**: Include invoices, chart of accounts, VATs, ledger receipts, persons, currencies, bank accounts, payments, etc.
6. **Direction**: Select "Both" (read and write)
7. **Countries**: Select "Finland and Sweden"
8. **Policies**: Accept all required policies
After submitting the request, Procountor will review the application and provide the client credentials (Client ID and Client Secret).
* This process typically takes 3-4 days
* The credentials will be sent to your email and your phone number as a text message
* Procountor will also send test account credentials that can be used as a test user for the integration using the sandbox
* The test account can be accessed in the browser (UI) via [https://pts-secure.procountor.com/procountor/](https://pts-secure.procountor.com/procountor/)
* **Login process**: The first login only requires a username and a personal password. After the first login, you can choose from two secure methods for verifying subsequent logins:
* **One-time passwords**: The third step in the login process will be entering a four-letter password from the password list. Before logging in, make sure your browser allows pop-up windows so you can open the password list.
* **Finago Procountor Key mobile app**: Verify your login using the mobile application.
* You may change the verification method at any point after the first login.
* **Note**: On the test server, automatic forgotten password resetting and sending options are not available.
* Once received, securely store these credentials
Finally, once you receive your credentials from Procountor, set up your API tenant with your application’s details:
* Contact your maesn representative to submit the client ID and client secret.
If you are not sure who your technical contact is, do not hesitate to [reach out to us](https://www.maesn.com/contact).
With the sandbox environment configured, you can now:
* Test all integration features in a safe environment
* Verify data synchronization and workflows
* Debug any issues before going to production
### Moving to Production
Once testing is complete in the sandbox environment, follow a similar process to set up the production environment:
1. Navigate to the [Procountor production access request form](https://dev.procountor.com/contact/request-production-access/) and fill it out with the same information as the test environment request, but with the following changes:
* **Redirect URI**: Set to `https://api.maesn.dev/auth/callback/procountor` (without `-sandbox`)
* **Authentication**: Select "API authentication" option
* All other fields remain the same (company information, purpose, type of integration, transferred data, direction, countries, and policies)
2. Wait 3-4 days for Procountor to send the production credentials (client id and secret) via email / text message
3. Create a production test account:
* **Note**: The test account from the sandbox environment cannot be used in production
* To test in the production environment, you will need a Procountor Finago account. Talk to your Maesn contact person or purchase an account through the following:
[https://procountor.fi/tutustu/](https://procountor.fi/tutustu/)
* This account can be accessed in the browser (UI) via [https://secure.procountor.com/procountor/](https://secure.procountor.com/procountor/)
4. Submit the production credentials (client id and secret) to Maesn to configure the `procountor` target system
5. You can now use Procountor in production
# Qonto
Source: https://docs.maesn.com/integrations/qonto
Integrate Qonto easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `qonto`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by Qonto
## How to connect to Qonto
To allow your customers to link your application with their Qonto accounts, you need to set up a Qonto App and submit your application credentials to maesn.
Before you begin, make sure you have the following:
* A Qonto developer account.
You can sign-up for a developer account at [https://developers.qonto.com/](https://developers.qonto.com/), if you do not have it already.
In this step we create the App that a user can choose to install into their Qonto instance to authorize the integration with your application.
* Navigate to the Qonto [developer portal](https://developers.qonto.com/) and log in, if you are not already logged in.
* Click "Create an app".
* Choose the use case "Connect your customers' Qonto accounts to your platform".
* Provide a logo to your app.
* Give your app a name. This should be your application's name. When your users link their Qonto account, they will see that "App Name" is requesting to integrate with their Qonto account.
* In "Redirection URIs" add the redirect URL: `https://api.maesn.dev/auth/callback/qonto`
* Click on "continue".
* Select the following scopes: `offline_access organization.read attachment.write supplier_invoice.read supplier_invoice.write client_invoices.read client_invoices.write client.read client.write webhook`.
* Click "Create app".
* Once the app is created, the regulatory team will review the app and approve it. This process can take few days.
In the last step, once your app is approved, we setup your API tenant with your App's details:
* Get in touch with your contact person at maesn to submit the `client id` and `client secret`.
If you are not sure who your technical contact is, do not hesitate to [reach out to us](https://www.maesn.com/contact).
## Sandbox environment
**TARGET\_SYSTEM:** `qonto-sandbox`
You can start testing and using the integration immediately in Qonto's sandbox environment.
Within your Qonto developer account, your sandbox credentials are already available in the "Sandbox" section. The only setup required is to add the redirect URL in "Settings": [https://api.maesn.dev/auth/callback/qonto-sandbox](https://api.maesn.dev/auth/callback/qonto-sandbox).
At this stage, simply provide your client credentials for the sandbox and your `X-Qonto-Staging-Token` key to your contact person at Maesn to set up the sandbox integration.
Inside the developer account, you will also find the "Test user credentials" (username and password) needed to authenticate with the sandbox environment and test the OAuth2 flow and API calls. If any verification screen is prompted, please fill `123456`.
IMPORTANT: When authenticating a sandbox user using the Maesn Auth API, you must first open the `sandbox web app` from the Qonto Developer Portal in your browser and log in with the test user credentials.
Once logged in, open another browser tab and start the OAuth2 flow using the URL generated by the Maesn Auth API call. This will allow you to link the sandbox account successfully.
## Becoming a Qonto Partner
You have the opportunity to publish your app in Qonto’s Integrations & Partnerships section, but this requires meeting several criteria:
* Beta usage: Your integration must be actively used by at least 25 beta testers.
* Submission: Send an email to [cp@getqonto.atlassian.net](mailto:cp@getqonto.atlassian.net)
including:
* A video demo of your integration’s functionalities.
* Login credentials so Qonto can access and test your app.
* Approval content: Once approved, provide all information to be displayed on your integration page.
You can find more information here : [Integrations and Partners Area ](https://support-fr.qonto.com/hc/en-us/articles/23947671003921-What-is-the-Integrations-and-Partnerships-section#h_ea9b840fa5).
## Webhooks
Qonto supports the following parameters for webhooks:
Resources:
* `INVOICE`
Qonto only needs the resource and not the event type: you subscribe to a type and get back all events for that type.
Qonto only sends `CREATED` and `UPDATED` events.
The subscription is created **per customer**, which means for each customer, you will create a customized subscription for resources you want to be notified about.
To set this up, call Maesn's create webhook endpoint `POST /webhooks` with the following example body:
```javascript Example code snippet theme={null}
const response = await axios.post(url, {
"callbackUrl": callbackUrl,
"resource": "INVOICE"
}, {
headers: {
'X-API-KEY': apiKey,
'X-ACCOUNT-KEY': accountKey
}
});
```
It will return the `id` associated with the subscription:
```json Example response theme={null}
{
"data": {
"id": "830251",
"callbackUrl": "https://example.com/webhook-endpoint/12345",
"createdDate": "2026-01-22T16:44:37.252Z",
"expiresDate": "null",
"secret": "2f1fd5f883d4c0adf5b31b91e4d6ae2d2975620c67bac8fdb864c78047b1d522"
"updatedDate": "2026-01-22T16:44:37.252Z"
},
"meta": {}
}
```
At this point, your system is ready to receive end-user–related events at the callback URL you provided. The event response will provide the following information:
```json Example event body theme={null}
{
"eventType": "UPDATED",
"filterDate": null, //not supported by qonto
"resource": "INVOICE",
"resourceId": "1605408d-ed88-4228-8a12-ab857a2972d8",
"userId": null //not supported by qonto
}
```
To delete the webhook subscription, you can call the `DELETE` `/webhooks/{webhookId}` endpoint provinding both your `X-API-KEY` and the end user `X-ACCOUNT-KEY`.
# QuickBooks
Source: https://docs.maesn.com/integrations/quickbooks
Integrate Quickbooks easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `quickbooks`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by QuickBooks
## How to connect to QuickBooks
To allow your customers to link your application with their QuickBooks accounts, you need to set up a QuickBooks App and submit your application credentials to maesn.
Before you begin, make sure you have the following:
* A QuickBooks account with administrator permissions.
You can sign-up for a free trial at [https://quickbooks.intuit.com/eu/#pricing](https://quickbooks.intuit.com/eu/#pricing), if you do not have a QuickBooks account already. Note that you will not need to use this QuickBooks account for anything else than managing the QuickBooks App and, if you want to, becoming a QuickBooks partner later.
In this step we create the App that a user can choose to install into their QuickBooks instance to authorize the integration with your application.
* Navigate to the QuickBooks [developer portal](https://developer.intuit.com/app/developer/dashboard) and log in, if you are not already logged in.
* On the tab "Apps", click "Create an app".
* Select the QuickBooks Online and Payments option.
* Give your app name: This should be your application's name. When your users link their QuickBooks account, they will see that "App Name" is requesting to integrate with their QuickBooks account.
* Select the com.intuit.quickbooks.accounting scope.
* Click "Create App".
* In the next screen, click on "Key & credentials" in the left-hand menu.
* Click on "Add URI" and add the redirect URL: `https://api.maesn.dev/auth/callback/quickbooks`
In the last step, we setup your API tenant with your App's details:
* Get in touch with your contact person at maesn to submit the client id and client secret.
If you are not sure who your technical contact is, do not hesitate to [reach out to us](https://www.maesn.com/contact).
## Sandbox environment
QuickBooks has different URLs and credentials for their production and sandbox environments.
To generate a sandbox end user account you have to use the `quickbooks-sandbox` target system.
Inside quickbooks, you can create sandbox credentials with the same steps as the production credentials, you just need to create sandbox credentials instead of production credentials.
You also have to use the following callback URL for the sandbox environment: `https://api.maesn.dev/auth/callback/quickbooks-sandbox`
## Becoming a QuickBooks Partner
Anyone can become a QuickBooks app partner. The requirements and steps to become a partner are detailed [here](https://developer.intuit.com/app/developer/qbo/docs/go-live/publish-app).
Note that before you become a QuickBooks partner you will only have access to their development environment. Once you become a partner you will have access to their production environment.
## Webhooks
Quickbooks supports the following resources:
* `ACCOUNT`
* `BILL`
* `CUSTOMER`
* `INVOICE`
* `ITEM`
* `JOURNAL_ENTRY`
* `PAYMENT`
* `SUPPLIER`
* `EXPENSE`
Quickbooks sends `CREATED`, `UPDATED`, `DELETED`, `MERGED`, `VOIDED` and `EMAILED` events.
Before you start using webhooks for QuickBooks, you will need to contact us to receive the callback URL to use in your QuickBooks App configuration.
Inside your QuickBooks app, you will choose the `resource` and `eventType` you want the webhooks enabled for. Once configured, this setup will be valid for all users of the app.
Now, for each authenticated end user, call Maesn’s create webhook endpoint `POST /webhooks` with the following body:
```javascript Example code snippet theme={null}
const response = await axios.post(url, {
"callbackUrl": callbackUrl
}, {
headers: {
'X-API-KEY': apiKey,
'X-ACCOUNT-KEY': accountKey
}
});
```
It will return the `id` associated with the subscription:
```json Example response theme={null}
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"callbackUrl": "https://example.com/webhook-endpoint/12345",
"createdDate": null,
"expiresDate": "null",
"secret": "2f1fd5f883d4c0adf5b31b91e4d6ae2d2975620c67bac8fdb864c78047b1d522"
"updatedDate": "null"
},
"meta": {}
}
```
At this point, your system is ready to receive end-user–related events at the callback URL you provided. Quickbooks retrieves a list of events.
The event response will be an array providing the following information:
```json Example event body theme={null}
[{
"eventType": "CREATED",
"filterDate": null, //not supported by quickbooks
"resource": "INVOICE",
"resourceId": "1",
"userId": "23631355"
}]
```
To delete the webhook subscription, you can call the `DELETE` `/webhooks/{webhookId}` endpoint.
# Sage Accounting
Source: https://docs.maesn.com/integrations/sage-accounting
Integrate Sage Accounting easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `sageaccounting`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by Sage Accounting
## How to connect to Sage Accounting
To allow your customers to link your application with their Sage Accounting account, you need to set up a Sage Accounting App and submit your application credentials to maesn.
You may include a companyId when targeting Sage Accounting endpoints to scope requests to a specific company. This step is optional.
To retrieve available company IDs, use the GET /companies endpoint in the Authentication section and use the id field from the response as the companyId.
Before you begin, ensure you have the following:
* An active Sage Accounting account with a valid subscription.
In this step we create the App that a user can choose to install into their Sage Accounting instance to authorize the integration with your application.
* Sign in to your [Sage Accounting](https://developerselfservice.sageone.com/session/new) account.
* On the welcome page select and click "Create an App".
* **App Name**: This should be your application's name. When your users link their Sage Accounting account, they will see that "App Name" is requesting to integrate with their Sage Accounting account.
* **Homepage URL**: The homepage of your company's website, e.g. `https://yourcompany.com/`.
* **Callback URL**: Should be set to `https://api.maesn.dev/auth/callback/sageaccounting`.
* Click "Save".
Once the application is created, the application page with all the provided info is shown. Note the "Client ID", "Client Secret" as it will be needed later.
Ensure that you are logged out from the developer account from the step above, or open a new tab in an incognito browser. Trying to create a user account while logged in to the developer account may lead to issues.
* Go to the [getting started page](https://developer.sage.com/accounting/docs/v1.0.0/guides/quick-start/getting-started) and use one of the "Sign-up-links" in the table of available trial businesses to set up a trial account. Currently only trial accounts for the UK are avaialble.
* Complete the registration of your user account and your trial company.
Set up your API tenant with your application's details:
* Contact your maesn representative to submit the client ID and client secret.
If you are not sure who your technical contact is, do not hesitate to [reach out to us](https://www.maesn.com/contact).
Finally, once the API key configuration is completed. You can start the authentication and authenticate using the user account of the trial business that you created in step 3.
**Note** that you cannot use the developer portal credentials to authenticate as an end user.
# Sage Active
Source: https://docs.maesn.com/integrations/sage-active
Integrate Sage Active easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `sage-active-de` `sage-active-es` `sage-active-fr`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by Sage Active
## How to connect to Sage Active
To allow your customers to link your application with their Sage Active account, you need to set up a Sage Active App and submit your application credentials to maesn.
When targeting Sage Active endpoints, it is essential to fill in the *companyId* query parameter.
You can obtain this value by using the `GET Companies` endpoints available under the Authentication section.
Please use the id field as the companyId.
Before you begin, ensure you have the following:
* An active Sage Active account with a valid subscription.
* Sign in to your [Sage Active](https://www.de.active.sage.com/) account.
* In the sidebar, select Settings.
* Select "Application keys".
* Select Apps
* To set up a new application, select "Add a new app", enter a name for your application, add an URL and a contact email.
* Click "Next".
* Select the right Sage Active type for your needs (DE/ES/FR).
* Under "CallBack URLs" enter one of the following URLs:
`https://api.maesn.dev/auth/callback/sage-active-de`
`https://api.maesn.dev/auth/callback/sage-active-es`
`https://api.maesn.dev/auth/callback/sage-active-fr`
* Click "Save".
On the "Solutions" page of your application, you will find all the information about your application. Note the "Client ID", "Client Secret" and the "Subscription primary key" as it will be needed later.
Finally, set up your API tenant with your application's details:
* Contact your maesn representative to submit the client ID and client secret and the subscription key.
If you are not sure who your technical contact is, do not hesitate to [reach out to us](https://www.maesn.com/contact).
# sevdesk
Source: https://docs.maesn.com/integrations/sevdesk
Integrate sevdesk easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `sevdesk`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by sevdesk
## How to connect to sevdesk
As a customer of sevdesk, you can easily retrieve the API key used for connecting to your sevdesk accounting data.
Before you begin, make sure you have the following:
* A sevdesk account with administrator permissions to retrieve the API key.
Navigate to the [sevdesk login page](https://my.sevdesk.de/login).
Log in to sevdesk using your account credentials and [retrieve the API key](https://api.sevdesk.de/#section/Authentication-and-Authorization).
Paste your sevdesk API key in to the 'API key' field in maesn Connect and press 'submit'. If the API key is valid, the connection will be established and a success message will be displayed.
You can also use the [create account](https://docs.maesn.com/api-reference/auth/create-account) endpoint for this.
Your sevdesk account is now connected!
## Becoming a sevdesk Partner
Anyone can develop an integration and become a sevdesk technology partner. The requirements and steps to become a partner are detailed [here](https://sevdesk.de/technologie-partner-werden/) (in German only).
Essentially, there is no approval process or registration required. Simply build the integration with maesn's unified API and register for the sevdesk partner program once you have onboarded your first ten users.
# Snelstart
Source: https://docs.maesn.com/integrations/snelstart
Integrate Snelstart easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `snelstart`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by Snelstart
## How to connect to Snelstart
To set up an integration with **Snelstart**, you’ll need two keys: a **Connection Key** and a **Subscription Key**.
Before you begin, make sure you have the following:
* A **[Snelstart account](https://login.snelstart.nl/)**. **Note** that you must have the *inZicht* or *inControle* package to set up API access.
* A **[Snelstart Developer account](https://b2bapi-developer.snelstart.nl/)**.
1. Go to the [Snelstart login page](https://login.snelstart.nl/) and sign in with your credentials.
2. In the left sidebar, click **“Koppelingen”** (Links).
3. Under **“Koppelingen”**, find **“Maatwerk”** (Custom integration) and select it.
4. Click **“Koppeling instellen”** (Set up connection), agree to the scopes, and save your **Connection Key** somewhere safe.
1. Visit the [Snelstart Developer Portal](https://b2bapi-developer.snelstart.nl/) and log in.
2. If you don't already have an active subscription, navigate to **Products** and select a suitable plan (you can start with **Ontwikkeling & Test** – development and testing).
3. Choose a name for your subscription, agree to the terms, and subscribe.
4. Once your subscription is created, go to your **Profile** and copy one of your two **Subscription Keys** (the Primary Key is recommended).
**Note:** Development keys are valid for 90 days with limited calls. For production, you'll need a production subscription key (€250 one-time fee). Apply at the [developer portal](https://b2bapi-developer.snelstart.nl/).
1. Contact your **maesn representative** and provide the following information:
* Your **Snelstart Subscription Key**
2. In **maesn Connect**, paste your **Connection Key** into the **API Key** field and click **Submit**.
3. If the key is valid, the connection will be established and a confirmation message will appear.
You can also use the [create account](https://docs.maesn.com/api-reference/auth/create-account) endpoint for this.
Your Snelstart account is now successfully connected!
## Becoming a Snelstart Partner
To use the Snelstart API in production, you must become an **official Snelstart Partner**.
Once approved, your application gains access to **live customer environments** (beyond the default test company).
For detailed instructions and partner requirements, visit the [Snelstart Developer Portal](https://b2bapi-developer.snelstart.nl/).
# Tripletex
Source: https://docs.maesn.com/integrations/tripletex
Integrate Tripletex easily with Maesn's Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `tripletex`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= Not yet supported
## How to Connect to Tripletex
Tripletex uses token-based authentication. Two tokens are combined into a session token: a `consumer token` that identifies your integration (configured once on your maesn tenant), and an `employee token` that identifies the Tripletex account, which the end user enters when connecting.
You need an active Tripletex account. Creating API tokens requires administrator access.
Obtain the `consumer token` for the integration in Tripletex. The consumer token identifies the integration (not an individual user) and is the same for all of your end users.
See Tripletex's [authentication and tokens documentation](https://developer.tripletex.no/docs/documentation/authentication-and-tokens/) for how consumer tokens are issued.
In Tripletex, an administrator creates an `employee token` under "user settings" > "API access". This token identifies the account whose data you want to access, and is the value each end user enters when connecting.
Before connecting, share your `consumer token` with your contact person at maesn so we can configure it on your API tenant. This is a one-time setup.
If you are not sure who your technical contact is, do not hesitate to [reach out to us](https://www.maesn.com/contact).
Once it is configured, connect through maesn Connect — or the [create account](https://docs.maesn.com/api-reference/auth/create-account) endpoint — by entering your `employee token`.
## Sandbox environment
**TARGET\_SYSTEM:** `tripletex-sandbox`
Tripletex provides a separate test environment. To connect against it, use the sandbox target system identifier:
The sandbox behaves exactly like production but points at Tripletex's test environment (`https://api-test.tripletex.tech`) and requires its own consumer and employee tokens.
## Multi-company (accountant) access
A regular employee token accesses a single company, and no company selection is required. An `accountant` (company-owned) token can access several client companies. For those tokens, the list of accessible companies is available through the [Get companies](/api-reference/auth/get-companies) endpoint, and the desired company can be selected during the connection flow.
# Twinfield
Source: https://docs.maesn.com/integrations/twinfield
Integrate Twinfield easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `twinfield`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by Twinfield
## How to connect to Twinfield
To allow your customers to link your application with their Twinfield account, you need to set up register to Twinfield and submit your application credentials to maesn.
Before you begin, ensure you have the following:
* An active Twinfield account.
In this step we create the App that a user can choose to install into their Twinfield instance to authorize the integration with your application.
* Navigate to the Twinfield [developer portal](https://developers.twinfield.com/) and log in, if you are not already logged in.
* On the tab "Clients", click "New".
* Give your client name: This should be your application's name. When your users link their Twinfield account, they will see that "Client Name" is requesting to integrate with their Twinfield account.
* Give your client id: This will be one of the credentials you will need to submit to maesn.
* Select authorization flow, and copy and save the client secret.
* Add the redirect URL: `https://api.maesn.dev/auth/callback/twinfield`.
* Click "Save".
Finally, set up your API tenant with your application's details:
* Contact your maesn representative to submit the client ID and client secret and the subscription key.
If you are not sure who your technical contact is, do not hesitate to [reach out to us](https://www.maesn.com/contact).
# Visma e-conomic
Source: https://docs.maesn.com/integrations/visma-e-conomic
Integrate Visma e-conomic easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `vismaeconomic`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by Visma e-conomic
## How to connect to Visma e-conomic
To allow your customers to link your application with their Visma e-conomic account, you need to set up a register to Visma e-conomic and submit your application credentials to maesn.
Before you begin, ensure you have the following:
* An active Visma e-conomic account.
* Login to Visma e-conomic dev portal and create an app.
* Add the following redirect URL: `https://api.maesn.dev/auth/callback/vismaeconomic`.
Finally, set up your API tenant with your application's details:
* Contact your maesn representative to submit the AppSecretToken.
If you are not sure who your technical contact is, do not hesitate to [reach out to us](https://www.maesn.com/contact).
# Visma eAccounting (Spiris)
Source: https://docs.maesn.com/integrations/visma-eaccounting
Integrate Visma eAccounting easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `vismaeaccounting`
Note that the system is known under the brand name eAccounting in the Netherlands and Norway and as Spiris (used to be called SPCS) in Sweden.
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :---------------------: | :-------------------: | :-------------------: | :-------------------: | :---------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | \* | | | | \* |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by Visma eAccounting
* Not available for Swedish companies
## How to connect to Visma eAcccounting
To allow your customers to link your application with their Visma eAccounting account, you need to set up register to Visma eAcccounting and submit your application credentials to maesn.
Before you begin, ensure you have the following:
* An active Visma eAcccounting account.
* When you registered to Visma eAccounting, you received an email that contains the client id and secret
* You have to contact Visma to change the URL to the correct one which is: `https://api.maesn.dev/auth/callback/vismaeaccounting`.
Finally, set up your API tenant with your application's details:
* Contact your maesn representative to submit the client ID and client secret and the subscription key.
If you are not sure who your technical contact is, do not hesitate to [reach out to us](https://www.maesn.com/contact).
## Sandbox environment
After registering with Visma you get access to a sandbox company for testing your integration. Visma will send your sandbox credentials — including your **client ID** and **client secret** — via email.
Each sandbox company is tied to a specific region and available in the following regions:
* Sweden
* Norway
* Finland
* The Netherlands
The region cannot be changed after creation. Since each account is limited to one sandbox company, you need to register a new account (with a different email address) to test additional regions. New accounts can be registered at the [Visma Developer Self-Service portal](https://selfservice.developer.vismaonline.com/).
> **Note:** Your production client ID can be used to access your sandbox company, but a sandbox client ID cannot be used against a production company.
# weclapp
Source: https://docs.maesn.com/integrations/weclapp
Integrate weclapp easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `weclapp`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by weclapp
## How to connect to weclapp
As a customer of weclapp, you can easily retrieve the API key used for connecting to your weclapp data.
Before you begin, make sure you have the following:
* A weclapp account with administrator permissions to generate and retrieve the Personal Access Token.
You can sign-up for a free trial at [https://www.weclapp.com/en/register/](https://www.weclapp.com/en/register/), if you do not have a weclapp account already.
Please note: you must replace 'weclappTenantId' inside the url's paths with the id of your instance of weclapp.
Log in to weclapp using your account credentials and the provided url, properly edited with your weclapp tenant id, to generate and retrieve the Access Token: [retrieve the Access Token](https://weclappTenantId.weclapp.com/webapp/view/settings/GeneralSettingsOverview.page).
Enter your password in the 'API token' section to generate new API keys.
Paste your weclapp api token in to the 'API key' field and your weclapp tenant id in to the 'weclapp Tenant Id' field in maesn Connect and press 'submit'. If the Token and the weclapp Id are valid, the connection will be established and a success message will be displayed.
You can also use the [create account](https://docs.maesn.com/api-reference/auth/create-account) endpoint for this.
Your weclapp account is now connected!
## Webhooks
Weclapp supports the following parameters for webhooks:
Resources:
* `CUSTOMER`
* `SUPPLIER`
* `INVOICE`
* `CREDIT_NOTE`
* `SALES_ORDER`
Event types:
* `CREATED`
* `UPDATED`
* `DELETED`
Weclapp needs both resource and event type to be able to send webhook events.
The subscription is created **per customer**, which means for each customer, you will create a customized subscription for the events and resources you want to be notified about.
To set this up, call Maesn's create webhook endpoint `POST /webhooks?companyId=` (`companyId` query parameter required if not using the interactive flow) with the following example body:
```javascript Example code snippet theme={null}
const response = await axios.post(url, {
"callbackUrl": callbackUrl,
"eventType": "CREATED",
"resource": "CUSTOMER"
}, {
headers: {
'X-API-KEY': apiKey,
'X-ACCOUNT-KEY': accountKey
}
});
```
It will return the `id` associated with the subscription:
```json Example response theme={null}
{
"data": {
"id": "830251",
"callbackUrl": "https://example.com/webhook-endpoint/12345",
"createdDate": null,
"expiresDate": "null",
"secret": "2f1fd5f883d4c0adf5b31b91e4d6ae2d2975620c67bac8fdb864c78047b1d522"
"updatedDate": "null"
},
"meta": {}
}
```
At this point, your system is ready to receive end-user–related events at the callback URL you provided. The event response will provide the following information:
```json Example event body theme={null}
{
"eventType": "CREATED",
"filterDate": null, //not supported by weclapp
"resource": "CUSTOMER",
"resourceId": "1605408d-ed88-4228-8a12-ab857a2972d8",
"userId": null //not supported by weclapp
}
```
To delete the webhook subscription, you can call the `DELETE` `/webhooks/{webhookId}?companyId=` endpoint provinding both your `X-API-KEY` and the end user `X-ACCOUNT-KEY`.
# Xentral
Source: https://docs.maesn.com/integrations/xentral
Integrate Xentral easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `xentral`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by Xentral
## How to connect to Xentral
As a customer of Xentral, you can easily retrieve the API key used for connecting to your Xentral accounting data.
Before you begin, make sure you have the following:
* A Xentral account with administrator permissions to generate and retrieve the Personal Access Token.
Please note: you must replace 'YourXentral' inside the url's paths with the id of your instance of Xentral.
Log in to Xentral using your account credentials and the provided url, properly edited with your Xentral id, to generate and retrieve the Access Token: [retrieve the Access Token](https://YourXentral.xentral.biz/new/account-settings?menu=developer-settings\&submenu=personal-access-tokens).
Paste your Xentral Token in to the 'API key' field and your Xentral instance Id in to the 'Xentral Id' field in maesn Connect and press 'submit'. If the Token and the Xentral Id are valid, the connection will be established and a success message will be displayed.
You can also use the [create account](https://docs.maesn.com/api-reference/auth/create-account) endpoint for this.
Your Xentral account is now connected!
# Xero
Source: https://docs.maesn.com/integrations/xero
Integrate Xero easily with Maesn’s Unified API. See the documentation with detailed system coverage and setup prerequisites.
**TARGET\_SYSTEM:** `xero`
| | Read | Create | Update | Delete | Webhook |
| -------------------- | :-------------------: | :-------------------: | :-------------------: | :-------------------: | :-------------------: |
| Accounts | | | | | |
| Async task | | | | | |
| Bank accounts | | | | | |
| Bills | | | | | |
| Bill lines | | | | | |
| Booking proposals | | | | | |
| Contacts | | | | | |
| Customers | | | | | |
| Credit notes | | | | | |
| Dimensions | | | | | |
| Expenses | | | | | |
| Files | | | | | |
| Fiscal years | | | | | |
| Goods receipts | | | | | |
| Goods receipt lines | | | | | |
| Invoices | | | | | |
| Invoice lines | | | | | |
| Items | | | | | |
| Journals | | | | | |
| Journal entries | | | | | |
| Offers | | | | | |
| Offer lines | | | | | |
| Open items | | | | | |
| Payments | | | | | |
| Payment terms | | | | | |
| Projects | | | | | |
| Purchase orders | | | | | |
| Purchase order lines | | | | | |
| Sales orders | | | | | |
| Sales order lines | | | | | |
| Suppliers | | | | | |
| Tax rates | | | | | |
| Transactions | | | | | |
| Trial balance | | | | | |
| Units | | | | | |
| Users | | | | | |
| Vendor credits | | | | | |
= Supported by Maesn
= On demand - contact us
= Not supported by Xero
## How to connect to Xero
To allow your customers to link your application with their Xero accounts, you need to set up a Xero App and submit your application credentials to maesn.
Before you begin, make sure you have the following:
* A Xero account with administrator permissions.
You can sign-up for a free trial at [https://www.xero.com/signup/](https://www.xero.com/signup/), if you do not have a Xero account already. Note that you will not need to use this Xero account for anything else than managing the Xero App and, if you want to, becoming a Xero partner later.
In this step we create the App that a user can choose to install into their Xero instance to authorize the integration with your application.
* Navigate to the Xero [developer portal](https://developer.xero.com/app/manage/) and log in, if you are not already logged in.
* On the tab "my Apps", click "New App".
* In the pop-up, enter the below details:
* **App Name**: This should be your application's name. When your users link their Xero account, they will see that "App Name" is requesting to integrate with their Xero account.
* **Integration Type**: Web app.
* **Company** or **application URL**: The homepage of your company's website, e.g. `https://yourcompany.com/`.
* **Redirect URL**: Should be set to `https://api.maesn.dev/auth/callback/xero`.
Now it is time to generate the unique client secret for your App.
* Navigate to the Configuration tab of your newly created App
* Click the "Generate a secret" button.
* Note your `client id`, which you will need together with the `client secret` in subsequent steps.
* Copy the `client secret` by clicking the Copy button next to the value. Make sure that you have copied the value before navigating away from this page. Once navigating away, you will not be able to retrieve it again.
In the last step, we setup your API tenant with your App's details:
* Get in touch with your contact person at maesn to submit the client id and client secret.
If you are not sure who your technical contact is, do not hesitate to [reach out to us](https://www.maesn.com/contact).
## Becoming a Xero Partner
Anyone can become a Xero app partner. The requirements and steps to become a partner are detailed [here](https://developer.xero.com/documentation/xero-app-store/app-partner-guides/app-partner-steps/).
Note that it is only possible to link 25 Xero accounts to your app before it is certified through the app partnership process. In addition, your customers cannot link more than two applications that are not certified.
## Webhooks
Xero supports the following resources:
* `CONTACT`
* `INVOICE`
Xero sends `CREATED` and `UPDATED` events.
Before you start using webhooks for Xero, you will need to contact us to receive the callback URL to use in your Xero App configuration and complete the setup.
Inside your Xero app, you will choose the `resource` you want the webhooks enabled for. Once configured, this setup will be valid for all users of the app.
Now, for each authenticated end user, call Maesn’s create webhook endpoint `POST /webhooks` with the following body:
```javascript Example code snippet theme={null}
const response = await axios.post(url, {
"callbackUrl": callbackUrl
}, {
headers: {
'X-API-KEY': apiKey,
'X-ACCOUNT-KEY': accountKey
}
});
```
It will return the `id` associated with the subscription:
```json Example response theme={null}
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"callbackUrl": "https://example.com/webhook-endpoint/12345",
"createdDate": null,
"expiresDate": "null",
"secret": "2f1fd5f883d4c0adf5b31b91e4d6ae2d2975620c67bac8fdb864c78047b1d522"
"updatedDate": "null"
},
"meta": {}
}
```
At this point, your system is ready to receive end-user–related events at the callback URL you provided. Xero retrieves a list of events.
The event response will be an array providing the following information:
```json Example event body theme={null}
[{
"eventType": "CREATED",
"filterDate": null, //not supported by xero
"resource": "CONTACT",
"resourceId": "b15311cf-c0c1-46fe-b895-341b4b2eb005",
"userId": "1cb1fbcc-b9ed-4ed8-a8c2-40a7fa5c8047"
}]
```
To delete the webhook subscription, you can call the `DELETE` `/webhooks/{webhookId}` endpoint.
# Introduction
Source: https://docs.maesn.com/introduction
Introduction to Maesn Unified API for ERP and Accounting software.The documentation helps you to get started with the maesn API.
The maesn API provides a single API to integrate with a range of systems with similar capabilties. By providing a set of generic resources and standardized operations that are mapped and transformed to the resources and operations of the respective target systems, an integrator can implement a single integration workflow toward the unified API to integrate to all the supported target systems.
Resources are modeled after important concepts in the target systems, such as Accounts, Customers, Invoices, Suppliers, Transactions and others. They are exposed in the API through representations, where each representation provides the most useful way to interact with the resource within a certain use case.
We conform to the HTTP/1.1 protocol as described in the IETF RFCs 7230-7235 unless otherwise stated.
## Getting started with the API
Follow our [quick start guide](/guides/quick-start) to started right away.
## Calling conventions
When calling the API, the client should select a resource and HTTP method matching the expected operation result. The client then sends a request to the API and it replies with the response or returns an error.
The general convention for choosing an HTTP method is:
`POST` results in the creation of a new resource of a given type.
`GET` returns the given resource’s representation without any side effects.
`PATCH` partially or fully changes the state of the given resource.
`PUT` replaces a given resource or creates (upserts) a new resource if the given resource does not already exist.
`DELETE` removes or hides a given resource making it inaccessible.
## Responses
All responses are returned as JSON documents and will contain at least one of the top-level keys:
```json theme={null}
{
"meta": {},
"data": {},
"errors": {}
}
```
The keys have the following purposes:
* `meta`: A meta object that contains non-standard information (pagination, warnings, etc.). Including the meta key is optional.
* `data`: Contains the actual response information (requested resource representation). The document's "primary data".
* `errors`: An array of error objects.
The keys `data` and `errors` will never coexist in the same response.
The primary data is either:
* a single resource object, a single resource identifier object, or null, for requests that target single resources.
* an array of resource objects, an array of resource identifier objects, or an empty array (\[]), for requests that target resource collections.
## Standardized Data
Maesn uses internationally standardized formats for values such as country codes, currencies, and date formats to ensure consistency across all integrations.
See our [Standardized Data](/standardization) section to learn more.
## Feedback
If you have feedback or questions, don’t hesitate to [reach out](https://www.maesn.com/contact/) to us.
# DATEV BelegbilderService
Source: https://docs.maesn.com/knowledgebase/belegbilderservice
Documentation for setting up BelgebilderService in your DATEV instance
* You have an existing DATEV client (Mandant) and you have created a fiscal year for it
* DATEV Unternehmen Online is enabled
* The DATEV app Belege Online is activated in `erweitert` mode.
* You have a SmartCard or SmartLogin with access rights for Mandantenregistrierung
The BelegbilderService constitues a special case among the DATEV services: It is not possible to order it via Mandantenregistrierung, since it is enabled by default when DATEV Unternehmen Online is enabled.
* Open [DATEV Rechtevewaltung Online](https://apps.datev.de/rvo-administration/)
* Select the user, client or group that you want to assign the access rights for Unternehmen Online (and indirectly BelegbilderService).
* Assign the access right to the correct berater number and client number that corresponds to the client (Mandant)
![Image showing service selection in Mandantenregistrierung]()
# DATEV BuchungsdatenService
Source: https://docs.maesn.com/knowledgebase/buchungsdatenservice
Documentation for setting up BuchungsdatenService in your DATEV instance
* You have an existing DATEV client (Mandant) and you have created a fiscal year for it
* DATEV Unternehmen Online is enabled
* You have a SmartCard or SmartLogin with access rights for Mandantenregistrierung
From the client overview, select the client and click "MyDATEV Mandantenregistrierung"
![Image showing DATEV client overview with link to Mandantenregistrierung]()
Order BuchungsdatenService
![Image showing service selection in Mandantenregistrierung]()
Choose whether to create a new consultant number or use an existing one. Finalise the order.
* Open [DATEV Rechtevewaltung Online](https://apps.datev.de/rvo-administration/)
* Select the user, client or group that you want to assign the access rights for BuchungsdatenService
* Open "Rechnungswesen" and give access to "BuchungsdatenService"
* Assign the access right to the correct berater number and client number that corresponds to the client (Mandant)
![Image showing service selection in Mandantenregistrierung]()
# DATEV Datenservice export
Source: https://docs.maesn.com/knowledgebase/datenserviceexport
Documentation for setting up Datenservice export in your DATEV instance
* You have an existing DATEV client (Mandant) and you have created a fiscal year for it
* DATEV Unternehmen Online is enabled
* You have a SmartCard or SmartLogin with access rights for Mandantenregistrierung
From the client overview, select the client and click "MyDATEV Mandantenregistrierung"
![Image showing DATEV client overview with link to Mandantenregistrierung]()
Order Datenservice export
![Image showing service selection in Mandantenregistrierung]()
Choose whether to create a new consultant number or use an existing one. Finalise the order.
* Open [DATEV Rechtevewaltung Online](https://apps.datev.de/rvo-administration/)
* Select the user, client or group that you want to assign the access rights for Datenservice export
* Open "Rechnungswesen" and give access to "Datenservice Export Rechnungswesen"
* Assign the access right to the correct berater number and client number that corresponds to the client (Mandant)
![Image showing service selection in Mandantenregistrierung]()
# DATEV service configuration
Source: https://docs.maesn.com/knowledgebase/datev-service-configuration
Documentation for setting up your DATEV instance with API services
## Prerequisites
In order to enable the DATEV services mentioned below, the following prerequisites must be met:
* An existing DATEV instance with a fiscal year created.
* DATEV Unternehmen Online is enabled for the company (Mandant).
* The DATEV app Belege Online is activated in `standard` or `erweitert` mode, depending on the service.
* An access medium (SmartCard or SmartLogin) for secure access to the company.
* The person with the access medium has at least standard access rights for the Belege Online app.
Configure BelegbilderService to receive files in Unternehmen Online
Configure RechnungsdatenService v1.0 to receive booking proposals in Unternehmen Online
Configure BuchungsdatenService to receive journal entries in Rechnungswesen
Configure Datenservice export to read data from Rechnungswesen
## Useful links
### Prerequisites
* How to [order and activate Unternehmen Online](https://help-center.apps.datev.de/documents/1008596) (in German).
* How to [activate Belege Online](https://help-center.apps.datev.de/documents/1048478) (in German).
* How to [order and configure SmartLogin](https://help-center.apps.datev.de/documents/1080654) (in German).
* How to [configure user access rights](https://secure16.datev.de/dlpon/course/view.php?id=3100) through DATEV Rechteverwaltung Online (in German).
### Configuring the services
* How to [configure BelegbilderService, RechnungsDatenService v1.0 and BuchungsDatenService](https://www.datev.de/hilfe/1007329) via MyDATEV Mandantenregistrierung for tax consultancies (in German).
* How to [order and configure BelegbilderService](https://help-center.apps.datev.de/documents/1024114) (in German).
* How to [order and configure RechnungsdatenService v1.0](https://help-center.apps.datev.de/documents/1037210) (in German).
* How to [order and configure BuchungsdatenService](https://help-center.apps.datev.de/documents/1037208) (in German).
* How to [order Datenservice export](https://www.datev.de/hilfe/1039548) (in German).
### Video tutorials
* Video showing the [configuration of BuchungsdatenService](https://youtu.be/nWfT9mufp0c?si=e_TzWWIW7ehyal2_).
* Video showing how to [give access rights via Rechteverwaltung Online](https://www.youtube.com/watch?v=WTBpgMtYV_M).
# DATEV RechnungsdatenService v1.0
Source: https://docs.maesn.com/knowledgebase/rechnungsdatenservice
Documentation for setting up RechnungsDatenService v1.0 in your DATEV instance
* You have an existing DATEV client (Mandant) and you have created a fiscal year for it
* DATEV Unternehmen Online is enabled
* The DATEV app Belege Online is activated in `erweitert` mode.
* You have a SmartCard or SmartLogin with access rights for Mandantenregistrierung
From the client overview, select the client and click "MyDATEV Mandantenregistrierung"
![Image showing DATEV client overview with link to Mandantenregistrierung]()
Order RechnungsdatenService v1.0
![Image showing service selection in Mandantenregistrierung]()
Choose whether to create a new consultant number or use an existing one. Finalise the order.
* Open [DATEV Rechtevewaltung Online](https://apps.datev.de/rvo-administration/)
* Select the user, client or group that you want to assign the access rights for ExportdatenService
* Open "Rechnungswesen" and give access to "RechnungsdatenService"
* Assign the access right to the correct berater number and client number that corresponds to the client (Mandant)
![Image showing service selection in Mandantenregistrierung]()
# MCP Server
Source: https://docs.maesn.com/mcp-server
Technical documentation for the MCP Server and machine-to-machine communication.
## Overview
The Maesn MCP Server acts as a bridge between your AI agent and the Maesn Unified API.
Think of it as a translator: instead of manually writing API calls, your agent can use the MCP to access accounting data and perform actions across our 20+ supported accounting systems through a single unified interface.
## How it works
Once connected to an agent like Claude, the MCP server lets you interact with the Unified API through simple, natural conversations. You don’t need to know how to structure an API call, the MCP takes care of that for you.
1. **Ask your question in plain text**
Example: *“Show me all unpaid invoices for Company A.”*
2. **The MCP Server handles the request**
It validates your input, applies the right filters, injects authentication, and makes the correct call to the Unified API.
3. **Get clear results back**
The server returns structured data, and your agent explains it to you in plain language complete with invoice IDs, amounts, dates, and any other relevant details.
Almost all endpoints from the Maesn Unified API are available through our MCP server. You can explore the currently supported resources [here](https://github.com/maesndev/maesn-mcp?tab=readme-ov-file#available-resources). Whether you need to retrieve, create, or update data, the MCP server provides full support for the listed resources.
## Getting Started
You can now try out our MCP server locally in just a few steps! Start by cloning the [GitHub repository](https://github.com/maesndev/maesn-mcp) and installing the dependencies:
```bash theme={null}
git clone https://github.com/maesndev/maesn-mcp.git
cd maesn-mcp
npm install
```
Next, configure your agent. For Claude Desktop, this means updating your claude\_desktop\_configuration.json file so it knows how to connect to the MCP server:
```json theme={null}
{
"mcpServers": {
"maesn-mcp": {
"command": "node",
"args": [
"/apps/maesn-mcp/dist/main.js"
]
}
}
}
```
Finally, start the server using:
```bash theme={null}
npx nx serve maesn-mcp
```
For more detailed configuration instructions, check out the [README](https://github.com/maesndev/maesn-mcp).
Once the server is running and your agent is configured, you can start asking it to pull customer data, list invoices, create new bills, or anything else you want to try out.
Don’t have an API key for the MCP server? [Reach out](https://www.maesn.com/contact/)!
Make sure to configure your credentials in your environment file before using the MCP server.
# Passthrough
Source: https://docs.maesn.com/pass-through
The Maesn Passthrough Feature enables access to APIs that are not part of Maesn.
## Overview
The Maesn API supports **Passthrough requests**, enabling you to call external system endpoints even if they haven’t been explicitly implemented in our API.\
This feature allows you to send authenticated requests directly through our platform by specifying the target path and providing the necessary request data.
This section explains how to structure a Passthrough request and outlines all supported fields.
## Endpoint
Send a `POST` request to:
```http theme={null}
https://api.maesn.dev/accounting/passThrough
```
## Request Body
The body of your request should include the following fields:
**`path`**
* The relative path of the target endpoint (e.g., `/employees`, `/units`).
* Do **not** include the full URL, only the endpoint path segment.
* If you’re unsure which part of the URL to include, refer to the system-specific documentation below. It shows the `baseUrl` we store for each system, this portion should **not** be included in the `path`.
**`method`**
* The HTTP method to use. Supported values are `GET`, `POST`, `PUT`, `PATCH`, and `DELETE`.
**`body`**
* Required for `POST`, `PUT`, and `PATCH` requests.
* For REST API systems: Add all relevant fields directly inside the body object.
* For GraphQL systems: The request body object must include a field named query, containing your GraphQL query as a string.
* For SOAP systems: The body object must include a field named xml, containing your XML payload as a base64-encoded string.
## Headers
Include the following headers in your request:
`X-API-KEY`: Your Maesn API key.\
`X-ACCOUNT-KEY`: Your account-specific key.
## Query Parameters
If you are **not** using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), some systems may require additional parameters:
`environmentName`
`companyId`
Refer to the system-specific documentation below to confirm whether these are required for your request.
## System specific information
Please ensure the query parameter `environmentName` is accurately populated with the appropriate environment.
You can obtain this value by using the `GET Environments` endpoint available under the Authentication section.
`baseUrl`: The base URL for Abacus depends on the server configuration and may vary depending on whether Abacus is installed locally or hosted via a cloud subscription.\
This baseUrl must be provided by the user upon authentication. The base URL follows this structure:\
`https://{user-specific-baseurl}/api/entity/v1/mandants/{environmentName}/`\
Only include the part **after** this base in the `path` field.
`baseUrl`: Set to `https://api.bexio.com`.
Only include the part **after** this base in the `path` field.
`baseUrl`: Set to `https://webapp.buchhaltungsbutler.de/api/v1`.\
Only include the part **after** this base in the `path` field.\
**Note** - Please beware that BuchhaltungsButler's API only supports POST requests, even if you're retreiving data. The operation is reflected in the path.
If you're not using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), make sure the query parameters `environmentName` and `companyId` are correctly populated.
You can obtain these values by using the `GET Environments` and `GET Companies` endpoints available under the Authentication section.
`baseUrl`: Set to `https://api.businesscentral.dynamics.com/v2.0/{environmentName}/api/v2.0/companies({companyId})/`.\
Only include the part **after** this base in the `path` field.
`baseUrl`: Set to `https://api.dinero.dk`.
Only include the part **after** this base in the `path` field.
If you're not using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), make sure the query parameter `companyId` is correctly populated.
You can obtain this value by using the `GET Companies` endpoint available under the Authentication section.
`baseUrl`: Set to `https://start.exactonline.nl/api/v1/{companyId}/`.\
Only include the part **after** this base in the `path` field.
`baseUrl`: Set to `https://api.fortnox.se/3/`.\
Only include the part **after** this base in the `path` field.
`baseUrl`: Set to `https://api.freeagent.com/v2/`.\
Only include the part **after** this base in the `path` field.
Ensure that the query parameter `_companyId_` is correctly filled with the account ID associated with the contact.
This value can be retrieved by using the `GET Companies` endpoint in the Authentication section. Use the returned `id` as the value for `_companyId_`.
`baseUrl`: Set to `https://api.freshbooks.com/accounting/account/${companyId}/`.\
Only include the part **after** this base in the `path` field.
`baseUrl`: Set to ` https://api.holded.com/api/`.\
Only include the part **after** this base in the `path` field.
`baseUrl`: Set to `https://api.lexoffice.io/v1/`.\
Only include the part **after** this base in the `path` field.
If you're not using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), make sure the query parameter `companyId` is correctly populated.
You can obtain this value by using the `GET Companies` endpoint available under the Authentication section.
`baseUrl`: Set to `https://moneybird.com/api/v2/{companyId}/`.
Only include the part **after** this base in the `path` field with format : `:resource_path.:format`
`baseUrl`: Set to `https://app.pennylane.com/api/external/v2/`.
Only include the part **after** this base in the `path` field.
}>
`baseUrl`: Set to `https://thirdparty.qonto.com/`.\
Only include the part **after** this base in the `path` field.
`baseUrl`: Set to `https://quickbooks.api.intuit.com/v3/company/{realmId}/`.\
Only include the part **after** this base in the `path` field.
The `realmId` is stored automatically after user authentication. You do not need to provide it manually.
`baseUrl`: Set to `https://api.accounting.sage.com/v3.1/`.\
Only include the part **after** this base in the `path` field.
If you're not using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), make sure the query parameters `environmentName` and `companyId` are correctly populated.
You can obtain these values by using the `GET Companies` endpoint available under the Authentication section. Please use the id field as the companyId and the environmentId field as the environmentName.
`baseUrl`: Set to `https://api.de.active.sage.com/graphql`.\
Sage Active uses **GraphQL**, so you should **not** provide a `path`.\
Instead, include your GraphQL query in the request body.
Below is an example request body:
```json theme={null}
body: {
"query": "query { accountingAccounts(where: { id: { eq: \"203661a0-83d8-458a-a9a2-51866acf42f9\" }}) { edges { node { id creationDate modificationDate code name description deactivated accountLevel subAccountType accountType } } } }"
}
```
`baseUrl`: Set to `https://my.sevdesk.de/api/v1/`.\
Only include the part **after** this base in the `path` field.
`baseUrl`: Set to `https://b2bapi.snelstart.nl`.\
Only include the part **after** this base in the `path` field.
If you're not using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), make sure the query parameter `companyId` is correctly populated.
You can obtain this value by using the `GET Companies` endpoint available under the Authentication section.
Twinfield uses a **SOAP API**, so you do **not** need to provide a `path`.\
Instead, send only the contents of the `` section from your XML request, base64 encoded.
We wrap your request using the following envelope and headers:
```xml theme={null}
{user accessToken}
{companyId}
${your XML body}
```
Send your request like this:
```json theme={null}
body: {
"xml": ""
}
```
`baseUrl`: Set to `https://eaccountingapi.vismaonline.com/v2/`.\
Only include the part **after** this base in the `path` field.
`baseUrl`: Set to `https://restapi.e-conomic.com`.\
Only include the part **after** this base in the `path` field.
`baseUrl`: Set to `https://{weclappId}.weclapp.com/webapp/api/v1/`.\
Only include the part **after** this base in the `path` field.\
Note that the *weclappId* is stored by us upon authentication and does not need to be imcluded in the request.
`baseUrl`: Set to `https://{xentralId}.xentral.biz/api/`.\
Only include the part **after** this base in the `path` field.
Note that the *xentralId* is stored by us upon authentication and does not need to be imcluded in the request.
`baseUrl`: Set to `https://api.xero.com/api.xro/2.0/`.\
Only include the part **after** this base in the `path` field.
# Rate limiting
Source: https://docs.maesn.com/rate-limits
Learn how Maesn handles Rate Limiting for all supported systems.
For the moment maesn's unified APIs do not implement any specific rate limits. However, it is important to notice that the systems made available through the API implement their own rate limits and that these limits apply to our tenants.
## Automatic retry
It is considered good practice to implement retry logic when encountering specific error codes and this is especially true for error code 429: Too many requests. This error code indicates that the API is receiving requests at a higher rate than it can handle and unless a retry mecahnism is implemented, the requests will be lost.
The best practice for implementing retry logic is called "expontential backoff". We recommend to retry the request after an initial one-minute delay and increasing the delay exponentially with each additional retry. I.e. if a request fails due toe a 429 error, the first retry is made after one minute, the next after two minutes, then 4 minutes, etc.
For more information about handling various response codes and automatic retries, see our [error handling guide](/guides/error-handling).
## Target system rate limits
### AbaConnect
The AbaConnect Webservices only supports one active request at a time.
Source: [AbaConnect Webservice documentation](https://downloads.abacus.ch/fileadmin/ablage/abaconnect/zipfiles/documents/AbaConnect_UsingWebServices.pdf)
### abacus
For the abacus API, the following rate limits apply:
* 200 calls per minute
* 12'000 calls per hour
* 30'000 calls per day
Source: [abacus API documentation](https://apihub.abacus.ch/odata)
### bexio
The bexio API enforces a rate limit, that limits the number of requests per minute a client can make. Currently, the limit is not published.
Source: [bexio Developer Portal](https://docs.bexio.com/#section/API-basics/Rate-Limiting)
### BuchhaltungsButler
For the BuchhaltungsButler API, the following rate limits apply:
* 100 requests per customer per minute
Source: [BuchhaltungsButler API documentation](https://app.buchhaltungsbutler.de/docs/api/)
### DATEV Rechnungswesen
No rate-limits are known for the DATEV Online APIs at the time of writing.
### DATEV Unternehmen Online
No rate-limits are known for the DATEV Online APIs at the time of writing.
### Dinero
The Dinero API enforces a rate limit of 100 requests per minute, per organization, on a ClientID basis.
### Exact Online
For the Exact Online REST API, the following rate limits apply:
* Minutely limit - your app can make 60 API calls, per company, per minute.
* Daily limit - your app can make 5,000 API calls, per company, per day.
The following limits are effective as of 1 July 2021:
* You must not request new access token more than once every 10 minutes. You can only request for a new access token after 570 seconds from the time you successfully received the previous access token.
* No more than 10 errors per API key, per user, per company, per endpoint, and per hour. When you exceed this limit, your API key will be temporarily blocked from making further requests. The block will automatically be lifted after one hour and will gradually increase when you continue making these errors. Response code 400, 401, 403, and 404 are counted as errors.
* Mandatory filtering on single and bulk endpoints where sync APIs are available.
Based on fair use policy, Exact will take corrective action by throttling your app if the limit has been exceeded excessively. Some examples of excessive actions are repeated download of unchanged data every day, log in attempts to inactive accounts, and overloading the token endpoint.
Source: [Exact Online Knowledge Base](https://support.exactonline.com/community/s/knowledge-base#All-All-DNO-Simulation-gen-apilimits)
### fortnox
For the fortnox REST API, the following rate limit apply:
* The limit per access-token is 25 requests per 5 seconds. This equals to 300 requests per minute.
Source: [fortnox API documentation](https://api.fortnox.se/apidocs#section/Documentation/Rate-limits)
### FreeAgent
For FreeAgent API, the following rate limits apply:
* 120 user requests per minute
* 3600 user requests per hour
* 15 token refreshes per minute
Source: [FreeAgent API documentation](https://dev.freeagent.com/docs/introduction#rate-limits)
### FreshBooks
There is no published limit on the number of API requests for FreshBooks. However, they state that requests will be rate-limited if too many calls are made within a short period of time. Additionally, a maximum of 100 results will be returned for list methods, regardless of the value sent with the per\_page parameter.
Source: [FreshBooks API documentation](https://www.freshbooks.com/api/limits)
### Holded
The holded API has a rate-limit of 1500 requests per 60 seconds.
### Lexware Office
The Lexware API uses [the token bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket) to maintain a stable rate of requests against the resource endpoints. The limits refer to all endpoints of the Lexware API at the same time:
* A client can make up to 2 requests per second to the Lexware API.
Source: [Lexware Office API documentation](https://developers.lexware.io/docs/#lexware-api-documentation-introduction)
Separate rate-limits apply for the Lexware Office Partner API. Contact us for more information.
### Microsoft Business Central
Business Central imposes a range of strict and well-defined limits both per environment and user. Some examples:
* Per environment:
* 5 concurrent requests
* 100 concurrent connections
* 300/600 requests per minute in the sandbox/production environment
* Per user:
* 5 concurrent requests
* 100 concurrent connections
* 6000 requests within a 5-minute sliding window
Source: [Microsoft Developer Portal](https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/operational-limits-online)
### Moneybird
The Moneybird API has a rate-limit of 150 requests per 5 minutes.
### Odoo
1 call/sec is the official rate limit for Odoo.
### Pennylane
The Pennylane API has a rate-limit of 5 requests per second.
### Procountor
The Procountor API has a rate limit of maximum 60 requests per second per customer on production server.
### Qonto
Qonto implement the following rate limits:
* 1000 requests / 10 seconds
* 10000 requests / 10 minutes
### QuickBooks
QuickBooks implement the following rate limits and throttles:
* For Online API endpoints:
* 500 requests per minute per realm ID
* 10 concurrent requests per realm ID and app
* For Batch endpoints:
* Recommended maximum number of payloads in a single batch request is 30
* Throttled at 40 requests per minute, per realm ID
Source: [Intuit Developer Portal](https://developer.intuit.com/app/developer/qbo/docs/learn/rest-api-features#limits-and-throttles)
### Sage Active
To ensure the availability and integrity of Sage Active Public API V2, a rate limit of 3000 requests per application per minute has been set. The rate limit is set for each unique client application.
Source: [Sage Active Developer Portal](https://developer.sage.com/sageactive/concepts/bestpractices/)
### sevdesk
The sevdesk API enforces a rate limit, that limits the number of requests per minute a client can make. Currently, the limit is not published.
### Snelstart
The Snelstart API enforces a rate limit in the development and testing environment.
Each developer key is valid for 90 days and allows a limited number of API calls, though the exact limit is not publicly specified.
### Twinfield
Twinfield uses a system of "API credits". Query requests as defined below will cost 1 API credit, and ‘Other requests’ will cost 3 API credits.
All GET requests in the Maesn API fall under the ‘query requests‘ category with a cost of 1 API credit and all POST request fall under ‘Other requests’ with a cost of 3 API credits.
* Per IP Address
* 1000 API credits per minute
* Per ClientId
* 1000 API credits per minute
* Per OrganisationId
* 1000 API credits per minute
* Per ClientId and OrganisationId combination
* 500 API credits per minute
### Visma eAccounting
Visma eAccounting implements the following rate limits:
* 600 requests per minute
* Limit is registered per client and endpoint/URL
### Visma e-conomic
Visma e-conomic implements the following rate limits:
* 50.000 requests per 24 hours
### weclapp
The weclapp API enforces a rate limit, that limits the number of requests per minute a client can make. Currently, the limit is not published.
### Xentral
The Xentral API is currently rate limited independent of the plan to 100 requests/minute (one request per 600ms).
Bursts of up to 300 simultaneous requests are accepted and processed as follows:
* the first two requests are processed immediately
* the following requests (up to 300 requests) will be queued and processed with a fixed rate of one request per 600ms (300 requests in a burst will take up to three minutes to get processed).
* the response for the requests in a burst will be delayed until the request is processed.
The limits mentioned above are flagged as due to change. Please check the Xentral developer portal regularly for the latest values
Source: [Xentral Developer Portal](https://developer.xentral.com/reference/rate-limiting)
### Xero
Xero implements three types of rate limiting against the respective tenant:
* Concurrent calls: 5 calls in progress at one time
* Minute Limit: 60 calls in a rolling 60-second window
* Daily Limit: 5000 calls in a rolling 24-hour window
Source: [Xero Developer Portal](https://developer.xero.com/documentation/guides/oauth2/limits/)
# Raw Data
Source: https://docs.maesn.com/raw-data
The Maesn Raw Data Feature enables access to data that is not part of the common data model of Maesn.
## Overview
The maesn API provides a way to access raw data from the target systems. This is useful when you need to access data that is not covered by the unified responses of the maesn API.
The raw data functionality can be used for all the GET endpoints and is available for all target systems.
To enable raw data, you need to provide the `rawData` query parameter with the value `true` in your request.
The response will have the normal unified response, but next to it, you will receive the raw data in a `rawData` field.
```javascript Example code snippet theme={null}
const response = await axios.get(url, {
params: {
"rawData": true
},
headers: {
'X-API-KEY': apiKey,
'X-ACCOUNT-KEY': accountKey
}
});
```
## Example
Here is an example of how the raw data functionality works:
```json theme={null}
{
"data": [
{
"id": "123",
"name": "John Doe",
"email": "test@email.com"
}
],
"rawData": [
{
"id": "123",
"name": "John Doe",
"email": "test@emai.com",
"extraField": "extra data"
}
]
}
```
# Sandboxes
Source: https://docs.maesn.com/sandboxes
Use sandbox environments provided by maesn to test accounting integrations safely before going live.
Some providers offer free trial accounts that allows you to test Maesn’s functionality as a Proof of Concept.
Maesn offers sandboxes for all the system we support, including the ones that do not have free trial account, like DATEV, Fortnox and Twinfield. If you want to use Maesn-owned sandboxes populated with test data, please [contact us](https://www.maesn.com/contact/).
| System | Free trial | Provided by Maesn | Link to free trial | |
| :------------------------- | :--------: | :---------------: | --------------------------------------------------------------------------------------------------- | - |
| Ababau | - | ✅ | | |
| Abacus | - | ✅ | | |
| Bexio | ✅ | ✅ | [Register](https://www.bexio.com/de-CH/bexio-anmelden) | |
| Buchhaltungsbutler | ✅ | ✅ | [Register](https://app.buchhaltungsbutler.de/registrieren/) | |
| DATEV Rechnungswesen | - | ✅ | | |
| DATEV Unternehmen Online | - | ✅ | | |
| Dinero | ✅ | ✅ | [Register](https://dinero.dk/) | |
| Exact Online | ✅ | ✅ | [Register](https://www.exact.com/nl/probeer) | |
| Fortnox | - | ✅ | | |
| FreeAgent | ✅ | ✅ | [Register](https://signup.freeagent.com/signup) | |
| FreshBooks | ✅ | ✅ | [Register](https://www.freshbooks.com/en-eu/signup) | |
| Holded | ✅ | ✅ | [Register](https://app.holded.com/signup?lang=en) | |
| Lexware Office | ✅ | ✅ | [Register](https://app.lexware.de/signup/app/trial/) | |
| Microsoft Business Central | ✅ | ✅ | | |
| Moneybird | ✅ | ✅ | [Register](https://www.moneybird.com/aanmelden/) | |
| Odoo | ✅ | ✅ | [Register](https://www.odoo.com/trial) | |
| Pennylane | - | ✅ | | |
| Procountor | ✅ | ✅ | [Register](https://procountor.fi/tutustu/) | |
| Qonto | - | ✅ | [Register](https://developers.qonto.com/) | |
| QuickBooks | ✅ | ✅ | [Register](https://quickbooks.intuit.com/eu/) | |
| Sage Accounting | ✅ | ✅ | [Register](https://developer.sage.com/accounting/quick-start/set-up-the-basics/) | |
| Sage Active | - | ✅ | | |
| Sevdesk | ✅ | ✅ | [Register](https://sevdesk.de/register/) | |
| Snelstart | ✅ | ✅ | [Register](https://www.snelstart.nl/pakketten#tab-2) | |
| Tripletex | ✅ | ✅ | [Register](https://developer.tripletex.no/exciting-update-welcome-to-our-new-api-test-environment/) | |
| Twinfield | - | ✅ | | |
| Visma eAccounting | ✅ | ✅ | [Register](https://www.eaccounting.no/prov-gratis/) | |
| Visma e-conomic | ✅ | ✅ | [Register](https://www.e-conomic.dk/regnskabsprogram/demo-alle) | |
| Weclapp | ✅ | ✅ | [Register](https://www.weclapp.com/de/registrieren/) | |
| Xentral | - | ✅ | | |
| Xero | ✅ | ✅ | [Register](https://www.xero.com/signup/) | |
# TypeScript SDK
Source: https://docs.maesn.com/sdk
Use the official Maesn TypeScript SDK to interact with the unified API.
The Maesn TypeScript SDK is currently in **beta**. The API surface may change between releases. We recommend pinning to a specific version in production.
The Maesn TypeScript SDK lets you interact with the unified API from your TypeScript or JavaScript application. It provides full type safety, built-in error handling, and supports all endpoints available in the API reference.
The SDK is available on [npm](https://www.npmjs.com/package/@maesn/typescript-sdk) and is actively developed.
## Installation
Install the SDK using your preferred package manager:
```bash npm theme={null}
npm add @maesn/typescript-sdk
```
```bash pnpm theme={null}
pnpm add @maesn/typescript-sdk
```
```bash yarn theme={null}
yarn add @maesn/typescript-sdk
```
```bash bun theme={null}
bun add @maesn/typescript-sdk
```
The SDK is published as an ES Module (ESM) only. If your project uses CommonJS, import it with `await import("@maesn/typescript-sdk")`.
## Authentication
The SDK requires two API keys, which you can pass directly or load from environment variables:
| Key | Environment variable | Description |
| ------------ | -------------------- | ------------------------------------------------- |
| `apiKey` | `MAESN_API_KEY` | Authenticates your application with the Maesn API |
| `accountKey` | `MAESN_ACCOUNT_KEY` | Identifies the end user's connected target system |
See the [authentication guide](/authentication) for how to obtain these keys.
## Example
The following example initializes the client and fetches a list of invoices for a connected end user:
```typescript theme={null}
import { Maesn } from "@maesn/typescript-sdk";
const maesn = new Maesn({
serverURL: "https://api.maesn.dev",
security: {
apiKey: process.env["MAESN_API_KEY"] ?? "",
accountKey: process.env["MAESN_ACCOUNT_KEY"] ?? "",
},
});
const result = await maesn.accounting.retrieveInvoices();
console.log(result);
```
Replace the environment variables with your actual API key and account key.
# Standardized Data
Source: https://docs.maesn.com/standardization
Technical explanation of standardized values used across all accounting integrations.
## ISO standardization
Maesn enforces international standards for all input and output data to ensure consistency.
All formats follow specifications published by the **International Organization for Standardization (ISO)**.
Any value not conforming to these standards may be rejected by the API.
### Country codes
Maesn uses **ISO 3166-1 alpha-2** country codes (two-letter uppercase).
These codes are required anywhere a country is referenced in the API.
**Supported Country Codes:**
`AD`, `AE`, `AF`, `AG`, `AI`, `AL`, `AM`, `AO`, `AQ`, `AR`, `AS`, `AT`, `AU`, `AW`, `AX`, `AZ`, `BA`, `BB`, `BD`, `BE`, `BF`, `BG`, `BH`, `BI`, `BJ`, `BL`, `BM`, `BN`, `BO`, `BQ`, `BR`, `BS`, `BT`, `BV`, `BW`, `BY`, `BZ`, `CA`, `CC`, `CD`, `CF`, `CG`, `CH`, `CI`, `CK`, `CL`, `CM`, `CN`, `CO`, `CR`, `CU`, `CV`, `CW`, `CX`, `CY`, `CZ`, `DE`, `DJ`, `DK`, `DM`, `DO`, `DZ`, `EC`, `EE`, `EG`, `EH`, `ER`, `ES`, `ET`, `FI`, `FJ`, `FK`, `FM`, `FO`, `FR`, `GA`, `GB`, `GD`, `GE`, `GF`, `GG`, `GH`, `GI`, `GL`, `GM`, `GN`, `GP`, `GQ`, `GR`, `GS`, `GT`, `GU`, `GW`, `GY`, `HK`, `HM`, `HN`, `HR`, `HT`, `HU`, `ID`, `IE`, `IL`, `IM`, `IN`, `IO`, `IQ`, `IR`, `IS`, `IT`, `JE`, `JM`, `JO`, `JP`, `KE`, `KG`, `KH`, `KI`, `KM`, `KN`, `KP`, `KR`, `KW`, `KY`, `KZ`, `LA`, `LB`, `LC`, `LI`, `LK`, `LR`, `LS`, `LT`, `LU`, `LV`, `LY`, `MA`, `MC`, `MD`, `ME`, `MF`, `MG`, `MH`, `MK`, `ML`, `MM`, `MN`, `MO`, `MP`, `MQ`, `MR`, `MS`, `MT`, `MU`, `MV`, `MW`, `MX`, `MY`, `MZ`, `NA`, `NC`, `NE`, `NF`, `NG`, `NI`, `NL`, `NO`, `NP`, `NR`, `NU`, `NZ`, `OM`, `PA`, `PE`, `PF`, `PG`, `PH`, `PK`, `PL`, `PM`, `PN`, `PR`, `PT`, `PW`, `PY`, `QA`, `RE`, `RO`, `RS`, `RU`, `RW`, `SA`, `SB`, `SC`, `SD`, `SE`, `SG`, `SH`, `SI`, `SJ`, `SK`, `SL`, `SM`, `SN`, `SO`, `SR`, `SS`, `ST`, `SV`, `SX`, `SY`, `SZ`, `TC`, `TD`, `TF`, `TG`, `TH`, `TJ`, `TK`, `TL`, `TM`, `TN`, `TO`, `TR`, `TT`, `TV`, `TW`, `TZ`, `UA`, `UG`, `UM`, `US`, `UY`, `UZ`, `VA`, `VC`, `VE`, `VG`, `VI`, `VN`, `VU`, `WF`, `WS`, `YE`, `YT`, `ZA`, `ZM`, `ZW`
### Dates and Timestamps
All date and datetime fields in the Maesn API use ISO 8601 format. The two formats we allow are:
1. Date without timestamp:
```json theme={null}
2026-01-01
```
2. Date with UTC timestamp:
```json theme={null}
2026-01-01T14:15:06Z
```
We do not allow any other formats, such as dates with timezone offsets like `2026-01-01T14:15:06+02:00`.
This applies to all places where dates are used:
* Filters such as `lastModifiedAt`
* Fields like `createdDate` and `updatedDate`
* Any other date or datetime value
As all our supported systems handle dates in different ways, these are the two automatic conversions that will be applied if the date format doesn't match the system requirements:
1. **Date → DateTime Conversion**
If you send a date without a timestamp (e.g., `2026-01-01`), and the system or field requires a timestamp (for example, `lastModifiedAt` often requires timestamps), we will add midnight UTC to that date. The result will be `2026-01-01T00:00:00Z`.
2. **DateTime → Date Conversion**
If you send a timestamp (e.g., `2026-01-01T00:00:00Z`), and the system or field does not support timestamps (for example, `dueDate` seldom supports timestamps), we will simply exclude the timestamp and use the date only. The result will be `2026-01-01`.
### Currencies
Currencies are always represented using ISO 4217 three-letter currency codes (uppercase).
**Supported Currencies**
`AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BRL`, `BSD`, `BTN`, `BWP`, `BYR`, `BZD`, `CAD`, `CDF`, `CHF`, `CLP`, `CNY`, `COP`, `CRC`, `CUC`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EEK`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GQE`, `GTQ`, `GYD`, `HKD`, `HNL`, `HRK`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LTL`, `LVL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRO`, `MUR`, `MVR`, `MWK`, `MXN`, `MYR`, `MZM`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `RUB`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLL`, `SOS`, `SRD`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `UYU`, `UZS`, `VEB`, `VND`, `VUV`, `WST`, `XAF`, `XCD`, `XDR`, `XOF`, `XPF`, `YER`, `ZAR`, `ZMK`, `ZWR`
### Document status fields
Transactional documents (invoices, bills, credit notes, and vendor credits) expose two related but distinct fields for state. They are not interchangeable, and confusing them is a common integration mistake.
#### `status`: document lifecycle
The authoritative state of the document in its lifecycle — for example `DRAFT`, `OPEN`, `PARTIALLY_PAID`, `PAID`, `OVERDUE`, or `VOIDED`. This field is populated across all source systems. Use it as the single source of truth for lifecycle and paid/unpaid logic.
#### `paymentStatus`: payment / open-item view
A finer-grained view of the payment or open-item state — for example `PENDING`, `PARTLY_PAID`, or `PAID`. It is **best-effort**: only some source systems populate it, and for every other system it is returned as `null`. It is not a reliable substitute for `status`.
#### General guidlines
Default to `status` for lifecycle and paid/unpaid logic. Treat `paymentStatus` as supplementary detail only, and always handle the `null` case.
The exact set of enum values differs per document type and per source system. See each endpoint response schema for the full list that applies to that document.
# Explore our use cases
Source: https://docs.maesn.com/use-cases
Use these cookbook-style recipies to understand how your product could work with the Maesn API.
## Use cases
Capture invoices and bills into accounting platforms
Retrieve invoices, payments and dunning data to manage debt
Retrieve invoices from any accounting platform
Retrieve bills from any accounting software
Synchronize customers and suppliers across systems
Automate classification and synchronization of expenses
Automate synchronization of products/articles
Automate invoice creation
Automate vendor payment reconciliation
Automate customer payment reconciliation
Post booking data into any system
Explore the use cases supported by DATEV
## Terminology
To navigate the use cases above, a short introduction to terminology may be helpful.
### Invoices vs bills
* When we refer to `invoices`, we are talking about outgoing invoices or customer invoices (accounts receivable).
* When we talk about `bills`, we mean incoming invoices or supplier invoices (accounts payable).
### Create vs capture
* When you `create` an invoice, you are creating (or issuing) the original document in the bookkeeping systems. Typically, a PDF-file is created in the bookkeeping after the invoice has been created and sent to the customer.
* In contrast, when you `capture` (or import) an invoice you are uploading a copy of an invoice originally created elsewhere in your bookkeeping system. Typically, the invoice is imported in teh form of a PDF-file and, optionally, additional detailed data.
### Bookings vs booking proposals
* A `booking proposal` is a draft or suggested booking that has not been finalized yet. It is not yet commited to the general ledger and can be freely edited or deleted without affecting the accounts. As an example, importing a bill into a bookkeeping system is typically a booking proposal until it has been manually verfied by an accountant.
* A `booking` is a finalized and commited entry in the general ledger. It is part of official accounting records and often legally binding. As an example, a booking proposal that has been approved and booked against a counter account on the general ledger by the accountant, is a booking.
## Glossary
The full list of resources in our Accounting API is available in the [accounting overview](/api-reference/accounting-endpoints/accounting-overview)
# Create and update contacts in DATEV Rechnungswesen
Source: https://docs.maesn.com/use-cases/DATEV-Rechnungswesen-create-update-contacts
Simplify the creation and updating of creditor and debitor records in DATEV Rechnungswesen.
## Create contacts in Datev in 10 steps
**Required**: Before getting started, ensure that your end users have the `Buchungsdatenservice` enabled in their DATEV accounts
Your end user must first authorize your application to access their data in DATEV Rechnungswesen through [maesn Connect](/guides/maesn-connect).
Fetch all the companies associated to your end users's DATEV account using the GET [/companies](/api-reference/auth/get-companies) endpoint. The user will need to select a company to proceed, as the company ID will be needed for subsequent steps.
Note that you can use the [interactive authentication flow](/authentication#interactive-authentication-flow) to eliminate this step.
Fetch the user info associated to your end users's DATEV account using the GET [/userInfo](/api-reference/user-endpoints/user/user-info) endpoint. Display the retrieved information in your application's UI as required by DATEV (see 'general requirements' below).
At this point, decide whether your use case requires
- Create or update individual contacts : proceed with `Individual contacts`.
- Create or update a miscellaneous account : proceed with `Miscellaneous account`.
Check the status of the contacts batch using the GET [/asyncTask](/api-reference/accounting-endpoints/asynctask) endpoint. This will allow you to verify if the batch was successfully processed by DATEV.
Read more about asynchronous tasks [here](/async-task)
Review the DATEV interface [requirements](https://developer.datev.de/en/guides/interface-requirements) to ensure that your application complies with DATEV’s specifications.
Optional:
If your user deletes their account, you may delete the end user from our API and revoke their token using the the POST [/delete-end-users](/api-reference/accounting-endpoints/tenants/delete-end-user). This step ensures both actions are handled on the backend.
## Individual contacts
It is possible to create individual contacts in DATEV Rechnungswesen, which are typically used for specific customers, suppliers, or other business partners. Each contact is identified by a unique `accountNumber`, which is essential for managing and referencing these contacts within the DATEV system.
Debtor account numbers are usually assigned in the range from 10000 to 69999. Creditor account numbers, on the other hand, usually lie in the range from 70000 to 99999.
To create or update individual contacts, use the POST [/contacts/bulk](/api-reference/accounting-endpoints/contacts/create-contacts-bulk) endpoint. This endpoint allows you to create new contacts or update existing ones by providing the necessary details.
- To `create` individual contacts, each contact entry in the JSON request must have a unique dedicated `accountNumber` (e.g. `10000`, `10001`, `70000`, `70001` etc.). If a contact with the provided accountNumber already exists, it will be updated automatically.
- To `update` existing contacts, provide the `accountNumber` field for each contact in the list with the account number of the contacts you want to update. If a contact with the specified accountNumber does not exist, a new contact will be created.
## Miscellaneous account
DATEV allows the creation of `miscellaneous accounts` ("Diverse Addressen" in DATEV) to group and manage business partners who do not have individual account numbers.
This approach is useful for managing one-time customers or suppliers — for example, when issuing an invoice to a partner with whom there is unlikely to be future collaboration.
Instead of creating a new account for each of these partners, all their transactions can be posted to a shared miscellaneous account, thereby simplifying bookkeeping.
IMPORTANT: To create and use a miscellaneous account, the end user must first activate OPOS (Offene-Posten-Buchführung) in their DATEV client. This enables open item accounting, which is required for tracking individual transactions under shared miscellaneous accounts.
To create a miscellaneous account, use the POST [/contacts/bulk](/api-reference/accounting-endpoints/contacts/create-contacts-bulk) endpoint.
- To `create` a miscellaneous account, all contact entries in the JSON request must share the same dedicated `accountNumber`, indicating they belong to the new shared account. (e.g. `20000`). If a shared account associated to the provided `accountNumber` already exists, the new contacts are added to it.
- The `update` function is not directly applicable to miscellaneous accounts, as they are designed to group multiple contacts under a single account number. However, it is possible to add new contacts to an existing miscellaneous account.
# Create bookings in DATEV Rechnungswesen
Source: https://docs.maesn.com/use-cases/DATEV-Rechnungswesen-upload-journalentries
Easily create journal entries in DATEV for accounting and tax purposes
## Create journal entries in Datev in 10 steps
**Required**: Before getting started, ensure that your end users have the `Belegbilderservice` and `Buchungsdatenservice` enabled in their DATEV accounts
Your end user must first authorize your application to access their data in DATEV Rechnungswesen through [maesn Connect](/guides/maesn-connect).
Fetch all the companies associated to your end users's DATEV account using the GET [/companies](/api-reference/auth/get-companies) endpoint. The user will need to select a company to proceed, as the company ID will be needed for subsequent steps.
Note that you can use the [interactive authentication flow](/authentication#interactive-authentication-flow) to eliminate this step.
Fetch the user info associated to your end users's DATEV account using the GET [/userInfo](/api-reference/user-endpoints/user/user-info) endpoint. Display the retrieved information in your application's UI as required by DATEV (see 'general requirements' below).
At this point, determine whether your use case requires attaching files (e.g. PDFs) to the journal entries data:
- If yes, proceed with the steps below to fetch document-related data and upload files.
- If not, skip directly to the "Create journal entries" step below.
Fetch the relevant document types from your end users's DATEV account using the GET [/documentTypes](/api-reference/accounting-endpoints/files/get-document-types) endpoint. The document types will be used to categorize the files you will upload. These may, for example, be presented to the end user as a drop-down menu at the point of file upload.
IMPORTANT: it is sufficient to call the endpoint once per user, as the document types are not expected to change frequently.
If necessary, confirm the file extensions supported by the selected end user company (Mandant) by calling the GET [/documentExtensions](/api-reference/accounting-endpoints/files/get-document-extensions).
IMPORTANT: like in the step above, this endpoint should be called only once per user.
Upload the document to DATEV using the POST [/files](/api-reference/accounting-endpoints/files/upload-file) endpoint and save the retrieved file id . Make sure to include all the required fields in the request body. Ensure your application checks the file size before uploading to avoid performance issues (see last step).
Create the journal entries list and upload it to Rechnungswesen using the POST [/journalEntries](/api-reference/accounting-endpoints/journalentries/create-journal-entries-bulk) endpoint. Make sure to include all the required fields in the request body. You can include the document id of the uploaded document in the request.
Check the status of the journal entries list using the GET [/asyncTask](/api-reference/accounting-endpoints/asynctask) endpoint. This will allow you to verify if the batch was successfully processed by DATEV.
Read more about asynchronous tasks [here](/async-task)
Review the DATEV interface [requirements](https://developer.datev.de/en/guides/interface-requirements) to ensure that your application complies with DATEV’s specifications.
Optional:
If your user deletes their account, you may delete the end user from our API and revoke their token using the the POST [/delete-end-users](/api-reference/accounting-endpoints/tenants/delete-end-user). This step ensures both actions are handled on the backend.
# Capture invoices & bills in DATEV Unternehmen Online
Source: https://docs.maesn.com/use-cases/DATEV-Unternehmen-online-upload-booking-proposals
Implement easy generation and transfer of booking proposals to DATEV for accounting and tax purposes
There are two different ways to capture invoices, bills and credit notes as booking proposals in DATEV Unternehmen Online:
1. Upload documents, e.g., PDF-files, and letting Unternehmen Online capture the data using optical character recognition (OCR)
2. Upload the documents together with structured data to provide more detail than visible on the document and avoid mistakes due to OCR-failures
The two approaches are described in the respective sections below.
## Upload files to Datev in 7 steps
**Required**: Before getting started, ensure that your end users have the `Belegbilderservice` enabled in their DATEV accounts
Your end user must first authorize your application to access their data in DATEV Unternehmen Online through [maesn Connect](/guides/maesn-connect).
Fetch all the companies associated to your end users's DATEV account using the GET [/companies](/api-reference/auth/get-companies) endpoint. The user will need to select a company to proceed, as the company ID will be needed for subsequent steps.
Note that you can use the [interactive authentication flow](/authentication#interactive-authentication-flow) to eliminate this step.
Fetch the user info associated to your end users's DATEV account using the GET [/userInfo](/api-reference/user-endpoints/user/user-info) endpoint. Display the retrieved information in your application's UI as required by DATEV (see 'general requirements' below).
Fetch the relevant document types from your end users's DATEV account using the GET [/documentTypes](/api-reference/accounting-endpoints/files/get-document-types) endpoint. The document types will be used to categorize the files you will upload. These may, for example, be presented to the end user as a drop-down menu at the point of file upload.
IMPORTANT: it is sufficient to call the endpoint only once per user, as the document types are not expected to change frequently.
If necessary, confirm the file extensions supported by the selected end user company (Mandant) by calling the GET [/document-extensions](/api-reference/accounting-endpoints/files/get-document-extensions).
IMPORTANT: like in the step above, this endpoint should be called only once per user.
Upload the document to DATEV using the POST [/files](/api-reference/accounting-endpoints/files/upload-file) endpoint. Make sure to include all the required fields in the request body. Ensure your application checks the file size before uploading to avoid performance issues (see last step).
Review the DATEV interface [requirements](https://developer.datev.de/en/guides/interface-requirements) to ensure that your application complies with DATEV’s specifications.
Optional:
If your user deletes their account, you may delete the end user from our API and revoke their token using the the POST [/delete-end-users](/api-reference/accounting-endpoints/tenants/delete-end-user). This step ensures both actions are handled on the backend.
## Upload files together with structured data to Datev in 7 steps
**Required**: Before getting started, ensure that your end users have the `Rechnungsdatenservice 1.0` enabled in their DATEV accounts. In addition, they must have at least one `fiscal year` set up and the necessary access rights to write `accounts payable (bills)` and `accounts receivable (invoices)`.
These permissions are required for posting financial data through the API.
Your end user must first authorize your application to access their data in DATEV Rechnungswesen through [maesn Connect](/guides/maesn-connect).
Fetch all the companies associated to your end users's DATEV account using the GET [/companies](/api-reference/auth/get-companies) endpoint. The user will need to select a company to proceed, as the company ID will be needed for subsequent steps.
Note that you can use the [interactive authentication flow](/authentication#interactive-authentication-flow) to eliminate this step.
Fetch the user info associated to your end users's DATEV account using the GET [/userInfo](/api-reference/user-endpoints/user/user-info) endpoint. Display the retrieved information in your application's UI as required by DATEV (see last step).
Fetch the available ledgers from your end users's DATEV account using the GET [/accounts](/api-reference/accounting-endpoints/accounts/get-accounts) endpoint. The user will need to select a ledger to proceed, as the ledger is required for the subsequent steps.
Create the booking proposal and upload it to DATEV Unternehmen Online using the POST [/bookingProposals](/api-reference/accounting-endpoints/bookingproposals/create-booking-proposal) endpoint. Make sure to include all the required fields in the request body. You can include multiple files in the request.
Check the status of the upload using the GET [/asyncTask](/api-reference/accounting-endpoints/asynctask) endpoint. This will allow you to verify if the upload was successfully processed by DATEV.
Read more about asynchronous tasks [here](/async-task)
Review the DATEV interface [requirements](https://developer.datev.de/en/guides/interface-requirements) to ensure that your application complies with DATEV’s specifications.
Optional:
If your user deletes their account, you may delete the end user from our API and revoke their token using the the POST [/delete-end-users](/api-reference/accounting-endpoints/tenants/delete-end-user). This step ensures both actions are handled on the backend.
# Retrieve accounting data from DATEV Rechnungswesen
Source: https://docs.maesn.com/use-cases/DATEV-retrieve-data
Gain exclusive early access to reading data from DATEV
## Fetch data from Datev in 5 steps
**Required**: End users must have the `Datenservice Export Rechnungswesen` enabled in their DATEV accounts
Speak to your customer success manager at Maesn to learn how to enable this service.
Your end user must first authorize your application to access their data in DATEV Rechnungswesen through [maesn Connect](/guides/maesn-connect).
Fetch all the companies associated to your end users's DATEV account using the GET [/companies](/api-reference/auth/get-companies) endpoint. The user will need to select a company to proceed, as the company ID will be needed for subsequent steps.
Note that you can use the [interactive authentication flow](/authentication#interactive-authentication-flow) to eliminate this step.
Fetch the user info associated to your end users's DATEV account using the GET [/userInfo](/api-reference/user-endpoints/user/user-info) endpoint. Display the retrieved information in your application's UI as required by DATEV (see 'general requirements' below).
Fetch the data you always dreamed of retrieving from the API instead of CSV exports:
* Retrieve GL accounts using the GET [/accounts](/api-reference/accounting-endpoints/accounts/get-accounts) endpoint
* Retrieve fiscal years through the GET [/fiscalYears](/api-reference/accounting-endpoints/fiscalyears/get-fiscal-years) endpoint
* Retrieve booking data using the GET [/journalEntries](/api-reference/accounting-endpoints/journalentries/get-journal-entries) endpoint
* Retrieve payment terms through the GET [/paymentTerms](/api-reference/accounting-endpoints/paymentterms/get-payment-terms) endpoint
* Retrieve sums and balances for your accounts using the GET [/trialBalance](/api-reference/accounting-endpoints/trialbalance/get-trial-balance) endpoint
Review the DATEV interface [requirements](https://developer.datev.de/en/guides/interface-requirements) to ensure that your application complies with DATEV’s specifications.
Optional:
If your user deletes their account, you may delete the end user from our API and revoke their token using the the POST [/delete-end-users](/api-reference/accounting-endpoints/tenants/delete-end-user). This step ensures both actions are handled on the backend.
## DATEV-Specific Technical Details
For technical insights and detailed explanations of DATEV-specific fields and behaviors (such as account functions, accounting reasons, and data relationships), [contact Maesn](https://www.maesn.com/contact/).
# Accounts payable
Source: https://docs.maesn.com/use-cases/accounts-payable
Step-by-step API guide for implementing unified accounts payable workflows with Maesn Unified API.
## 8 steps to implement accounts payable
Start by implementing the [synchronize contacts](/use-cases/sync-contacts) use case to ensure that the suppliers across your database and your user’s accounting platform are in sync.
You will usually need to specify a general ledger account for bills and payments. Fetch it from the user's accounting platform by calling the GET [/accounts](/api-reference/accounting-endpoints/accounts/get-accounts) endpoint.
Retrieve available tax rates from the accounting platform with GET [/taxRates](/api-reference/accounting-endpoints/taxrates/get-tax-rates).
If your users use classes, locations, departments or other dimensions configured, you can retrieve them from the accounting platform with GET [/dimensions](/api-reference/accounting-endpoints/dimensions/get-dimensions).
Presenting the data retrieved in the previous steps in your frontend, enable your user to configure rules for categorizing the bills and payments that will be synchronized to the accounting platform. The business logic will depend on your application, but bear in mind that:
* If your user only wants to synchronize their bills and payments against one single GL account respectively, a simple dropdown menu to select the account may be sufficient.
* Users may want to categorize expenses based on conditional logic, such as "if Department = IT, use Account A". This will require more from your UI!
* You may want to give your users the possibility to categorize the transaction at the time when they synchronize it to their accounting service, which would imply that no pre-categorization is required in the configuration or that it is possible to override the configuration.
* Depending on your use case, the accounting platform you are integrating to and the legislation of the country you operate in, you may want to automatically configure certain tax rates for certain categories or allow your users to manually select the tax rate for each individual expense.
* Likewise, dimensions may follow categories or be presented for selection for the respective expense.
Create a bill in your user's accounting platform by calling POST [/bills](/api-reference/accounting-endpoints/bills/create-bill).
It is up to your application whether bills should be synchronized automatically or require an end user to manually export the bill from within your application.
Create a payment in your user's accounting platform by calling POST [/payments](/api-reference/accounting-endpoints/payments/create-payment).
It is up to your application whether payments should be synchronized automatically or require an end user to manually export the payment from within your application.
After fetching data initially, you should make sure to keep your user's data up to date by regularly retrieving data from the maesn API and looking for changes. The `lastModifiedAt` query parameter can be utilized on all our GET endpoints to save you the hassle of creating deltas to detect change. See our [guide to keeping data fresh](/guides/keep-data-fresh) for more information!
You can utilize Webhooks to make this process more efficient.
# Accounts receivable
Source: https://docs.maesn.com/use-cases/accounts-receivable
Technical walkthrough for accounts receivable workflows using the Maesn Unified API.
## 8 steps to implement accounts receivable
Start by implementing the [synchronize contacts](/use-cases/sync-contacts) use case to ensure that the customers across your database and your user’s accounting platform are in sync.
You will usually need to specify a general ledger account for invoices and payments. Fetch it from the user's accounting platform by calling the GET [/accounts](/api-reference/accounting-endpoints/accounts/get-accounts) endpoint.
Retrieve available tax rates from the accounting platform with GET [/taxRates](/api-reference/accounting-endpoints/taxrates/get-tax-rates).
If your users use classes, locations, departments or other dimensions configured, you can retrieve them from the accounting platform with GET [/dimensions](/api-reference/accounting-endpoints/dimensions/get-dimensions).
Presenting the data retrieved in the previous steps in your frontend, enable your user to configure rules for categorizing the invoices and payments that will be synchronized to the accounting platform. The business logic will depend on your application, but bear in mind that:
* If your user only wants to synchronize their invoices and payments against one single GL account respectively, a simple dropdown menu to select the account may be sufficient.
* Users may want to categorize expenses based on conditional logic, such as "if Department = IT, use Account A". This will require more from your UI!
* You may want to give your users the possibility to categorize the transaction at the time when they synchronize it to their accounting service, which would imply that no pre-categorization is required in the configuration or that it is possible to override the configuration.
* Depending on your use case, the accounting platform you are integrating to and the legislation of the country you operate in, you may want to automatically configure certain tax rates for certain categories or allow your users to manually select the tax rate for each individual expense.
* Likewise, dimensions may follow categories or be presented for selection for the respective expense.
Create an invoice in your user's accounting platform by calling POST [/invoices](/api-reference/accounting-endpoints/invoices/create-invoice) or, if the original customer invoice was already created on another platform, use POST [/bookingProposals](/api-reference/accounting-endpoints/bookingproposals/create-booking-proposal) to upload it.
It is up to your application whether invoices should be synchronized automatically or require an end user to manually export the invoice from within your application.
Create a payment in your user's accounting platform by calling POST [/payments](/api-reference/accounting-endpoints/payments/create-payment).
It is up to your application whether payments should be synchronized automatically or require an end user to manually export the payment from within your application.
After fetching data initially, you should make sure to keep your user's data up to date by regularly retrieving data from the maesn API and looking for changes. The `lastModifiedAt` query parameter can be utilized on all our GET endpoints to save you the hassle of creating deltas to detect change. See our [guide to keeping data fresh](/guides/keep-data-fresh) for more information!
You can utilize Webhooks to make this process more efficient.
# Capture invoices & bills
Source: https://docs.maesn.com/use-cases/capture-invoices
Step-by-step technical guide to capture invoices and bills from accounting systems using the Maesn Unified API.
## 5 steps to implement capturing of invoices
Start by implementing the [synchronize contacts](/use-cases/sync-contacts) use case to ensure the customers and/or suppliers across your database and your user’s accounting platform are in sync.
You will usually need to specify a general ledger account for the captured document. Fetch it from the user's accounting platform by calling the GET [/accounts](/api-reference/accounting-endpoints/accounts/get-accounts) endpoint.
Call the GET [/taxRates](/api-reference/accounting-endpoints/taxrates/get-tax-rates) endpoint to fetch the tax rates or tax codes available in in the accounting platform.
Decide when to transfer invoices to your user’s accounting platform. It could be a button within your application's frontend, listening for a specific event or according to a schedule (e.g. nightly).
Upload the document and complimentary data to your user's accounting platform by calling POST [/bookingProposals](/api-reference/accounting-endpoints/bookingproposals/create-booking-proposal).
Want to create a new invoice or bill? You are likely looking for the [create invoice](/use-cases/create-invoices) use case
# Create bookings
Source: https://docs.maesn.com/use-cases/create-bookings
Step-by-step technical guide to create accounting bookings via the Unified API.
## Create journal entries in 5 steps
Your user must first authorize your application to access their accounting platform (e.g., Exact Online, Xero, QuickBooks) via an authorization flow (e.g., OAuth, API key) through [maesn Connect](/guides/maesn-connect).
You will usually need to specify a an account and a contra account for each journal entry. These could be stored in your database or be based on user input, but most likely it will be sensible to fetch it from the user's accounting platform by calling the GET [/accounts](/api-reference/accounting-endpoints/accounts/get-accounts) endpoint.
Call the GET [/taxRates](/api-reference/accounting-endpoints/taxrates/get-tax-rates) endpoint to fetch the tax rates or tax codes available in in the accounting platform.
If your users use classes, locations, departments or other dimensions configured, you can retrieve them from the accounting platform with GET [/dimensions](/api-reference/accounting-endpoints/dimensions/get-dimensions).
For systems that support multiple journals, the journals can be retrieved with GET [/journals](/api-reference/accounting-endpoints/journals/get-journals).
Decide when to transfer invoices to your user’s accounting platform. It could be a button within your application's frontend, listening for a specific event or according to a schedule (e.g. nightly).
Create the booked transaction in your user's accounting platform by calling POST [/journalEntries](/api-reference/accounting-endpoints/journalentries/create-journal-entry).
Note that it is possible to upload attachments, such as receipts, statements and vouchers, by using the `files` and `filesPos` fields in the multipart form.
Some systems, like DATEV Rechnungswesen, supports the creation of bookings in [bulk](/api-reference/accounting-endpoints/journalentries/create-journal-entries-bulk)
# Create invoices
Source: https://docs.maesn.com/use-cases/create-invoices
Technical step-by-step documentation for creating invoices in your customers ERP based on structured data via the Maesn Unified API.
## Create invoices in other systems in 5 steps
Start by implementing the [synchronize contacts](/use-cases/sync-contacts) use case to ensure the customers across your database and your user’s accounting platform are in sync.
You will usually need to specify a general ledger account or an item on each line of the invoice. These could be stored in your database or be based on user input, but most likely it will be sensible to fetch it from the user's accounting platform by calling the GET [/accounts](/api-reference/accounting-endpoints/accounts/get-accounts) endpoint.
Call the GET [/items](/api-reference/accounting-endpoints/items/get-items) endpoint to fetch the items registered in the accounting platform.
Call the GET [/taxRates](/api-reference/accounting-endpoints/taxrates/get-tax-rates) endpoint to fetch the tax rates or tax codes available in in the accounting platform.
Decide when to transfer invoices to your user’s accounting platform. It could be a button within your application's frontend, listening for a specific event or according to a schedule (e.g. nightly).
Create the invoice in your user's accounting platform by calling POST [/invoices](/api-reference/accounting-endpoints/invoices/create-invoice).
Want to upload an invoice in PDF-form? You are likely looking for the [capture invoice](/use-cases/capture-invoices) use case
# DATEV use cases
Source: https://docs.maesn.com/use-cases/datev-overview
Documentation for implementing common DATEV integration use cases using Maesn Unified API.
Capture invoices and bills in DATEV Unternehmen Online
Post booking data into DATEV Rechnungswesen
Automate contact creation in DATEV Rechnungswesen
Retrieve data from DATEV Rechnungswesen
# Debt management
Source: https://docs.maesn.com/use-cases/debt-management
Technical walkthrough for implementing debt management workflows.
## Implement debt management in 5 easy steps
Your user must first authorize your application to access their accounting platform (e.g., Xero, Lexware Office, Sevdesk) via an authorization flow (e.g., OAuth, API key) through [maesn Connect](/guides/maesn-connect).
Start by retrieving a list of invoices by calling GET [/invoices](/api-reference/accounting-endpoints/invoices/get-invoices) and applying the appropriate filters, for example payment status or due date, to give your users an overview of their unpaid invoices.
When the end user has selected a specific invoice, present all the details including line items by calling GET [/invoices/\{id}](/api-reference/accounting-endpoints/invoices/get-invoice).
Present original PDF documents by calling GET [/invoices/\{id}/document](/api-reference/accounting-endpoints/invoices/get-invoice-document).
Periodically retrieve payments by calling GET [/payments](/api-reference/accounting-endpoints/payments/get-payments) to stop reminders as soon as the invoice has been paid.
# Fetch bills
Source: https://docs.maesn.com/use-cases/fetch-bills
Technical step-by-step documentation to fetch bills and supplier invoices via the Maesn Unified API.
## Fetch bills from other systems in 5 steps
Your user must first authorize your application to access their accounting platform (e.g., Xero, Lexware Office, Sevdesk) via an authorization flow (e.g., OAuth, API key) through [maesn Connect](/guides/maesn-connect).
Start by retrieving a list of bills by calling GET [/bills](/api-reference/accounting-endpoints/bills/get-bills) and applying the appropriate filters, for example bill date or bill status, to give your users an overview of their bills.
When the end user has selected a specific bill, present all the details including line items by calling GET [/bills/\{id}](/api-reference/accounting-endpoints/bills/get-bill).
Present original PDF documents by calling GET [/bills/\{id}/document](/api-reference/accounting-endpoints/bills/get-bill-document).
In addition, to bills created in the respective accounting platforms, bills created elsewhere and subsequently uploaded to the accounting platform can be retreived through
* GET [/bookingProposals](/api-reference/accounting-endpoints/bookingproposals/get-booking-proposals)
* GET [/bookingProposals/\{id}](/api-reference/accounting-endpoints/bookingproposals/get-booking-proposal)
* GET [/bookingProposals/\{id}/document](/api-reference/accounting-endpoints/bookingproposals/get-booking-proposal-document).
You can utilize Webhooks to make this process more efficient.
# Fetch invoices
Source: https://docs.maesn.com/use-cases/fetch-invoices
Step-by-step guide to fetch invoices from multiple accounting systems using a single Unified API.
## Fetch invoices from other systems in 5 steps
Your user must first authorize your application to access their accounting platform (e.g., Xero, Lexware Office, Sevdesk) via an authorization flow (e.g., OAuth, API key) through [maesn Connect](/guides/maesn-connect).
Start by retrieving a list of invoices by calling GET [/invoices](/api-reference/accounting-endpoints/invoices/get-invoices) and applying the appropriate filters, for example `lastModifiedAt` which is universally supported or `dueDate`, `status` or `paymentStatus` where available, to give your users an overview of their invoices.
When the end user has selected a specific invoice, present all the details including line items by calling GET [/invoices/\{id}](/api-reference/accounting-endpoints/invoices/get-invoice).
Present original PDF documents by calling GET [/invoices/\{id}/document](/api-reference/accounting-endpoints/invoices/get-invoice-document).
In addition, to invoices originally created in the respective accounting platforms, invoices created elsewhere and subsequently uploaded to the accounting platform can be retreived through
* GET [/bookingProposals](/api-reference/accounting-endpoints/bookingproposals/get-booking-proposals)
* GET [/bookingProposals/\{id}](/api-reference/accounting-endpoints/bookingproposals/get-booking-proposal)
* GET [/bookingProposals/\{id}/document](/api-reference/accounting-endpoints/bookingproposals/get-booking-proposal-document).
You can utilize Webhooks to make this process more efficient.
# Synchronize contacts
Source: https://docs.maesn.com/use-cases/sync-contacts
Step-by-step technical guide to synchronize contacts across accounting systems using Maesn Unified API.
## 5 steps to implement contact syncronization
Your user must first authorize your application to access their accounting platform (e.g., Xero, Lexware Office, Sevdesk) via an authorization flow (e.g., OAuth, API key) through [maesn Connect](/guides/maesn-connect).
Fetch the relevant contacts from your user's accounting platform using either the GET [/contacts](/api-reference/accounting-endpoints/contacts/get-contacts) or the GET [/customers](/api-reference/accounting-endpoints/customers/get-customers) and [/suppliers](/api-reference/accounting-endpoints/suppliers/get-suppliers) endpoint.
Match the contacts imported from your user's accounting platform with any existing contacts in your application, using relevant fields like `vatId`, `email` and `companyName`. Update contacts with newer information from the accounting platform if available and resolve conflicting information.
Use the POST [/customers](/api-reference/accounting-endpoints/customers/create-customer) or [/suppliers](/api-reference/accounting-endpoints/suppliers/create-supplier) endpoint to create contacts that exist in your application, but not in your user's accounting platform. Use PUT [/customers](/api-reference/accounting-endpoints/customers/update-customer), PATCH [/customers}](/api-reference/accounting-endpoints/customers/patch-customer), PUT [/suppliers](/api-reference/accounting-endpoints/suppliers/update-supplier) or PATCH [/suppliers](/api-reference/accounting-endpoints/suppliers/patch-supplier) to update contacts in your user's accounting platform if your application has more recent information on a contact.
After fetching contact data initially, you should make sure to keep your user's contact data up to date by regularly retrieving data through the GET endpoints. The `lastModifiedAt` query parameter can be utilized on all our GET endpoints to save you the hassle of creating deltas to detect change. See our [guide to keeping data fresh](/guides/keep-data-fresh) for more information!
You can utilize Webhooks to make this process more efficient.
# Synchronize expenses
Source: https://docs.maesn.com/use-cases/sync-expenses
Technical walkthrough for synchronizing expenses via the Maesn Unified Accounting API.
## 5 steps to implement expense syncronization
Your user must first authorize your application to access their accounting platform (e.g., Xero, Lexware Office, Sevdesk) via an authorization flow (e.g., OAuth, API key) through [maesn Connect](/guides/maesn-connect).
Implement the following logic in your application to retrieve customers' account data:
* Call the GET [/accounts](/api-reference/accounting-endpoints/accounts/get-accounts) endpoint to fetch the accounts from your user's accounting platform.
* Use the retrieved data to present your user's chart of accounts in your frontend. Use fields such as:
* `classification` (e.g., ASSET, EQUITY, EXPENSE, LIABILITY, REVENUE) to group accounts.
* `parentAccount` to visualize hierarchical relationships in the customer’s General Ledger (GL).
* **Note:** For DATEV integrations, the GET [/accounts](/api-reference/accounting-endpoints/accounts/get-accounts) endpoint only provides account ledger names.
* Do not forget to call GET [/accounts](/api-reference/accounting-endpoints/accounts/get-accounts) with regular intervals to keep track of any updates to your customer's chart of accounts.
Retrieve available tax rates from the accounting platform with GET [/taxRates](/api-reference/accounting-endpoints/taxrates/get-tax-rates).
Follow the steps outlined in the [synchronize contacts](/use-cases/sync-contacts) use case to synchronize suppliers in your application with your user's accounting platform.
If your users use classes, locations, departments or other dimensions configured, you can retrieve them from the accounting platform with GET [/dimensions](/api-reference/accounting-endpoints/dimensions/get-dimensions).
Presenting the data retrieved in the previous steps in your frontend, enable your user to configure rules for categorizing the expenses that will be synchronized to the accounting platform. The business logic will depend on your application, but bear in mind that:
* If your user only wants to synchronize their expenses against one single GL account, a simple dropdown menu to select the account may be sufficient.
* Users may want to categorize expenses based on conditional logic, such as "if Department = IT, use Account A". This will require more from your UI!
* You may want to give your users the possibility to categorize the transaction at the time when they synchronize it to their accounting service, which would imply that no categorization is required in the configuration or that it is possible to override the configuration.
* Depending on your use case, the accounting platform you are integrating to and the legislation of the country you operate in, you may want to automatically configure tax rates for expense categories or allow your users to manually select the tax rate for each individual expense.
* Likewise, dimensions may follow categories or be presented for selection for the respective expense.
Whenever your user incurs spend-related transactions in your application, e.g., credit card transactions or travel expenses, you can synchronize the transactions to your user’s Accounting platform with the correct classification via the POST [/expenses](/api-reference/accounting-endpoints/expenses/get-expenses) endpoint.
It is up to your application whether these transactions should be synchronized automatically or require an end user to manually export the expenses from within your application.
After fetching data initially, you should make sure to keep your user's data up to date by regularly retrieving data from the maesn API and looking for changes. The `lastModifiedAt` query parameter can be utilized on all our GET endpoints to save you the hassle of creating deltas to detect change. See our [guide to keeping data fresh](/guides/keep-data-fresh) for more information!
A simplified way to post expenses is to [create bookings](/use-cases/create-bookings) directly
# Synchronize items
Source: https://docs.maesn.com/use-cases/sync-items
Step-by-step guide to synchronize items and products across accounting systems.
## 5 steps to implement item/article/product syncronization
Your user must first authorize your application to access their accounting platform (e.g., Xero, Lexware Office, Sevdesk) via an authorization flow (e.g., OAuth, API key) through [maesn Connect](/guides/maesn-connect).
Fetch the relevant items from your user's ERP system using the GET [/items](/api-reference/accounting-endpoints/items/get-items) endpoint.
Match the items imported from your user's ERP platform with any existing items in your application, using relevant fields like `itemId`, `itemNumber` and `gtin`. Update items with newer information from the ERP system if available and resolve conflicting information.
Use the POST [/items](/api-reference/accounting-endpoints/items/create-item) endpoint to create items that exist in your application, but not in your customer's ERP platform. Use PUT /items or PATCH [/items](/api-reference/accounting-endpoints/items/patch-item) to update items in your customer's ERP system if your application has more recent information on an item.
After fetching item data initially, you should make sure to keep your customer's product data up to date by regularly retrieving data through the GET [/items](/api-reference/accounting-endpoints/items/get-items) endpoint. The `lastModifiedAt` query parameter can be utilized on all our GET endpoints to save you the hassle of creating deltas to detect change. See our [guide to keeping data fresh](/guides/keep-data-fresh) for more information!
You can utilize Webhooks to make this process more efficient.
# Get dimensions
Source: https://docs.maesn.com/v2/api-reference/accounting-endpoints/dimensions/get-dimensions
get /accounting/v2/dimensions
## Field support per integration
If you're not using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), make sure the query parameters `environmentName` and `companyId` are correctly populated.
You can obtain these values by using the `GET Environments` and `GET Companies` endpoints available under the Authentication section.
Supported filters: `none`
Support pagination: `false`
Support rawData: `true`
Supported Response Fields:
If you're not using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), make sure the query parameter `companyId` is correctly populated.
You can obtain this value by using the `GET Companies` endpoint available under the Authentication section.
Supported filters: `none`
Support pagination: `false`
Support rawData: `false`
Supported Response Fields:
If you're not using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), make sure the query parameter `companyId` is correctly populated.
You can obtain this value by using the `GET Companies` endpoint available under the Authentication section.
Supported filters: `none`
Support pagination: `false`
Support rawData: `false`
Supported Response Fields:
# Get dimensions by dimension
Source: https://docs.maesn.com/v2/api-reference/accounting-endpoints/dimensions/get-dimensions-by-dimension
get /accounting/v2/dimensions/{dimension}
## Field support per integration
If you're not using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), make sure the query parameters `environmentName` and `companyId` are correctly populated.
You can obtain these values by using the `GET Environments` and `GET Companies` endpoints available under the Authentication section.
Supported filters: `none`
Support pagination: `true`
Support rawData: `true`
Supported Response Fields:
If you're not using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), make sure the query parameter `companyId` is correctly populated.
You can obtain this value by using the `GET Companies` endpoint available under the Authentication section.
If you're retrieving projects from Exact Online, your account must have one of the following package subscriptions enabled:
* **Manufacturing** (any tier)
* **Professional Services** (Plus, Professional, or Premium)
* **Wholesale & Distribution** (any tier)
Supported filters: `none`
Support pagination: `true`
Support rawData: `true`
Supported Response Fields:
If you're not using the [Interactive Authentication Flow](/authentication#interactive-authentication-flow), make sure the query parameter `companyId` is correctly populated.
You can obtain this value by using the `GET Companies` endpoint available under the Authentication section.
Supported filters: `none`
Support pagination: `true`
Support rawData: `false`
Supported Response Fields:
# Webhooks
Source: https://docs.maesn.com/webhooks
Learn how to use webhooks to receive real-time updates from connected accounting systems.
Webhooks allow you to receive real-time notifications about events happening in your connected accounting systems. This enables you to automate workflows and keep your data in sync without the need for constant polling.
## Unified Webhooks
Maesn supports a single, unified webhook type for all systems.
Endpoint url : `POST /webhooks`
Subscriptions are created **per customer**, so each customer events is received through the related subscription.
Requires both the `X-API-KEY` and the `X-ACCOUNT-KEY` in the header.
Systems that support webhooks:
* `businesscentral`
* `exact-nl`
* `freshbooks`
* `lexware-office`
* `moneybird`
* `qonto`
* `quickbooks`
* `weclapp`
* `xero`
## Setting up a webhook
To set up a webhook, you need to create a subscription by sending a POST request to the `/webhooks` endpoint.
The request body support the following parameters:
* `callbackUrl`: The URL where you want to receive webhook events.
* `eventType`: The type of event you want to subscribe to (e.g., `CREATED`, `UPDATED`, `DELETED`).
* `resource`: The resource you want to monitor (e.g., `INVOICE`, `CUSTOMER`).
In each target system page, you can check the required input parameters for the request body.
## Getting events
Once a webhook is set up, you will start receiving events at the specified callback URL. Each event will contain information about the resource that triggered the event, including its event type and ID.
The received event body will look similar to this:
```json Example event body theme={null}
{
"eventType": "CREATED",
"filterDate": "2023-10-01T00:00:00Z",
"resource": "INVOICE",
"resourceId": "bca91f06-0414-4b24-81fa-8489105afceb"
}
```
`Note`: for Business Central, Quickbooks and Xero the notification will be an array of objects.
## Handling events
When your server receives a webhook event, it should process the event according to your application's logic. This may involve updating records in your database, triggering other workflows, or sending notifications.
## Deleting a webhook
If you no longer need a webhook, you can delete it by sending a `DELETE` request to the `/webhooks/{webhookId}`endpoint.
## Webhook Authentication
All received events to the callback URL include an X-MAESN-SIGNATURE header containing an HMAC-SHA256 signature for verification.
### How to Verify
1. Get the signature from the `X-MAESN-SIGNATURE` header
2. Compute HMAC-SHA256 of the raw request body using the webhook secret returned during webhook creation
3. Compare the computed signature with the header value
```javascript Node.js theme={null}
const crypto = require('crypto');
const expectedSig = crypto
.createHmac('sha256', Buffer.from(secret, 'hex'))
.update(body)
.digest('hex');
const isValid = expectedSig === headerSig;
```
Always use the raw request body before parsing JSON. Your webhook secret is provided when creating the webhook endpoint.
# Welcome to maesn!
Source: https://docs.maesn.com/what-is-maesn
Learn more about Maesn and the vision behind the Unified Accounting API.
We do the hard integration work of normalizing data across a multitude of ERP and Accounting systems into a unified schema.
If you have any questions, don’t hesitate to [reach out](https://www.maesn.com/contact/) to us. Access to the API can be requested via our website.
## What is maesn?
Maesn is the only Unified API that provides standard endpoints tailored for ERP use cases. We will continuously work on improving and extending our portfolio of use cases and ERP systems that we offer easy integration to.
Beside great use-cases, the most relevant ERP systems and the best possible support, we provide several technical key features that enable you to accelerate your integration game:
* Drop-in frontend authentication components that makes it easy to connect to your customers’ end systems.
* Authenticated pass through request for the occasional API endpoint not included in our common data models.
* Templates for you docs, so that you have all content for your end user-onboarding ready
* Soon: Observation dashboard to monitor all connections and integration activities, as well as an outstanding 1st level support with our wiki
Once you get started with maesn and integrate with our endpoints, you automatically have support for all existing and new integrations we add.
## Unified API
A Unified API provides a standardized set of endpoints for accessing data and functionality across multiple systems within the same software vertical (such as Accounting or Warehouse Management). By providing a single point of connection, Unified APIs act as an abstraction layer that simplifies authentication, data transformation, syntax, and data synchronization.
The point of Unified APIs is to make it easier for developers to build integrations with multiple similar software products, e.g., for a spend management system to provide integrations to a range of accounting systems with similar functionality but distinct APIs.
Since there is a multitude of authentication mechanisms in use and many APIs implement proprietary variants of standard protocols, providing a single authentication mechanism for multiple systems is a key feature of Unified APIs and probably one of the largest time-savers for integration developers.
However, features such as standardized pagination, filtering, and sorting are also essential to enable developers to retrieve data across different platforms efficiently.
## Common data model
The Unified API standardizes models of data for each category of software and normalize data from each system into these standardized data schemas.
It is the responsibility of the Unified API to decide what data is common across a given category, and how best to represent it in a normalized model.
Thus, developers only need to implement a single code base to access data across many systems.
As an example, the currency of an account may be represented with the field `currencyCode` in Xero and `currency` in sevdesk, while the account model in Lexware Office does not have any corresponding field since Lexware Office only supports euro as currency. The Unified API provider would make a decision on how to represent currency across integrations, for example with a `currency` field in the common data model and to always return `EUR` in this specific field for Lexware Office. Thus, the Unified API does the hard lifting and the integration developer can rely on always receiving normalized and consistent data!