A REST data feed is one secure address where your own system serves its books as pages of JSON, in the columns of Naarvin's import templates. It suits an in-house ERP, a middleware or an integration flow. Naarvin reads it over HTTPS on the schedule you set, with a token, an API-key header or a user name and password, and never writes to it.
What does the feed have to serve?
A set of paths under one base address. Two are required; the rest are read when they exist, and a path that answers 404 is simply treated as absent.
| Path | Needed | Rows |
|---|---|---|
| /accounts | Yes | The chart of accounts |
| /journal-entries | Yes | Posted journal lines |
| /customer-invoices, /vendor-bills | No | Open items, with credit notes |
| /customer-invoice-lines, /vendor-bill-lines | No | Lines with their VAT |
| /customer-payments, /vendor-payments | No | Payments, with what is still on account |
| /customers, /vendors | No | Master data with VAT numbers and terms |
| /exchange-rates | No | Dated rates |
| /companies | No | Code, name, currency and country of each company |
Each path answers with a JSON array of rows, or with an object holding the rows under data and the address of the next page under next. Next pages must stay under the feed's own address: a link elsewhere would receive the feed's credentials, so Naarvin refuses it. Rows use the template columns, by their keys such as account_code or their English or Arabic names.
How does Naarvin sign in to the feed?
With a bearer token, an API key in a header you name (X-API-Key unless you choose another), or a user name and password. Whatever you choose is encrypted when saved and never shown again. Only public HTTPS addresses are accepted.
How do incremental syncs work?
On a full sync Naarvin reads every path without filters and treats the answer as the whole picture: entries the feed no longer serves are marked deleted, unless that would remove more than half of what is loaded, in which case nothing is removed and the sync warns. On later syncs Naarvin adds ?since=YYYY-MM-DD to the dated paths, journals, invoices, payments and lines, so the feed can return only what changed. A feed that ignores since still works; it just sends more.
A path may return up to 500,000 rows over at most 2,000 pages in one sync. Rows that fail the import checks are left out and listed as warnings. Schedules run from every 15 minutes to weekly, in your time zone.
How are companies and currencies handled?
A feed for several companies serves /companies and puts the company code on each row; each company links to its own company in Naarvin with the same currency. A feed for one company can leave both out and name the company code, currency and country on the connection.
How do you connect a feed?
- Publish the two required pathsServe /accounts and /journal-entries in the template columns over HTTPS, behind a token or key.
- Add the connectionEnter the base address, the sign-in type and secret, and the company details if there is no /companies.
- Run a full sync and compareCheck the trial balance against your system's own, and read the warnings.
- Add the optional paths and sinceAdd invoices, payments and master data, and honour ?since on dated paths to keep syncs light.
Questions people ask
Is the feed something Naarvin hosts?
No. Your system or middleware serves it, and Naarvin reads it. Nothing is pushed into Naarvin.
Can the feed live on our internal network?
It needs a public HTTPS address that Naarvin can reach. Private and plain-HTTP addresses are refused.
Do we have to support ?since?
No. Without it every sync reads everything, which is simpler but heavier.