well_get_vat_summary

io.github.WellApp-ai/well-mcp · Verify this server

Read the VAT position of a workspace over a window of whole months, grouped by the date of its entries and invoices, straight from its book (VAT on posted invoices, which is the debit basis): per month, for the whole window as a CA3 by rate, and as totals with the net VAT payable. A French workspace gets that CA3; any other workspace, or a window with nothing posted, is answered from its draft entries and invoices (see below). It also lists the invoices whose lines or supplier leave the figure unreliable. It reads the book and computes nothing a reader has to trust blind: every amount is a decimal string in major units of `currency`, such as `"5000.00"` for five thousand euros, ready to state as returned. State each amount with its `currency` exactly as given. Never convert, scale or recompute one. Use it for "what is my VAT this quarter", "how much VAT can I deduct", "is my VAT return ready" and "which invoices are hurting my VAT". Do not use it to sum invoices (`well_sum_invoices`) or to browse journal entries (`well_query_records`). **The window is whole months.** `from` is the first day of the first month and `to` is the first day of the month AFTER the last one, both as YYYY-MM-01, so the second quarter of 2026 is `2026-04-01` to `2026-07-01`. On `basis: "posted"`, name both or neither: with neither, the call reads the current calendar quarter only: the quarter in progress, not the last four quarters and not the last complete one. On `basis: "possibilities"`, name both always: a call with neither is refused `invalid_period` with the current quarter's bounds in `error`, so the caller can ask again for them. To read any other period, work out `from` and `to` from today's date and pass both. A window shorter than one month, longer than 12 months, or with a bound inside a month returns `status: "invalid_period"` with the reason in `error`. It is refused, never widened. **`months`** holds one row per calendar month, oldest first: `collected` (output VAT), `deductible` (input VAT, a positive magnitude), `net` (collected minus deductible, positive is payable), and `reverse_charge` (the self-assessed VAT on reverse-charge purchases, kept out of `collected` and `deductible`). `month_ended: false` marks a month still running, whose figures can still move. `unattributed_collected` and `unattributed_deductible` are VAT on lines that name no tax rate. `unmapped_rate_tax` is the signed net VAT (collected positive) on a rate the return has no slot for, such as 8.50 or 13.00. These three are in none of `collected`, `deductible` and `net`, so state them beside any total that is not zero. The monthly `collected`, `deductible` and `net` add up to the window totals. **`ca3`** is the return by rate over the WHOLE window, built once from every entry in it, not summed from the monthly rows. `complete: false` means the ledger holds a figure the return cannot place: read `blocking_reasons` (`unattributed_collected_vat`, `unattributed_deductible_vat`, `unmapped_rate_percent`, `directionless_taxable_base`) and say so before quoting any total as final. Box numbers are deliberately absent: Well does not guess a printed CA3 box. **`totals.net_due`** is the net VAT payable: collected minus deductible over the window, on the rates the return has a slot for (it leaves out `unattributed_*` and `unmapped_rate_tax`), with `position` as `payable`, `credit` or `nil`. A credit means the state owes the workspace, so never present it as a payment. **The figure is on the debit basis.** It counts VAT when the invoice is posted. Entries are placed by their entry date, in the month of the date, never by their fiscal period, so an entry posted into a later return still shows in its own month and a filed return can differ from this figure; `basis_note` says so. On the receipts basis (TVA sur les encaissements), the default for services, VAT follows payments, so the amount payable can differ from this figure. The read models no VAT regime. State the basis beside the net figure, and say "the posted ledger shows X net VAT payable", never "you owe X". **A window with nothing posted** is not refused. When the window holds no posted ledger entry that carries VAT, the call answers from the possibilities read of the same window instead: `status: "ok"`, `basis: "possibilities"`, with a `basis_note` saying that nothing is posted in the window yet, that the figures come from draft entries and invoices, and that the filed figure comes from closing the books. State that note beside the figures. It is NOT a nil return: never say no VAT is due. When that read finds nothing either, the answer is `no_vat_found`. Pass **`basis: "possibilities"`** when the question is what VAT the current documents and in-progress book could become. The read includes the VAT-role entries in every state, plus invoice-header tax only when no live VAT-role entry exists for that invoice. The entries' state is a bookkeeping detail: `entries.validated_count` and `entries.draft_count` split `entry_count` by the books' state: read them, never state them, and never word an entry or an amount as validated, draft, « validé » or « brouillon » (a money answer has no validation step); state the number of entries from `entry_count`. It groups the evidence by calendar quarter (quarters follow the entry date of each entry and the issue date of each document, never the fiscal period, and a filed return can differ), keeps domestic purchases, purchases to check, sales and unsided documents separate, counts the documents between two other companies apart (`not_ours`), and reads a document in another currency in the read currency only when its stored accounting tax is in that currency; an unconverted other-currency document, or any document with no currency, is excluded and counted in `excluded`. A purchase is domestic when its registry country is France, or, only for a French workspace with no registry country, its stored SIREN, SIRET or French VAT number passes full validation; otherwise it stays to check. When `excluded.identity_grouping_truncated` is true, the identifier check read only part of the suppliers, so some French purchases may still sit in purchases to check: every amount stays whole, only that split is less precise, so say purchases to check may hold French suppliers. Utility bills (document type 901) count as purchase documents; expense receipts (902) and pro formas (325) remain out. Documents with no issue date are counted in `excluded.undated_count` but never placed in a quarter or amount; that count covers the whole workspace, not the window, so it is the same on every window. Replacement documents are counted but excluded from the money lines, and make the quarter `incomplete`. A quarter's `presentation` is `computed` (both sides evidenced, each by an entry or a document, with at least one ledger entry in the quarter and nothing unread: `net` and `position` are set), `evidence_only` (one side only, or documents alone), `incomplete` (unsided, other-currency, null-currency or replacement evidence, or entry VAT with no attributed or mapped rate, sits beside the figures) or `no_evidence` (the quarter is in the window but holds no VAT-role entry and no invoice VAT: it is returned with every amount, `net` and `position` null and a `note`; state it as no evidence found for that quarter, never as zero VAT and never as a nil position); `net` and `position` are null unless `computed`; `entries.unplaced` is the entry VAT that neither side carries: reverse charge is only reported, while unattributed and unmapped-rate VAT make the quarter `incomplete`; purchases to check are reported beside a computed position and never added to it, and a side without evidence (`purchase_evidence` or `sales_evidence` false) is absent, never zero. Ledger entries booked in another or an unstated accounting currency are counted in `excluded` and not summed. A window over twelve months answers `range_too_large` with the window you asked for; nothing is narrowed. Documents between two other companies (both parties known, neither one a company of this workspace) are counted in `counts.not_ours`, ordinary and replacing ones alike, and the VAT of those whose tax is stated in `currency` is in `documents.not_ours` of the quarter, which sums only the documents with a readable VAT, so a quarter's count can be larger than the documents behind its amount. `possibilities.not_ours_note` is the ready sentence for them: their count, quarter by quarter, how many of each have a readable VAT, and that VAT. Relay it as its own sentence beside the figures, in the language of the answer and with its numbers unchanged; compose none of your own, never add that VAT to a figure or put it inside the deductible sentence, and never call a quarter `incomplete` for them. A null `documents.not_ours` means none of the quarter's such documents has a VAT stated in `currency` (an unconverted other-currency document, a document with no currency, a replacement): the note then says none is readable, and no amount is ever 0.00. A document with no party at all is not one of them: it stays unsided. Documents whose side rests on an inference, not on proof (a company of this workspace on one leg, or a provider claim with no holder), are counted in `counts.estimated_side`, replacing ones included, and their VAT is in `documents.estimated` of the quarter, by kind (`purchase_domestic`, `purchase_to_check`, `sales`); it is never in `deductible`, `collected`, `net` or `position`. `possibilities.estimated_side_note` is the ready sentence for them: relay it once, as its own sentence beside the figures, in the language of the answer and with its numbers unchanged, never as proven, and compose none of your own. An inferred side alone never makes a quarter `incomplete`: a quarter that holds only such documents is `evidence_only`, while a replacement, unsided, other-currency or no-currency document still makes it `incomplete`; state the returned `presentation` unchanged. A null amount in `documents.estimated` means none is stated, never 0.00. Possibilities carry no `months`, `ca3` or `totals`. With no accounting country, purchases remain `to check` and no jurisdiction is inferred, unless `estimated_country_code` is set (see below). With no configured or country currency, the mode of eligible non-null document currencies is used, ties break alphabetically, and no eligible currency returns `no_vat_found`; existing ledger amounts are never relabelled. `currency_basis` says what `currency` rests on: `settings` (the workspace's books currency), `country` (the default currency of its accounting country) or `documents_mode` (the most common currency of its invoices, because neither is set); it is null, beside no `currency`, when no denomination exists. Name it only when it is not `settings`. `status: "no_vat_found"` means neither VAT-role entries nor document evidence were found in any quarter of the window (the quarters it looked at come back as `no_evidence` rows), or no denomination can be selected; it is not a nil return. **`anomalies`** lists invoices in the window, purchases and sales, that carry a billed line with no VAT rate (`line_without_vat_rate`). A purchase that names no supplier company also lists as `supplier_unattributed`; a sale never does. `direction` says which side an invoice is on, from the workspace's own company: a `purchase` names a `supplier`, `sales` names a `customer`, and `label` uses that party. `unanchored` means the invoice does not name the own company on exactly one side, so it has no direction and no party. `total` counts every such invoice, `items` holds the first `anomaly_limit` (default 20, at most 50), and `truncated: true` means more exist than `items` shows. Name an invoice by its `label`, never by `invoice_id`. An invoice with no rate is not necessarily missing VAT: the fix is to set the rate or supplier on the invoice, not to adjust the return. **A workspace outside France, or with no accounting country,** is not refused either. It is answered from the possibilities read, with `filing: null` (no CA3, no CA3 slots) and a `basis_note` that names the gap: VAT filing for its country is not mapped in Well, or the workspace has no accounting country, and the figures are the VAT the books and invoices carry. State that note beside the figures. With no configured country, `estimated_country_code` is the majority registry country of the workspace's own documents, an estimate stated as one: the domestic split and the French-identifier check run on it, and `basis_note` / `estimated_country` says so. `country_code` stays null: nothing configured is asserted. `estimated_country_truncated` is true when more of its documents would vote than the estimate reads, so only the newest voted, and `basis_note` then says the country leads among the newest documents read, never a majority of all of them. The estimate reads the twelve months up to today, whatever window the call names. When no country emerges, the read infers no jurisdiction and places purchases in `to check`. **`filing`** is the VAT return Well's obligation table assigns to the workspace's own company, from its accounting country and legal form, or null when the table assigns none (the legal form is not set, or the country is not covered). `cadence` is the table's cadence for that form, which assumes the normal real regime (régime réel normal). Well stores no VAT regime and no deadline: `due_rule` is the published rule, with the `source` to name beside any date, and `due_window` is the window that rule gives for THIS read's period, the days of the month after it. It is null unless the read covers exactly one calendar month or one calendar quarter. State a date only after the person has confirmed they file on that cadence, and name the source with it. **`scope`.** Omit it, or pass `"this_workspace"`, to read the workspace the call runs in. Pass `"my_companies"` on WhatsApp to read every company workspace of the person's company family in one call, without moving the chat: the family is the membership the chat runs in, or the company's parent membership, and its company workspaces. A workspace counts only when the signed-in person holds a live membership in it, checked again before each read, and Well finds them from the signed-in person: a workspace is never named in the call. The result then carries `workspaces`, one block per company workspace (at most 10, `workspaces_truncated: true` when more exist), each with its `workspace_name`, `company_name` and the same fields as a single read, its own `status` first. Answer each block on its own: never add, net or compare two blocks into one figure. A block for a workspace outside France or without a country answers like any other and carries its own `basis_note`; state it with that block. `workspaces_unreadable` counts the company workspaces a failed lookup left out unnamed: their position is unknown, not nil. An empty `workspaces` with `workspaces_unreadable` at 0 means the person has no company workspace they can read; with it above 0 it means the read failed. On any other host the read refuses the scope with `status: "failed"`: read one company per call there. `status: "range_too_large"` means the window holds more posted entries than one call reads (5000). Ask again with a shorter window. It is never answered with a partial sum. `status: "failed"` means the read failed and the position is UNKNOWN, not nil. **Unread invoice-header VAT.** On the possibilities basis, `excluded.header_tax_unread_count` counts live eligible invoices with no header tax where both item and grand totals are present and differ. It is a count of VAT the header cannot read, not an amount. `excluded.tax_unknown_count` (present when above 0) counts every live eligible invoice in the window with no header tax, whatever its totals say (`tax_unknown_split` gives the equal, missing and differing totals; the differing ones are `header_tax_unread_count`). When it is present, the answer says once how many invoices in the window have VAT that could not be read, as a count for the window as a whole: never inside a quarter, never as nil, zero or no VAT, never as an amount, and never added to another count. When the token authorizes one workspace, call this directly — no workspace call is needed first. When it authorizes several, this read will not guess which one you mean: pass `workspace_id` on the call.