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.

Sending a document means Finpilo hands it to your accounting system over the internet, as data rather than as a file to open. Your accounting system has to be able to receive it. Many can, through their own API or an add-on. Some need a small piece of code written once by whoever supports that system.

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 connections and workflows, shows you exactly what would change, and applies it only after you approve.

Do you need a developer?

What you can do yourself: choose which entities send where, decide which documents get sent, generate and revoke API keys, and watch what was sent and what failed.

What needs someone technical, once: the address Finpilo sends to and the credentials for it, and anything on the receiving side. That is usually your accounting system's supplier or your IT partner. Ask them for the base URL and the authentication details, or forward them External API, which is written for them.

If you only need your partner list or dimension values loaded, you may not need any of this. Both have an Import button that takes a spreadsheet — see Dimensions.

Not sure? Write to help@finpilo.com and we will tell you what your system needs.

The Integrations tab

Admin or Owner role required.

Go to Workspace Settings → Integrations. It has three sub-tabs:

• Send To — the external addresses Finpilo sends documents to.
• API Keys — the keys external systems use to call Finpilo.
• Logs — every call in and out, and how it ended.

The two lists are separate on purpose. One row is one direction: an address you send to is never also a key someone calls you with.

The same three sub-tabs appear on each entity, under Entity Management → the entity → Integrations, showing only what applies to that entity.

Send To — where documents go

Click New Destination and fill in:

• Name — how it appears in lists, for example "Accounting system".
• Entities — which entities may send through it: all of them, or a chosen list.
• Base URL — the address of the receiving system.
• Auth — how it recognises Finpilo: No Auth, Bearer Token, Basic (user:password), or Custom Header (you also give the Header name).

If your accounting system signs in with OAuth rather than a fixed key or token — many cloud systems do — Finpilo supports it, but it is not set up on this form. Ask an AI assistant to configure it (see AI Assistants), or write to help@finpilo.com.

• Secret — the token, key or password the system expects.

The secret is stored encrypted. Once saved, Finpilo never shows it again — the field displays dots with a Change button. Leave it alone to keep the current one.

If you set an auth type and the address starts with http:// rather than https://, Finpilo warns you: the credentials would travel unencrypted.

Which destination an entity uses

Each entity sends to one destination, and it is set on the destination itself: open it from the entity's Integrations tab and turn on Entity's Destination.

An entity with no destination cannot send. Its sends fail, and the entity's Integrations tab says so at the top. There is no fallback.

The Workspace Default switch, on a workspace-level destination, decides what a newly created entity starts with. Changing it later does not move any existing entity.

Pausing a destination

Open it and click Disable. It keeps every setting, and sends through it fail until you click Enable. This is the way to stop everything at once without deleting anything.

Deleting a destination is blocked while an entity or the workspace still points at it. The message names what to reassign first.

API Keys — letting a system call Finpilo

Click New API Key and fill in:

• Name and Entities, as above. The key reaches only those entities' data. Anything else answers as if it did not exist.
• What this key may do — tick each permission the key needs: read documents, create and edit documents, move documents through their statuses, read partners and dimensions, create/edit/delete partners and dimensions, read change history, read usage figures.

Nothing is ticked to begin with, and a key with nothing ticked can do nothing. It will authenticate and then be refused on every call. Tick what the system actually needs and no more.

Editing configuration and managing users are never available to a key, whatever it is for. Those need a person's login.

Save first, then click Generate API Key. The full key is shown exactly once, with a copy button — store it safely, because Finpilo keeps only a hash.

• Regenerate Key replaces it. You choose when the old key stops working: after 24 hours (recommended, so the system can be switched over with no downtime) or immediately.
• Revoke Key removes it. That system loses API access immediately. Sending is not affected.

API access also has to be switched on for the workspace as a whole — see the API & AI Access tab in Workspace Settings. While it is off, nothing outside Finpilo can reach your workspace, key or no key.

Logs — did it arrive?

The Logs sub-tab records every call, in both directions: when it happened, which connection and entity, the method and address, the status it ended with, and how many records were created, updated or failed.

• Filter by entity, direction or outcome, or search the address.
• Click a row for the call detail — the actual request and the actual reply.
• Export CSV takes the filtered list away with you.

The request and reply text is kept for 14 days, and the summary of each call for 90 days. So an older entry still shows what happened and how it ended, but not the exact text that was sent.

This is the place to answer "did yesterday's invoices arrive?" without opening forty documents. Each entity has the same tab for its own traffic.

How sending works

When you send a validated document (see Document View), Finpilo runs the Send to Accounting workflow. It posts the document's data to the entity's destination. If the entity has no destination, or the destination is disabled or does not cover that entity, the send fails and says which.

When the receiving system accepts the document, the workflow moves it on and, if the reply carries an accounting reference, stores it in the document's Accounting Reference field. If it returns no reference, nothing is stored — that is fine. The send and the reply are recorded on the document's Activity tab, and in full on the Logs tab.

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

About retries and duplicates

A failed send is not automatically retried by default, because a retry can post the same invoice twice — the receiving system may have processed the first attempt before the connection dropped. Whoever configures the send step decides whether it is safe to retry, and can have Finpilo attach a key that lets the receiving system recognise a retry.

Sending the same document again from Finpilo replaces the accounting reference rather than creating a second record.

Two more things worth knowing if a send fails for no obvious reason: Finpilo only calls addresses reachable on the public internet, so an address on a private or office network is refused. And redirects are not followed, so give the final address rather than one that forwards.

Changing what is sent

Admin or Owner role required.

The send is an ordinary workflow you can open and adjust, under Workspace Settings → Workflows → Send to Accounting:

• The Send HTTP Request step holds the data that gets sent — an editable JSON body. Type @ anywhere in it to insert a value from the document. What is sent by default is listed in External API.
• The Update Field step stores the accounting reference your system returns. It can write any document field, not just that one.
• To send the document's file too, use Document File on the Send HTTP Request step and pick As a File Attachment (multipart) or Embedded in the Body as Base64, whichever your system expects. Files up to 25 MB are sent.
• Test This Step runs it for real against a document you pick and shows the reply.

A step can also work out a value the document does not hold — a total for one cost centre, an amount in cents, your code translated to theirs. See Workspace Settings.

Changes are saved as a draft and take effect only when you publish them.

If you used webhooks before

Connections replaced the old webhook settings. Your existing configuration — workspace and entity — was moved across automatically, so sending kept working without any reconfiguration. Each webhook URL became a Send To destination, each API key an API Key, and an entity that had its own webhook now has that destination marked as its own.