Essentio

View saved version →

---
name: close-vat-month
description: Close a month's VAT with Essentio — read the month's Reported VAT and Income from Essentio's own reports, find the Drafts left and the documents still awaiting payment, and say plainly what is and is not done. Use this whenever the person asks what VAT they owe for a month or quarter, wants to prepare or check a VAT return, asks how much they earned in a month, or says they are closing or wrapping up a month's books — even when they do not name Essentio.
---

# Close a month's VAT

The Essentio connector (`essentio_*` tools) reads one Business's reports as Essentio's dashboard
computes them. The figures that matter here are Essentio's, not yours: a VAT figure you add up yourself
from documents can differ by rounding, by currency or by which documents count, and the person may file
it. So every figure you state comes from a tool's answer, quoted as it is, with its currency.

Nothing in Essentio "closes" a month: no tool locks it, files a VAT return or sends anything to a tax
authority. What this workflow does is gather what Essentio knows about the month and tell the person
what is finished and what is still open.

## 1. Settle the period

Take the month the person means as its first and last day, `YYYY-MM-DD` (for a quarter, its first and
last day). Essentio dates documents by the day in UTC. If the person did not say which month, ask.

## 2. Read the month's figures

Call `essentio_get_report` twice, with the same `from` and `to`:

- `report: "vat"` — the Reported VAT: the VAT of the Invoices and Credit Notes issued in the period,
  in full, paid or not, a Credit Note subtracting. It answers `net`, `vat` and `bands` (the same split
  by VAT category and rate).
- `report: "income"` — Income: the net amounts of the documents issued in the period, paid or not, a
  Credit Note subtracting and a Proforma Invoice never converted adding only what was paid on it;
  its `vat` beside it.

Both are in the Business's reporting currency (`currency`). Each answers
`other_currency_documents`: how many documents issued in the period are in another currency and are
left out of every figure. Essentio never converts them. When that count is above zero, say so, and list
them (step 3) so the person can account for them.

A Proforma Invoice carries no VAT, so it is in no VAT figure, paid or not.

## 3. Find what is still open

Use `essentio_search_documents`. Each answer is one page: when it carries a `next_cursor`, call again
with it until there is none, or your list is incomplete.

- **Drafts left**: `status: "draft"`. A Draft has no issue date, so a period cannot narrow it; list
  them all, with their Client, Total, `due_date` and `created_at`, so the person can see which belong
  to the month. A Draft counts in no report. Issuing one now gives it today's issue date, so it counts
  in the month it is issued, not in the month being closed — say so before the person decides to
  issue it.
- **Awaiting payment**: `status: "awaiting_payment"` — every issued Invoice and Proforma Invoice that
  still takes a Payment, Overdue ones included. This does not change the Reported VAT, which counts
  documents on issue, paid or not; it tells the person what is still owed to them. For what is
  Overdue today, by Client, `essentio_get_report` with `report: "overdue"` gives Essentio's own totals.
- **Documents in another currency** (when `other_currency_documents` is above zero): list the ones
  the count counts. The VAT report counts the Invoices and Credit Notes issued in the period, not
  cancelled: search the period (`issued_from`, `issued_to`) with `document_type: "invoice"` and again
  with `document_type: "credit_note"`, leave out any whose `status` is `cancelled`, and keep those whose
  `currency` differs from the report's. The Income report's count also takes the Proforma Invoices
  issued in the period and never converted into an Invoice: search the period again with
  `document_type: "proforma"` and keep the ones not cancelled in another currency. A document's answer
  does not say whether a Proforma Invoice was converted, so this list may include converted ones and
  be longer than the count. Say so; do not present it as the count's documents exactly.

## 4. Say what is and is not done

Answer in three short parts:

1. **The month's figures** — Reported VAT (`net`, `vat`, and each band's category, rate, net and VAT)
   and Income, as the reports answered them, with their currency and period.
2. **Still open** — the Drafts left, the documents awaiting payment, and any documents in another
   currency left out of the figures, each with its number (or "Draft"), Client and amount as the tool
   answered it.
3. **Not done by Essentio** — the VAT return itself: Essentio reports the figure; filing and paying it
   are the person's (or their accountant's).

Some rules keep this honest:

- Quote each amount as the tool answered it. If you add anything up yourself, say that it is your sum,
  and never add amounts in different currencies.
