First steps with Rest-API

Content

• What is a REST API?
• Where can I find the Finmatics API documentation?
  • If you don't have Finmatics access credentials yet
  • If you already have Finmatics access credentials
  • Postman
  • Limitations
• Overview of Endpoints
• Integration
  • Structure
  • Objects and UUIDs
• Authentication
• Master Data

  • Company

  • Clients

  • Processes

  • Businesspartner

  • Businesspartner - Bank Data 

  • GL Accounts

  • Cost Center 

• Invoices
  • Retrieving invoice data
  • Retrieving processed invoices
  • Retrieving invoices in an "Emergency"
  • Marking retrieved invoices as exported
  • Retrieving invoice images
• Training Data
• Returning booked invoices as Training Data
• Tips and Tricks

What is a REST API?

APIs, or application program interfaces, allow the functions of one computer program to be used by another. They are a way by which two different programs can communicate. REST APIs can be used by IT for software integration and automation purposes.

Where can I find the Finmatics API documentation?

If you don't have Finmatics access credentials yet

By logging in with the following credentials at this link:

https://app.finmatics.com/

• Username: demo
• Password: demodemo

afterwards, you can access the desired documentation URL:

• app.finmatics.com/api/v1/redoc/
• app.finmatics.com/api/v1/swagger/

If you already have Finmatics access credentials

By appending /api/v1/redoc/ or /api/v1/swagger/ to your customized Finmatics web interface URL, for example:

• your-companyname.finmatics.com/api/v1/redoc/
• your-companyname.finmatics.com/api/v1/swagger/

Postman

For the Postman program, we also provide a small collection with the essential API calls to help you get started quickly.

• Finmatics Postman library

To request an API user, please reach out to you customers@finmatics.com.

Limitations

• The API has a rate limit of 1000 requests per minute for generall and 100 for authentication (token_auth) requests.
  This limit is regularly monitored and will potentially be decreased further.

Overview of Endpoints

The following endpoints use the base_url of the production system. For the sandbox, the base_url should be set to test.finmatics.com.

• Token: https://api.finmatics.com/api/v1/token_auth/
  Needed for authentication
• Companies: https://api.finmatics.com/api/v1/companies/
  Allows retrieving and editing company data
• Clients: https://api.finmatics.com/api/v1/clients/
  Allows retrieving and editing client data
• Booking Types: https://api.finmatics.com/api/v1/booking_types/
  Allows retrieving, creating, and editing processes
• Partners: https://api.finmatics.com/api/v1/partners/
  Allows retrieving, creating, and editing partner data
• Partner Bank Data: https://api.finmatics.com/api/v1/partners/{id}/banks
  Allows retrieving, creating, and editing bank data for a specific partner
• All Partner Banks: https://api.finmatics.com/api/v1/partner_banks/
  Allows retrieving, creating, and editing bank data for all partners (bulk changes)
• GL Accounts: https://api.finmatics.com/api/v1/gl_accounts/
  Allows retrieving, creating, and editing general ledger accounts
• Cost Centers/Objects: https://api.finmatics.com/api/v1/cost_centers/
  Allows retrieving, creating, and editing cost centers/objects
• Invoice data: https://api.finmatics.com/api/v1/documents/
  Allows retrieving, creating, and editing invoice data
• E-Invoices: https://api.finmatics.com/api/v1/e-invoices/
  Allows retrieving, creating, and editing invoice data in various e-invoice formats. Offers a slightly different data structure
• Invoice Images: https://api.finmatics.com/api/v1/documents/{uuid}/pdf/
  Allows retrieving invoice images for individual invoices (UUID = invoice ID)
• Training Data: https://api.finmatics.com/api/v1/training_data/
  Allows retrieving, creating, and editing training data. These data support the system in automation as learning data

Integration

Structure

Finmatics offers a flexible structure for setting up the system and master data.

1. The customer's company is at the top level.
2. Below that are the individual clients (subcompanies, locations, etc.) of a company.
3. These clients are assigned master data such as partners, general ledger accounts, cost centers/objects.
4. Finally, each client is also assigned processes such as incoming invoices, outgoing invoices, cash receipts, etc., through which invoices can be assigned to the respective processes.
5. These processes contain the corresponding invoices of the client.

In the API, data can be retrieved for an entire company or per client. Filtering at the client level is recommended in most cases, such as when maintaining master data or retrieving invoices.

Objects and UUIDs

Each of the above-mentioned objects has its own UUID, which is used as an identifier and for assignment within the system. A UUID is unique within the object type.

