Ekwo OS — open source accounting: ledger, invoices and VAT on your own…

A balance sheet or an income statement for a period, on the scheme the country pack declares — the Belgian abbreviated model, the French liasse — or on the generic framework by account type. Each line is summed from the accounts its rules catch and the totals are derived from the lines; no country rule lives in this tool. It also returns the accounts no line catches: if that list is not empty, say so instead of presenting a statement that does not tie out. It prepares figures; it files nothing.

Every posted line of an account over a period, with the balance carried forward from before it and a running balance. Give account_code for one account; leave it out for all of them, which on a real company is a lot of lines.

The Fichier des Écritures Comptables for a period: the eighteen columns of the arrêté du 29 juillet 2013, as text, with the checks a tax inspector applies first (mandatory fields, one side per line, entries balancing) and the filename the format wants. The file comes back in the answer; writing it to disk is the caller's business.

Everything needed before booking in a company: its financial years and whether they are closed, its lock dates, its journals, and the accounts that play the receivable, payable, suspense and retained-earnings roles. Read this before creating a document if you do not already know the journals and the lock dates. Next: list_accounts and the ekwo://companies/{companyId}/taxes resource give the codes a document line names.

One document with its lines, the account and tax of each line, the legal mentions its country requires on it, that country's payment and e-invoicing rules, and — when it has been posted — the ledger entry it produced with every ledger line. Use it to check what a document will book, what it did book, and what has to be printed on it.

The signed-in user’s own preferences — which company an interface opens on, the language they read labels in, their timezone and how they like a date and a number written — and the language chain to read labels with: theirs, then the company’s, then the country pack’s. Every one of them may be null, and null means "take the next answer in the chain" rather than a default this installation picked.

