This doc explains how to link two ioi sites together so that customers, suppliers, invoices and credit notes from one site are transferred automatically (or on demand) to the other site, instead of being accounted for internally.
General principle: this is a cross configuration, and it must ALWAYS be done on both sides, even if documents only flow in one direction.
This is not just an organizational matter: it is a technical requirement. When site A sends a document to site B, it passes along its own connection identifier. Later, when B needs to call A back (to update the accounting status of the original document, cancel it, etc.), it does so by looking up, on B itself, an ioi Accounting API Connection record carrying that exact identifier. If that record does not exist on B, this callback fails, even though the initial A → B transfer worked perfectly.
Concrete example: I transfer an invoice from site A (ERP) to site B (LU accounting). Site A sends the invoice, then asks for its status to change once it has been accounted for. If the status change succeeds on site B, then site B contacts site A back to tell it to move the original ERP invoice’s status forward. Site B therefore needs to know site A and be able to connect to it, exactly as A needs to know B for the initial send. Hence the rule: always set up the cross configuration on both sides, making sure to specify the exact name under which each site is referenced by the other.
In practice, one of the two sites is the “master” (it emits its customers/suppliers/invoices) and the other is the “receiver” (it only receives them): the document flow is one-way. A genuinely bidirectional flow (each site also emitting toward the other) is theoretically possible with this mechanism but is not normally used in practice.
Concretely, for a link between a master site and a receiver site:
- Part 1 (API connection): to be created on both sites, without exception, including on the receiver site which will never emit anything itself (needed for the status callbacks, see the example above).
- Parts 2 and 3 (journals + “Transfer candidate”): only needed on the master site, the one that actually emits the documents.
Part 1 - Create the API connection (on both sides) #
1.1 On the site that will RECEIVE the documents: create a dedicated user #
This is the user the other site will use to authenticate its API calls.
- Create a new
Userdedicated to this purpose (e.g.api-link-lu@yourdomain.com). Do not reuse a personal account. - On this user’s record, API Access section, generate an API Key and an API Secret. Write down both values immediately (the secret will never be shown again in clear text afterwards).
- Make sure the user is active (not disabled).
1.2 On the site that will SEND the documents: create the connection record #
Go to ioi Accounting API Connection (new document) and fill in:
| Field | Content |
|---|---|
| Identification | A unique identifier chosen once and for all (cannot be changed after creation). Automatically becomes the record’s technical name (UPPERCASED). This is the value the other site must copy, as is, into its own “Accounting API Connection ID for this site” field (see below). |
| Site URL | The remote site’s base URL (e.g. https://oviservice.ioi.online). |
| API Key | The key generated in step 1.1 on the remote site. |
| API Secret | The secret generated in step 1.1 on the remote site. |
| Accounting API Connection ID for this site | The value of the “Identification” field as entered on the connection record created on the remote site (the one that remote site uses to call you back). Must match exactly (case does not matter, everything is automatically uppercased) the name of an ioi Accounting API Connection record that must actually exist on the remote site, otherwise callback calls (status update, cancellation) will fail. |
| Accounting Access | Only check this if you also want to be able to view the remote site’s balances/accounting situations from this site. Not needed for simple document transfer. |
Important, follow this order to avoid back-and-forth:
- On site A, create the connection record with a chosen “Identification” (e.g.
OVI-BE). Leave “Accounting API Connection ID for this site” aside for now if you don’t yet know site B’s identifier. - On site B, create the connection record with its own “Identification” (e.g.
OVI-LU), and fill in “Accounting API Connection ID for this site” =OVI-BE(the value chosen in step 1). - Go back to site A’s record and fill in “Accounting API Connection ID for this site” =
OVI-LU.
Each site therefore necessarily has its own ioi Accounting API Connection record (pointing to the other, with the credentials of a dedicated user that exists on that other site): this Part 1 must be repeated on both sides in all cases, even if only one of the two sites actually sends documents to the other (see the explanation at the top of this doc).
Part 2 - Configure the relevant journals #
This step is done on the sending site, on each sales journal (for customers/sales invoices) and/or purchases journal (for suppliers/purchase invoices) whose documents must go out to the remote site.
Open the relevant journal (ioi Sales Journal or ioi Purchases Journal).
2.1 “Sales Invoices” / “Purchases Invoices” tab (and “Sales Credit Notes” / “Purchases CN”) #
“Accounting Transfer” section: the Accounting Journal field (link to an internal accounting journal) must stay empty. This field determines the transfer mode:
- filled in → internal transfer (an accounting entry is created directly on this site, the mechanism described here is not used);
- empty → external transfer (provided the fields in part 2.2 are filled in).
2.2 “Files” tab #
| Field | Content |
|---|---|
| Accounting Journal (External) | Free-text identifier of the journal that must receive the document, as it should be understood on the remote site. To be agreed with whoever manages the other site. |
| Accounting API Connection (External) | Select the ioi Accounting API Connection record created in Part 1.2. |
These two fields exist separately for invoices and for credit notes: fill them in for each document type you want to transfer.
2.3 “Logs” tab #
| Field | Role |
|---|---|
| Automatic | Check this so THIS journal takes part in the automatic transfer (every 10 minutes, see Part 4). If unchecked, no document from this journal is ever sent automatically, even if the global setting is active. |
| Attempt Submit | If checked, the system also attempts to validate (“submit”) the entry on the remote site right after it is created. |
| Number of inactive days at the beginning of the month | The automatic transfer does not trigger until this day of the month has passed (e.g. 5 = nothing goes out before the 6th of the month). |
| Minimum document age in days | Grace period after the document date before automatic sending (e.g. 5 days = a document dated today will not go out before 5 days). |
These last two settings only apply to the automatic trigger: manual transfer via “Transfer Now” (Part 4) ignores them.
Part 3 - Mark customers/suppliers for transfer #
On each relevant ioi Customer / ioi Supplier record, “Transfer (External)” section:
- Transfer candidate: check this so this third party is synchronized to the remote site(s).
- Last transferred on: filled in automatically after the first successful transfer, read-only.
Checking this box alone is not enough. The transfer job looks, among all sales/purchases journals, for at least one journal correctly configured as in Part 2 (external Accounting Journal + Accounting API Connection filled in). If no journal is configured, the transfer fails with the error “No accounting API connection found” (see Part 6), regardless of the “Transfer candidate” checkbox state.
Option: transfer only on creation #
In ioi Accounting Settings (see Part 4), general parameters section:
- Do not update customers after creation on external site(s)
- Do not update suppliers after creation on external site(s)
By default (unchecked), every later change made to the third party is re-transferred automatically (as long as “Transfer candidate” stays checked). If checked, only the initial creation is transferred: subsequent changes made to the third party are no longer sent to the remote site.
Part 4 - Enable and test the global transfer #
Go to ioi Accounting Settings → “Transfer of Invoices & CNs” tab, “Execution” section:
| Field | Role |
|---|---|
| Automatic (Every 10 Minutes) | Main switch. Must be checked for the scheduled task (every 10 minutes) to run. This task handles both the third-party synchronization (Part 3) and the transfer of invoices/credit notes from journals marked “Automatic” (Part 2.3). |
| Inactive From / Inactive Until (Server Time) | Optional: time window (server time) during which the automatic transfer does not trigger. Leave both fields empty together if you don’t want an inactivity window; never fill in only one of the two. |
| Transfer Now | Forces an immediate run, manually, without waiting for the 10 minutes. Useful for testing the configuration once it’s in place. |
| Latest Transfer Beginning / Latest Transfer End | Timestamp of the job’s last run. Check these if in doubt: if “End” has not been updated for a long time while “Automatic” is checked, the job is likely stuck. |
| Latest Error Log (caped to 6500 characters) | Last error log, one message per third party/document that failed during the last run. First thing to check when troubleshooting. |
The VAT Code For Proposed Financial Discount (Sales/Purchases) fields on this same page only relate to the proposed financial discount mode (reduced VAT); they have no impact on how the link itself works.
Part 5 - What gets transferred, and how #
- Customers/Suppliers: identity, contact details, VAT, bank details, payment/delivery terms, default accounting accounts, etc. The full list of transferred fields is fixed (not configurable).
- Invoices and credit notes: only documents in “standby” status; for sales, the document must also be approved (or not require approval). The summary lines (general account, VAT code, amounts, analytics) are sent as they are, along with the document’s file attachments.
- Once successfully transferred, the source document moves to “Temporary” status on the sending site and keeps a reference to the entry created on the remote site (visible on the document).
- If “Attempt Submit” is checked on the journal, the system also tries to validate the entry on the remote site right afterwards; if this validation fails, the document stays in error even if the creation itself succeeded.
Part 6 - Troubleshooting: common errors #
| Message / symptom | Likely cause | Solution |
|---|---|---|
| “No accounting API connection found” | No sales journal (for a customer) or purchases journal (for a supplier) has both the “Accounting Journal (External)” and “Accounting API Connection (External)” fields filled in (Part 2.2). | Complete the configuration of at least one journal. |
| “Accounting API connection {id} not found” | A journal’s “Accounting API Connection (External)” field points to a deleted or non-existent record. | Check/recreate the ioi Accounting API Connection record. |
| Nothing happens despite “Transfer candidate” being checked and journals configured | The global “Automatic (Every 10 Minutes)” setting (Part 4) is not checked, or the current time falls within the “Inactive From/Until” window. | Check “Automatic”, check the time window, or use “Transfer Now” to test immediately. |
| Authentication error (401/403) on the call | Invalid or expired API key/secret, or the dedicated user disabled on the remote site. | Regenerate a key/secret on the remote site (Part 1.1) and update them in the connection. |
| Invoice/credit note never transferred automatically, but manual transfer works | “Number of inactive days at the beginning of the month” or “Minimum document age in days” (Part 2.3) not yet elapsed, or the journal’s “Automatic” checkbox unchecked. | Check these two settings and the relevant journal’s “Automatic” checkbox. |
| The number of customers/suppliers doesn’t match between the two sites after a while | Synchronization still incomplete (new third parties not yet checked “Transfer candidate”, or the job hasn’t run yet) or configuration only half done (only one direction configured). | Check “Latest Transfer End” and “Latest Error Log” (Part 4) to confirm the job is running, and that the configuration is done on both sides if needed. |
Summary of key points #
| Topic | To check |
|---|---|
| API connection | Created on both sites, always, each with the key/secret of an active dedicated user from the other site |
| Cross identifiers | “Accounting API Connection ID for this site” on A = “Identification” of the record on B, and vice versa (otherwise status callback calls fail) |
| Journals + “Transfer candidate” | Only needed on the master site (the one that emits); the receiver site only needs Part 1 |
| Journal (internal vs external) | “Accounting Journal” (internal) empty + “Accounting Journal (External)” and “Accounting API Connection (External)” filled in |
| Journal - activation | “Automatic” checkbox checked on the journal (Logs tab), in addition to the global setting |
| Third party | “Transfer candidate” checkbox checked on each relevant customer/supplier |
| Global setting | “Automatic (Every 10 Minutes)” checked in ioi Accounting Settings, “Inactive From/Until” fields empty together (never just one) |
| Test | “Transfer Now” button for an immediate run, then check “Latest Error Log” |
Aussi pour cet écran