• An invoice is assigned to a process and a client.
• A process is assigned to a client.
• A client is assigned to a company.
• Master data is assigned to a client.

This means that in each object, the assigned object is provided via the API in the form of a UUID.

Example of a client:

1 {
2 "id": "11111111-2222-3333-4444-555555555555",
3 "idExternal": "string",
4 "clientName": "Test",
5 "clientNo": "1234",
6 "company": "11111111-2222-3333-4444-555555555555",
7 }

• The id is the object's own UUID.
• company contains the company's UUID.
• idExternal can be filled with your own system ID to create an easy match with the partner system.

Authentication

The API uses JWTs (JSON Web Tokens) for authentication, which are valid for one week. To create a token, a POST request must be sent to https://api.finmatics.com/api/v1/token_auth/.

To refresh a token, use the https://api.finmatics.com/api/v1/token_refresh/ endpoint. The original token must be provided as the payload "token". The response is the same as when creating a token.

Payload

Payload for Refresh

Response

The Token from the response has to be used as an authorization header with the value "jwt=TOKEN" for all further calls.

We recommend using token refreshes sparingly and if possible. For example, if partners and then general ledger accounts need to be synchronized, only one token should be created for both synchronizations.

Master Data

Master data are the basic data of a company required for invoice processing.

Company

The company is usually prepared in the system by Finmatics, but data such as address or UID can be updated at any time.

Clients

• Endpoint: https://api.finmatics.com/api/v1/clients/
• Options: POST, GET (list/read), PATCH, PUT, DELETE

Clients can be created, adjusted, and deleted at any time via the API. When creating, name, number, and assignment to the company must be specified.

Tip: If the field noDefaultBookingTypes is set to false, a process ER for incoming invoices, AR for outgoing invoices, and KA for cash invoices is automatically created when creating a client.

Processes

• Endpoint: https://api.finmatics.com/api/v1/booking_types/
• Options: POST, GET (list/read), PATCH, PUT, DELETE

Processes can also be manually created or adjusted for a client at any time. When creating, the booking symbol (ER, AR, KA, etc.) and the assignment to the client must be specified.

Businesspartner

• Endpoint: https://api.finmatics.com/api/v1/partners/
• Options: POST, GET (list/read), PATCH, PUT, DELETE

Businesspartners can be created individually or in bulk (as a list). When creating, the booking symbol (ER, AR, KA), the name, the number, and the assignment to the client must be specified.

To ensure the best possible automatic assignment of the partner to the invoice in Finmatics, it is recommended to provide as much data as possible (address, UID/VAT, phone number, etc.) when creating.

Businesspartner - Bank Data

• Bank data of a businesspartner: https://api.finmatics.com/api/v1/partners/{id}/banks
• Bank data of all businesspartners: https://api.finmatics.com/api/v1/partner_banks/

Options: POST, GET (list/read), PATCH, PUT, DELETE

Bank data can be created individually for the respective businesspartner or in bulk (as a list) for several businesspartners.

When creating bank data for a single businesspartner, these are directly assigned to the businesspartner via the ID in the URL.The country must be specified.

When creating bank data in bulk, the businesspartner is not assigned in the URL but in the payload via the ID. The country must also be specified here.

GL Accounts

• Endpoint: https://api.finmatics.com/api/v1/gl_accounts/
• Options: POST, GET (list/read), PATCH, PUT, DELETE

General ledger accounts can be created individually or in bulk (as a list). When creating, the number, the designation, and the assignment to the client must be specified.

Cost Centers

• Endpoint: https://api.finmatics.com/api/v1/cost_centers/
• Options: POST, GET (list/read), PATCH, PUT, DELETE

Cost centers can be created individually or in bulk (as a list). When creating, the number and the assignment to the client must be specified. Both the name and the number are string fields and are therefore not limited to numbers. It is important, however, that the number is provided when retrieving invoices as it is relevant for the assignment.

Invoices

• Endpoint: https://api.finmatics.com/api/v1/documents/
• Options: POST, GET (list/read), PATCH, PUT, DELETE

Invoices can be transferred individually or in bulk (as a list) with or without additional data and can be retrieved at any time after processing. When creating a new invoice, the assignment to the process or the booking symbol and the assignment to the client must be specified.

Invoice processing is done asynchronously in the system. For this reason, after creating a new invoice it should be regularly checked whether the processing has already been completed.

The invoice fields are only shown if configured in the invoice detail screen. Read the following article for instructions: 

Exceptions are customFields, which are also displayed without configuration.