- If a report is refused (a tool error whose text is JSON with `error.message`), quote the message and
  stop: do not estimate the missing figure from documents.
- This workflow only reads. If the person then asks to issue a Draft or record a Payment, that is a
  change to the Business: confirm it with them first, and use the tools for it one document at a time.

View saved version →

---
name: draft-and-send-invoice
description: Draft, check, issue and send an Invoice in Essentio through the Essentio connector's tools, in that order, stopping at a refusal. Use this whenever the person asks to invoice or bill a Client, charge someone for work or products, prepare or send an Invoice, Proforma Invoice, Quote or Credit Note, or says things like "invoice ACME 500 euros and send it" — even when they do not name Essentio or say "draft".
---

# Draft, check, issue and send an Invoice

The Essentio connector (`essentio_*` tools) acts for one Business, the one the person chose when they
connected it, with the Role they gave it there. Every figure on a document is computed by Essentio when
the Draft is saved: your job is to put the right Client and Lines into a Draft, let the person see
what Essentio computed, and then issue and send only what they approved.

Work in this order. Each step says why, so you can adapt when the person asks for less (only a Draft,
or issue without sending).

## 1. Find the Client

Call `essentio_search_clients` with `search` set to the name, email, VAT number or account code the
person gave. Use the `id` of the Client that matches.

- Several match: show their names and emails and ask which one. Guessing would bill the wrong Client.
- None matches: ask whether to create one. `essentio_create_client` needs an `email`, a `country` and a
  `name` or `legal_name`; a VAT number is optional and is checked with the EU's VIES service. Create it
  only after the person confirms the details.

If you need the Client's currency or payment terms, `essentio_get_client` reads them.

## 2. Read the Business's setup

Call `essentio_get_business_setup` once. It gives the reporting currency, the active VAT rates (each
with the VAT category a Line takes at it) and the bank accounts. Take each Line's `vat_rate` and
`vat_category` from those rates rather than from memory: a rate the Business does not use is a
different document. A 0 rate in a category other than `S` and `Z` needs a `vat_exemption_code`
(a VATEX code) — ask the person for it rather than choosing one.

When the person names a Product or service they sell, `essentio_search_products` gives its name, unit,
price and VAT rate.

## 3. Create the Draft

Call `essentio_create_draft` with:

- `document_type`: `invoice` unless the person asked for a `proforma`, `quote` or `credit_note`;
- `client_id` from step 1;
- `currency`: the Client's currency if it has one, otherwise the Business's; ask if the person said
  another;
- `due_date` (YYYY-MM-DD): today plus the Client's payment terms, unless the person gave a date;
- `lines`: each with `description`, `quantity`, `unit_price` (VAT excluded) and `vat_rate`, all as
  decimal strings such as `"500.00"` and `"19"` — never as numbers.

A Draft has no number and no issue date, is not sent and counts in no report, so creating it commits
the person to nothing. A second identical `essentio_create_draft` within about ten minutes is answered
with the first Draft, marked as a replay, and creates nothing new; if the person really wants two
identical Drafts, send a fresh `idempotency_key` with the second.

## 4. Check the figures with the person

The person is shown the Draft as a card with its Client, Lines, VAT and Total. Read the same answer
yourself and compare it with what they asked for: the Client's name, each Line, `vat_groups`,
`subtotal`, `total_vat`, `total` and `currency`.

- Quote Essentio's figures as they are in the answer. Do not recompute VAT or totals and present your
  own numbers: Essentio's rounding is the one the document will carry.
- If something is not what the person meant (a price, a quantity, a rate, the wrong Client), change the
  Draft with `essentio_update_draft`. Only the fields you send change, and `lines`, when sent, replace
  every Line — so send them all.

Then read the answer's `actions`. Each Action is `{open, code, remedy}`:

- `actions.issue.open` false: the Draft cannot be issued as it stands. Say so, with its `code`, before
  asking to issue.
- `actions.send.open` false with `remedy` `connect_mail_provider`: Essentio cannot email the
  document for the Business right now — it has no email address of its own, its recipients through
  Essentio for today are all emailed (`sending_limit_reached`), or its connected mailbox was lost. Tell
  the person now, in the refusal's words, and give them the `remedy_url`, Essentio's email settings.
  Issuing still works.

## 5. Issue, once the person says so

