Falco

Falco

This connector uses the Falco API (docs.falco-app.be) of Falco, the Belgian accounting and e-invoicing application: purchase and sale documents, documents received over Peppol, Peppol participant lookups, and the customers, articles and invoices of the Falco invoicing module. It reads; setting a purchase payment status is a write, and sending a Peppol invoice response is installed switched off.

Setup (two keys, both required)

1. The integrator creates an application on the Falco developer portal (dev.falco-app.be), requests the scopes it needs (e.g. documents:purchases:read, documents:sales:read, peppol:inbound:read, peppol:participants:read, customers:read, articles:read, invoices:read) and makes it Public. Its production Application Secret (as_live_...) goes into FALCO_APP_SECRET.
2. The Falco customer (an administrator of the organisation, plan Expert Essential or Expert Premium) opens API access under their initials in the Falco desktop application, picks that application by its id (app_...) and generates an API key (sk_live_...) for their organisation. It goes into FALCO_API_KEY.
3. Install and run falco_get_organization to check both keys. The connector calls the production API, https://api.falco-app.be/v1; sandbox keys (as_test_, sk_test_) only work on the sandbox host and are refused here.

Workflow

• Supplier invoices: falco_list_peppol_inbound for what arrived over Peppol (sender, amount, due date, payment reference, bank account), falco_get_peppol_inbound_document, falco_download_peppol_inbound_document for the UBL. falco_list_purchase_documents and falco_get_purchase_document cover all purchase documents with their files; falco_download_purchase_document_file with main, ubl or a file id fetches one.
• Sales: falco_list_sale_documents, falco_get_sale_document; documents made in the invoicing module: falco_list_invoices, falco_get_invoice, falco_download_invoice_pdf; master data: falco_list_customers, falco_get_customer, falco_list_articles.
• Peppol reachability of a company: falco_find_peppol_participant with its VAT number, or falco_check_peppol_participant with a participant id such as 0208:0123456789.
• After paying a supplier: falco_set_purchase_payment_status (switched off at install; replaces the status, so show the user the document and the new status and wait for a yes).
• falco_send_invoice_response (switched off) sends an accept, reject, query or paid message to the supplier over Peppol at once; before calling it show the user the document and the response and wait for a yes.

Dates and amounts: filters take YYYY-MM-DD. Amounts are strings in the document currency (usually EUR). Lists are paged with page (from 0) and page_size (20 to 200, invoices up to 100); ask for the next page while a page comes back full.

Limits and errors: 60 requests per minute per application secret (429 above that; wait and retry). Errors follow RFC 9457 with title, detail and code. 401 means a wrong application secret or API key, or a sandbox key on production; 403 means the key lacks the scope for that area (the customer grants scopes when creating the key); 404 on a participant lookup means the company is not reachable on Peppol.