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 four sub-tabs, each with its own address you can bookmark:

• Connect: the switch that lets AI assistants and API integrations reach your workspace, and the two addresses they connect to, each with Copy.
• 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. Both lists show who changed each row last, and when.

Destinations and keys are managed here only. Each entity's own Integrations tab shows where that entity sends and its own calls (see Entity Management).

Send To — where documents go

Click Add Destination. It opens on its own page with three cards:

• General: the Name (how it appears in lists, for example "Accounting system") and the Entities that may send through it, all of them or a chosen list.
• Connection: the Address of the receiving system and its Sign-in, how it recognises Finpilo: None, Bearer token, Basic (user:password) or Custom header (you also give the Header name), and the Secret the system expects.
• Default: Workspace default makes it the destination a newly created entity starts with. Changing it later does not move any existing entity.

Click Create to save it. Changes later are kept with Save in the bar that appears.

Some systems sign in another way: OAuth, a login that returns a token, signed requests, credentials in the body, or an SSH key for SFTP. Finpilo supports them, but they are not set up on this page. Ask an AI assistant to configure them (see AI Assistants), or write to help@finpilo.com. Such a destination shows its sign-in as text here, and its name and entities can still be changed.

The secret is stored encrypted. Once saved, Finpilo never shows it again: the field shows dots, with Change Secret under it. Leave it alone to keep the current one.

If you set a sign-in 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. It is chosen on the entity: Entity Management → the entity → Integrations → Sends to, then Save.

An entity with no destination cannot send. Its sends fail. There is no fallback.

Writing back onto a sent document

A sent document is usually locked, so nobody can change it by hand. Your own workflows can still write onto it: when the accounting system answers with its posting number, or later reports a payment, a workflow step saves that onto the document. The lock holds people, the AI assistant working for a person and outside systems using an API key. It does not hold the workflows your workspace set up.

Pausing a destination

Open it and choose Deactivate in its ⋮ menu. It keeps every setting, and sends through it fail until you choose Activate. This is the way to stop everything at once without deleting anything.

Delete Destination is the last entry of the same menu. A destination is not deleted while an entity sends through it, a workflow names it, or it is the workspace default: the answer names every one of them at once, for example "Not deleted. Alfa Būve and the workflow 'Invoice export' still send through it." A deleted destination or API key is kept aside. To find it, filter Status by Deleted on Send To or API Keys. It opens read-only. Restore Destination or Restore API Key at the top brings it back, and your AI assistant can do this too. An API key that is brought back needs a new key. The old one stays revoked.

API Keys — letting a system call Finpilo

Click Add API Key. Its page has three cards: General, Key and What it may do.

• Name and Entities, as above. The key reaches only those entities' data. Anything else answers as if it did not exist.
• What it 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.

Click Create, then Generate Key in the Key card. The full key is shown exactly once, under New key with Copy. Store it safely, because Finpilo keeps only a hash.

• Regenerate Key replaces it. You choose when the old key stops working: Keep the old key 24 hours (recommended, so the system can be switched over with no downtime) or Stop the old key now.
• 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 Connect sub-tab above and 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, whether it was sent or received, which connection and entity, the call (method and address), and the status it ended with (or No answer when the other side never replied). A send that was refused before it left (for example, with no destination) is there too, with the reason, and so is every call another system makes to a workflow's address.

• Filter by entity, direction or outcome, or search the address.
• Click a row to open the call in the panel on the right: its time, connection, entity and outcome, and the actual Request and Response. The arrows at the top step to the next call.
• Export in the ⋮ menu 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's Integrations tab lists its own calls the same way.

How sending works

When you send a validated document (see Document View), Finpilo runs your workspace's send 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. When a step does allow retries, a call that got no answer is retried after a short wait, as one the other system answered with "busy".

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 under Workspace Settings → Workflows. A new workspace has none: an admin builds it, and adds a Send step to the lifecycle that starts it. A send workflow usually has:

• 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. The document's data 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.