Ask before issuing, and say what it means: the Draft takes its document number for good and today's
issue date, a due date already passed becomes today plus the payment terms, and an issued document can
no longer be deleted — only cancelled, or corrected with a Credit Note.

Then call `essentio_issue_document` with the `document_id`. It does not email anything.

The card has its own Issue and Send buttons. If the person pressed one, the card already shows what
happened: call `essentio_get_document` to read the document as it is now instead of issuing again.

## 6. Send, once the person says so

Ask before sending: `essentio_send_document` emails the document, attached, to the Client's address on
record, through the Business's connected mail account. It cannot send to any other address. `subject`
and `message` are optional; left out, the Business's own template is used. If the document is still a
Draft, sending issues it first.

An identical `essentio_send_document` call within about ten minutes emails nothing: it is answered with
the first call's answer, and a second text says "Nothing was written again: an identical
essentio_send_document call was made less than 10 minutes ago…". When you see that, tell the person the
document was not emailed again. If they do want it sent a second time, call it again with a fresh
`idempotency_key` of your choosing (a UUID). The same holds for `essentio_create_draft` and
`essentio_create_client`: an answer that says "Nothing was written again" is the first call's record,
not a new one.

Finish by telling the person the document number, its status and Total, and its `public_url`.

## When a tool fails

A failed call answers a tool error whose text is JSON: `{"error": {"type", "message", ...}}`. Tell the
person what happened in `message`'s words, and act on `type`:

- `refusal`: the Action is not open for the document as it stands. Quote `message`, which is written
  for the person, and name the `code`. Stop there — do not retry with other values on your own.
  Nothing was written, with one exception: a Send refused `mail_account_lost` (the connected mail
  account refused to renew its access) may have issued its Draft on the way — when the error carries
  a `document_number`, the Draft is now issued under that number and stays issued, unsent. With the
  `remedy` `connect_mail_provider`, Essentio cannot email for the Business right now, as the refusal's
  words say: the person puts it right in Essentio's settings (the document's `actions.send.remedy_url`
  leads there) — or, past the day's limit, waits for tomorrow — then asks to send again.
- `not_delivered`: the mail provider did not take the email. This is not "nothing written": a Send of a
  Draft issued it on the way. When the error carries a `document_number`, the Draft is now issued under
  that number and stays issued, unsent. Say so plainly, so the person does not think it is still a
  Draft, and do not issue it again.
- `permission`: the connection's Role may not do this (a Viewer's connection writes nothing). Someone
  with a higher Role in the Business has to do it, or the person reconnects with that Role.
- `invalid_request`: `errors` names each field at fault and what is wrong with it — a `client_id` that
  is not one of the Business's Clients is answered this way by `essentio_create_draft`. Fix what the
  person can confirm, and ask about the rest.
- `not_found`: a tool that names a record by its id — for example `essentio_issue_document`,
  `essentio_send_document` or `essentio_get_document` — did not find it in this Business. `message`
  names the search tool that lists them; find it again there.
- `idempotency_in_flight`: an identical call is still being performed, and nothing more was done. Make
  the same call again, unchanged, a few seconds later: it answers what the first one did. If the first
  call was refused or failed, it kept nothing, and the call again is a new attempt — before sending
  again, read the document with `essentio_get_document` to see whether it was issued or sent.
- `idempotency`: an `idempotency_key` you sent was used before with other arguments, and nothing was
  done. A new call takes a new key.

Two failures carry no such tool error:

- **The connector refused the request** (HTTP 429, a rate limit): the connection made more requests in
  the last minute than it may — every request counts, listing the tools included — and the request
  did not reach any tool. Wait about a minute. Before making a write again, read back with
  `essentio_get_document` or a search whether it happened.
- **An internal or server error**: a fault on Essentio's side, and it does not tell you what was
  written. Read the document back with `essentio_get_document`, or search for it, before calling
  anything again.

## In a Test business

When the connection is to a Test business, its documents are marked as samples and everything it sends
goes to its Owner, never to the Client. It is the place to try this workflow first.
`essentio_get_business_setup` and every document say so with `is_test: true`, and every number it
issues carries `TEST-`, such as `TEST-INV-2026-0007`. It issues no more Invoices a year than the
Free plan: past that, Issue and Send are refused `issuing_limit_reached`, which its Owner clears by
resetting it in Essentio. Tell the person it is a sample, not a real Invoice.