Finpilo
EN|LV
LoginGet started

Integrations

Finpilo exchanges data with your accounting system or ERP in both directions. Master data such as partners and dimension values flows in, and validated documents are sent out. A connection describes one external product you work with: where Finpilo sends documents, and the API key that product uses to call Finpilo.

Connections are managed in one place, the Integrations tab in Workspace Settings, and then picked wherever they are needed. Each entity can pick its own sending connection, and one connection can be marked as the default for the whole workspace.

An AI assistant can also build an integration for you — see AI Assistants. Describe the system and what should flow, and the assistant drafts the connection and workflows, shows you exactly what would change, and applies it only after you approve.

What a connection is

A connection describes one external product:

  • Name — how the connection appears in lists (for example "Accounting system").
  • Entities — which entities this product works with: All entities, or a selected list. This applies in both directions: only these entities can send through the connection, and the connection's API key can only reach these entities' data.
  • Sending — the Base URL of the external system, the Auth type (No auth, Bearer token, Basic (user:password), or Custom header), and the Secret the system expects.
  • API Key — the key this product uses to call the Finpilo External API (to sync partners and dimension values in, or read documents). See below.

The sending secret is stored encrypted. After you save it, Finpilo never shows it again — the connection just shows a Secret Set badge. To replace it, enter a new value. When editing, leave the field blank to keep the current secret.

Creating a connection

Admin or Owner role required.

  1. Navigate to Workspace Settings → Integrations tab.
  2. Click New Connection.
  3. Enter a Name and choose which Entities the product works with. All entities is right when the whole workspace uses one system; pick Selected entities when only some do.
  4. Fill the Sending section if documents are sent to this product: the Base URL, the Auth type (for Custom header, also the Header name), and the Secret.
  5. Click Create.
  6. If the product also calls Finpilo (to sync partners or dimension values, or read documents), generate its API Key — see below.

You can also create a connection directly from an entity's Sending tab. It is created covering just that entity and becomes the entity's sending connection right away.

Deleting a connection is blocked while it is still in use — as the workspace default, or picked by an entity. The message tells you what to reassign first.

The API key

Each connection has its own key for the External API. The key reaches only the entities the connection covers, so different products never share credentials and each can be cut off on its own.

  • Generate the key in the connection's API Key section. The full key is shown exactly once, with a copy button — store it safely, Finpilo keeps only a hash.
  • Regenerate replaces the key. You choose when the old key stops working: after 24 hours (recommended — time to switch the product to the new key with no downtime) or immediately.
  • Revoke removes the key entirely. The product loses API access immediately; sending is not affected.

The workspace default

In the connection editor, the Use as the Workspace Default switch marks the connection documents are sent to when an entity has no pick of its own. New entities use the default automatically. The default connection must cover all entities.

Picking a connection for an entity

Admin or Owner role required.

Use an entity-level pick when a specific entity sends to a different system than the rest of the workspace:

  1. Navigate to Entity Management and open the entity.
  2. Select the Sending tab.
  3. Choose a connection from the dropdown. Only connections covering this entity are listed. The empty choice, Workspace default, means the entity follows the workspace default connection.
  4. Click Save.

The tab always shows where the entity's documents effectively go, including when that comes from the workspace default.

How sending uses connections

When you send a validated document (see Document View), Finpilo runs the Send to Accounting workflow. It posts the document data to:

  1. The entity's connection, if the entity has picked one.
  2. The workspace default connection otherwise.

If neither exists, the document cannot be sent — create a connection first. A document is never sent through a connection that does not cover its entity.

When the external system accepts the document, the status changes to Sent. If the system's reply contains an accounting reference, Finpilo stores it in the document's Accounting Reference field. If it returns no reference, nothing is stored — that is fine. The send time and the system's reply are recorded on the document's History tab.

If the send fails, the document moves to Send Failed and the error is recorded in the history. Fix the connection or the document and send again.

Changing what is sent

Admin or Owner role required.

The send itself is an ordinary workflow you can open and adjust:

  1. Navigate to Workspace Settings → Workflows tab and open Send to Accounting.
  2. The Send HTTP Request step holds the payload — an editable JSON body where {{field}} references insert values from the document at send time. Type @ in the editor to pick a field. The default payload is described in External API.
  3. The Update Field step stores the accounting reference returned by your system in the document's Accounting Reference field. It can write any document field, not just the reference — pick the field from the dropdown.
  4. To send the document's file along with the data, use Attach the Document File on the Send HTTP Request step — as a file attachment (multipart), or embedded in the JSON body as Base64 text, whichever your system expects. Files up to 25 MB are sent.

If you used webhooks before

Connections replace the old webhook settings. Your existing webhook configuration — workspace and entity — was moved into Connections automatically, so sending kept working without any reconfiguration. Each webhook URL and API key became a connection, and an entity that had its own webhook now has that connection picked on its Sending tab.