Reads a bank statement file and writes its statements and lines. `format` says what the file is — `camt.053` (the ISO 20022 XML statement), `coda` or `cfonb120`, which are the ones this server reads today — and `content` is the file as text. It is never guessed from the content. It books nothing: every line waits as pending, to be settled afterwards. Safe to repeat: the same file imported twice creates nothing the second time, and a statement overlapping an earlier one imports only the new lines. Refused by name, with nothing written: an account the company does not have (create it first with …

Description is built at runtime.

The payments on account of a declaration that the VAT scheme a company recorded asks for during its period — a simplified scheme pays part of the year's tax before filing the annual return — with what was due, what was paid and what is outstanding. The schedule, the percentages and the box of the previous year they are read on are country pack data; no country rule lives in this tool. It reads; it pays nothing.

Invites an address into a company with a preset — viewer reads, client reads and hands pieces over, accountant keeps the books, owner also administers — and any capability granted on top of it. It returns a token once and stores only its hash, so hand the token to the person you invited: they accept it themselves, signed in with that address. It does not send an e-mail, and it does not create an account. Inviting the same address again withdraws the invitation that was pending.

The book of a journal: every line of every posted entry over a period, in the order a book is read — day, journal, entry number, line — each with its entry, the document behind it, its account and its contact, and the totals of each journal at the head. Give journal_code for one journal (the sales journal, the bank); leave it out for the book of every journal, which on a real company is a lot of lines. For one account with its running balance, use general_ledger.

Records that an open line on a receivable or payable account names nobody on purpose — a cash difference, a one-off refund — with the user's reason: suggest_line_contacts no longer proposes it. The line does not move and stays an open item. Refused by name: unknown_line, not_allowed, reason_required, reason_too_long, line_not_posted, line_has_contact, line_not_third_party, line_left_unnamed. Ask the user before calling it.

The accounts a company actually works with, filtered by code prefix, by account type, or by a search on the name. Use it to find the income or expense account a document line should carry. By default it returns the working chart — the accounts that carry entries, that the company's settings or an enabled module point at, or that somebody pinned — because a country pack transcribes the whole regulation and a company uses a few dozen of its several hundred accounts; `in_use_from` and `in_use_to` narrow the movements to a period, `include_all` returns the whole chart, and `include_deprecated` ret…

The analytic axes of a company — a cost centre, a project, a site, a business unit — each with its values, which may nest under a parent_id, and required_on: none, or expense, income or result — the lines that must carry the axis whole, or posting refuses them (analytic_axis_required). A value says what a cost, a revenue or a fixed asset is for; a product says what was sold or bought. A retired value takes no new share. Read it before analytic_report, which takes an axis by its code.

The keys a company has issued to machines, what each one may do, how it posts a document (posting_mode, review or autopilot, fixed when it was issued), when it was last used and whether it is still live. Only somebody who manages members sees them, and no secret is in here: a key is shown once, when it is issued.

The bank accounts of a company, with their identifier and the scheme it is written in, the journal they book through and the ledger account behind each. Read it before recording a payment on a particular account, and to find out whether the company has one at all.

Statement lines of a company, pending by default — the ones still waiting to be dealt with. `amount` is signed: positive is money in. A statement line is not a ledger entry; recording a payment is what books it.

The companies of this installation that you are a member of, with your role on each. Start here: every other tool needs a company_id. Returns id, name, country, currency and your role. It does not list companies you were never invited to — those are invisible, not hidden. Next: get_company on the one the user means.

Invoices, credit notes and quotes of a company, filtered by type, state, settlement state, contact or date range. `state` is the document (draft, posted, cancelled) and `payment_state` is the settlement (not_paid, partially_paid, paid) — two different questions. Returns headers and totals, not lines; use get_document for those.

The people invited into a company and not yet on its books, with the preset and the capabilities each was invited with, and whether the invitation is still pending, expired, accepted or withdrawn. Only somebody who manages members sees them. The token is never in here: it is shown once, when the invitation is issued.

The links a company has published onto its own sales documents, with how many times each was opened and when it was last opened. No token is in here: a link is shown once, when it is made. Use it to answer "did the customer open the invoice?" and to find the link to withdraw.

The schemes this company can be presented on: those of its country and of its chart of accounts, plus the generic framework by account type that fits any chart. Ask this before financial_statement rather than guessing a code.

Moves the accounting lock date, the VAT lock date, or both. After this, nothing can be booked, changed or deleted on or before that date — including corrections you may want later. Only an owner of the company may do it. Always ask the user first, and never lock a period you have just posted into without being told to.

What reconcile_with_difference accepts for this company: the largest difference it books (in units of the currency and as an amount) and the reasons — rounding, exchange_difference — each with the account the pack gives, the side it answers (charge, income, either) and whether it is available. No pack carries a role for bank charges or payment discounts, so they are not reasons.

One party created twice — two spellings of one customer, two imports of one supplier: everything that names the absorbed contact names the kept one afterwards, in one transaction — posted ledger lines and issued documents included, statement lines, payments, branches, files and learned motifs — and the kept contact's empty fields (VAT number, IBAN, address, email…) are filled from the absorbed one without overwriting any. The absorbed contact is retired, never deleted, and no row may name it again. No amount, account, date or tax box moves, and there is no unmerge. Refused by name: unknown_con…

Turns the trial balance of whatever kept the books before into the opening entry of a fiscal year, on the opening journal, dated on its first day — or on opening_date, the day inside the year the books were taken over. Lines are {account_code, debit, credit}; total debit must equal total credit. Balance-sheet accounts only, unless allow_result_accounts is set, which is for taking books over in the middle of a year. items are the invoices and credit notes still open that day, each posted as a document with its number, payment reference and due date, so a bank statement finds it; the items of an…

Adds accounts to the working chart of a company, so list_accounts offers them whether or not anything has been booked on them. Pass pinned: false to take one back out. Pinning is display and nothing else: an unpinned account may still be booked on, and a pinned one is still hidden once it is deprecated.

Which declarations, across your portfolio — every company you may read the declarations of, which for an accounting firm is its clients — had entries posted into their period after they were filed — with the company named, how many entries, and how many of the filed figures now disagree. A period stays open after its return has gone, on purpose; this is what keeps a late entry from going unnoticed. Companies with nothing to report are named too, with how many filed declarations were examined. It reads; whether a corrective is owed is for whoever keeps the books.

What falls due between two dates in every company you may read the declarations of — the question a firm asks of all the books it keeps, and the one a person asks of the single company they run. "Portfolio" is meant as an accounting firm means it — its client portfolio — and is nothing but that: the companies you hold filings.read on, worked out at each call, never a list anybody maintains. Every one of them is in the answer, including a company whose country pack names no deadline, which is listed without a date and says so; a company left out would be indistinguishable from one that was neve…

Description is built at runtime.

Who changed what, and when. Every change to the configuration and reference data of a company — the chart of accounts, the journals, the taxes and the accounts they post to, the bank accounts, the contacts, the products, the financial years, the members and their roles, the country pack version — and every act that changes a state: a document posted or cancelled, an entry posted or reversed, a payment booked, matched or unmatched, a financial year closed or reopened. Filter by table, by natural key, by user, by act, or by date range. The ledger itself is not in here: a posted entry is immutabl…

Matches a debit line against a credit line on the same reconcilable account, for an amount, defaulting to the smaller of the two open amounts. Use it to settle an invoice against a payment by hand. Matching changes no account and stays possible after a period is locked.

Matches several lines together in one call — one payment against several invoices, one invoice against several instalments — when their open debits and credits are equal to the cent: posted lines of one company, one reconcilable account, one counterparty (a line naming nobody is attributed by the matching), in the company's currency. Paired oldest first through reconcile, under one letter. Refused by name, and never settled in part: reconcile_unbalanced gives the difference. Show the user the lines and ask before calling it.

Matches the same set of lines as reconcile_many when their totals differ by no more than the company's tolerance: posts an entry that books the difference on the same account and counterparty against the account the pack gives for the reason (matching_difference_options: rounding, exchange_difference), then matches everything under one letter. Refused by name: difference_above_tolerance, no_difference, unknown_difference_reason, no_account_for_reason, and every refusal of reconcile_many. The entry is posted; unreconcile of the matching of the difference line takes it back. Show the user the di…

Records money in or out, books it (bank against the customer or supplier account) and, unless you say otherwise, matches it against that contact's oldest open invoices up to the amount paid. Matching is what makes an invoice count as paid. The entry it produces cannot be unposted, though the matching can be undone with unreconcile.

Removes a member from a company, now: they stop reading and writing its books. Needs members.manage, except to leave a company yourself. The last owner of a company is refused, themself included; make somebody else owner with set_member_role first. Their pending invitations are not touched. Say who is being removed before calling it.

The PDF of a sale invoice or a sale credit note, rendered from the books: the seller with its logo, the buyer, the lines, the tax summary, the totals and what is still due, how to pay, and the legal mentions the country requires — as the views publish them, in the accent colour and on the logo side the company set with update_company_profile. Comes back as a PDF resource (base64) beside a JSON summary: filename, pages, whether the logo was used. factur_x: true embeds the CII XML of a posted document and returns the rules of EN 16931 it breaks. Words of the layout are English unless labels give…

Undoes an ordinary close, to correct the year: the entries it wrote are reversed, never deleted, and the year accepts entries again. Entries already posted in later years do not prevent it and are not touched — they read this year from the ledger, so closing it again carries the corrected result to them. Refused for a year under a final close (fiscal_year_finally_closed), for everybody, and while a later year is closed (later_fiscal_year_closed): reopen that one first. Always ask the user before calling it.

Undoes a posted entry in one call: writes its mirror in the same journal — every line on the other side — naming it, posts it under the next number, and matches the two. The original keeps its number and its lines. Dated on the original's day unless you give a date; refused by name when that period is locked or closed (reversal_date_needed), and then you ask the user for a date rather than choosing one. Refused for an entry a document wrote (use cancel_document), the entries of a close (reopen_fiscal_year), an opening, the entry of a payment, a bank transaction, a module or a matching, an entr…

Stops a key working, now and for good. There is no un-withdraw: a secret that has been out of the building is issued again rather than brought back. Whatever the machine was doing with it stops, so say so before calling it.

Withdraws an invitation that has not been accepted, so its token stops working. An invitation that has already become a membership is refused: a member is taken out with remove_member.

Stops a link working, now and for good. Whoever holds it sees exactly what they would see for a link that never existed. There is no un-withdraw: a secret that has been out of the building is issued again rather than brought back, so say so before calling it.

Customers, suppliers and other third parties of a company, by name, by type or by VAT number. Use it before creating a document: a document is booked against a contact, and creating a second contact for a customer who already exists splits their account. Nobody matches: create_contact. Found: create_document with its id.

The catalogue of a company: what it sells and buys, with the code, the unit, the price, the account each books to and the tax each carries. Search it before writing a line by hand — a product fills in the text, the price, the account and the tax, and keeps two invoices for the same thing consistent. Retired products are left out unless you ask for them.

Names the contact of an open line on a receivable or payable account that names nobody — the open items of books imported line by line — once, from nothing to a contact of the same company, and learns the label as a motif of that contact for the next suggestion. Refused by name: unknown_line, line_not_posted, line_has_contact (a posted counterparty is corrected by reversing the entry), line_matched (unmatch it first, and only when the user says so), line_not_third_party, unknown_contact. Changes no amount, account or tax box. Show the user the candidates of suggest_line_contacts and ask which …

Changes the preset of a member of a company — viewer reads, client reads and hands pieces over, accountant keeps the books, owner also administers. Needs members.manage. The capabilities granted or revoked on that member so far are cleared, and the ones you pass are granted on top of the new preset, the way an invitation writes a new member. The last owner of a company cannot be demoted: promote the successor first.

Sets the prefix one journal prints in place of {CODE} in the numbers it draws — FAC instead of SAL, for instance — or puts its code back with null. The journal keeps its code and its counter: the series goes on at the next number. A prefix another journal of the company already prints is refused. The pattern around it (year, width) is the company's number_format in update_company_profile. Needs settings.write.

Writes the signed-in user’s own preferences and nobody else’s. Only the fields you name change: leave one out and it is untouched, pass null and it is cleared, which puts that question back to the company and then to the country pack. It changes nothing in the books.

Books a pending statement line as the payment it is and matches it against the documents or open items named, in one entry: the bank, the customer or supplier account, and the extra lines the money is net of — the fee a payment provider kept from a payout, the charges of a bank, each on the account and with the tax the user names. A payout of 97.00 for an invoice of 100.00 settles the invoice in full with an extra line of 3.00 on a fee account. amounts says how much settles each item; left out, oldest first. The line has to balance to the cent (settlement_unbalanced otherwise, with the differe…

Publishes a posted sales invoice, credit note or quote behind a link the customer opens without an account and without a password: the token in the url is the whole secret. It returns that token once and stores only its hash, so give the url to the customer and say it cannot be read back. The page shows the document as it was sent and what is still owed on it today, so the link stays worth opening after a payment. A purchase document is refused — it is a third party’s own document — and so is a draft. A link is never edited: to change when it expires, withdraw it and make another.

The schema version, the instance this is, how this server is connected and as whom, whether this session posts in review or in autopilot, and the companies you can see with the mode a posting meets in each. Use it first when something does not add up — an empty company list usually means the user was never invited rather than that the books are empty.

The pairs of active contacts of a company that are probably one party — two spellings of one customer, two imports of one supplier — strongest first. Each pair names the contact to keep (the one more ledger lines and documents name, then the older) and the one to absorb, a score from 0 to 1, the kinds of evidence (vat_number, registration_number, account: the same number or bank account, score 1; name: the words of the shorter name in the longer, each weighed by how few contacts carry it, so that a shared trade, place or legal form alone is never a pair; 0.950 for the same name, 0.900 otherwis…

For each open line on a receivable or payable account of one counterparty (a branch and its parent are one party), the lines of the other side on the same account that could settle it, up to three proposals a line: an exact pair, several lines that add up to it to the cent ("this payment settles these three invoices", or one invoice paid in instalments), and — only when nothing is exact — a pair or several lines within the company's difference tolerance, with the difference (the line less the total). Each proposal has a stable proposal_id, a kind (pair, combination), the lines and a sentence. …

For each open line on a receivable or payable account that names no contact — typically the open items of books imported line by line — the contacts it could be, best first, each with a score, the method (a learned motif, the number of a document of the company quoted in the label, the description or the reference of the entry, the words of a contact's name), the evidence in a sentence, and alternatives: how many contacts the same evidence reached. More than 1 is a question for the user, not an answer. It writes nothing; set_line_contact names a line once the user has chosen.

Opening balance, movements of the period and closing balance for every account, from posted entries only. The debit and credit totals are equal on a healthy ledger; if they are not, say so rather than explaining it away.

Takes back leave_line_unnamed: the line is proposed a contact again. Refused by name: unknown_line, not_allowed, line_not_left_unnamed.

Removes one matching, putting the residual back on both lines. The entries themselves are untouched. It is what cancel_document and reverse_entry ask for first when what they would undo is matched.

Changes what a company says about itself on its documents: the names it goes by, its address and identifiers, its logo and the colour, logo side and typeface of its invoice PDF, the pattern of its document numbers, its stated capital, its activity code and the bank account customers are asked to pay into — and agent_posting, how agents post its documents, which you only ever make stricter. Only the fields you name change. It touches nothing in the ledger, and it needs company.write — the owner preset, not the accountant one.

Replaces every line of a draft document with the set you give, and returns the document with its recomputed totals. Lines take product_code the same way create_document does. Drafts only: a posted document is never edited; cancel_document undoes it with a credit note.

Changes a catalogue row — its name, price, unit, account, tax — or retires it with active: false. Documents already written keep the text, the price and the account they were invoiced with; an invoice is a statement about the day it was raised, and this tool cannot rewrite one. Retiring is the way to withdraw something: deleting is refused while any line still points at it.

The boxes of the VAT return for a period, with their names: the base and tax boxes are summed from what the postings wrote on the ledger lines, the totals are derived from them by the declaration form of the country pack. No country rule lives in this tool, nor in the function behind it. Name a report_code only where a country files several declarations. It prepares figures; it files nothing.