Create invoice from data
well_create_invoice_from_dataLoad the draft-invoice skill with well_get_skill before you call this.
Create an invoice in Well from data you extracted by reading an invoice (your own OCR) — you send the structured fields, not the file.
Never call it to add a product or a service to the catalog, or to change a product's price ("Ajoute le produit Audit SEO à 1 200 € HT", "Passe Audit SEO à 1 400 €"): those are well_create_product and well_update_product, and they make no invoice.
Well persists the invoice + its line items + payment means using the same pipeline as uploaded documents. Fill every field you can read from the document:
issuer / receiver: { name (required), company_id?, domain?, tax_id? }
A draft may be saved before it is complete: with status "draft", leave out the issuer, the receiver, issue_date, currency or line_items you do not know yet, and never invent one. On such a draft a party you do send carries its company_id, currency is required as soon as there is a line, and payment_means is left out. The answer's missing_fields names every part the draft still lacks before it can be issued, the issuer's own details included; the draft is complete only when it is empty. Any other status needs every part
invoice_number (the invoice's own number, read from the document; leave it out for a draft, Well numbers drafts itself), reference_number? (a reference printed apart from the invoice number; never the invoice number itself; ignored on a draft), issue_date (YYYY-MM-DD), due_date? (YYYY-MM-DD; leave it out on a draft the person gave no due date: Well sets the customer's usual terms, else 30 days after the issue date), currency (ISO 4217)
line_items[]: { line_id?, parent_line_id?, name, line_kind?, ordinal?, printed_subtotal?, product_id?, quantity?, unit_price, currency?, tax_rate? }. A section uses line_kind "section", unit_price null and an ordinal; its printed_subtotal must equal the billed descendants it closes. It prints as a heading and never changes invoice totals. A product_id can name a live product from well_list_products or an exact SKU match returned in well_define_line_items. When product_id is absent, Well links the line only if exactly one active product in this workspace has the exact line name or SKU and the same unit price and currency. Zero or multiple matches stay unlinked. Well does not create or change a product, and a stated price applies to this invoice only. The result's line_catalogue_attribution says which saved line has a product link and whether its exact price came from the catalogue. Never send totals: Well computes them from billed lines, each line held to the currency's minor units
printed_grand_total? — the grand total printed on a document you read. Well still stores the computed total; when the printed one differs by more than rounding, the answer carries printed_total_mismatch { printed_grand_total, computed_grand_total }: tell the user both figures
payment_means?[]: { type, iban?, bic?, scheme? }
status?: draft | issued | paid | canceled — create an invoice the user is still reviewing as "draft", then issue it with well_issue_invoice once the user confirms; issuing gives it the next invoice number and locks it. "paid" is an "issued" request that also records the source's claim that the invoice was settled; it is never a lifecycle word of its own
document_type_code?: "380" invoice | "381" credit note (state it: an invoice with no document type cannot post); corrects_invoice_id? — the issued invoice a credit note corrects, required for a credit note. An issued invoice cannot be edited: correct it with a credit note, then create a new invoice
ONE CALL IS THE WHOLE WRITE. This tool takes the invoice's status and both parties' company ids, so a create never needs a well_update_invoice after it:
The user asked to DRAFT an invoice → pass status: "draft" here.
You already found the company (well_query_records, well_get_entity) → pass its company_id on that party. Naming the party without its id re-resolves it, which can attach the invoice to the wrong company or create a duplicate one.
Creating and then patching the same invoice writes twice and shows the user two confirmations for one action. Put the intent in this call.
The answer carries the saved invoice's status, customer_name, customer_siren (absent while the customer has none), currency, grand_total, issue_date, design_layout (null until a design is chosen) and lines. line_catalogue_attribution marks each line as catalogue only when the exact active catalogue product is linked and its unit price and currency match; otherwise it says not_catalogue. The card shows the invoice summary, so the reply does not list those fields again.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| issuer | No | The company that issues the invoice. Leave it out only on a draft whose issuer is not known yet. | |
| status | No | The invoice's lifecycle status. Set it here when the user asked for one ("draft an invoice") — do NOT create and then call well_update_invoice to change it. Omitted, Well derives one only where the document type decides it; otherwise the invoice has no status. | |
| currency | No | ISO 4217 (3 letters). Required as soon as the invoice has a line; never guessed by Well. | |
| due_date | No | ISO 8601 YYYY-MM-DD. | |
| receiver | No | The customer: a company, or a private individual named by person_id. Leave it out only on a draft whose customer is not known yet. | |
| issue_date | No | ISO 8601 YYYY-MM-DD. Leave it out only on a draft whose date is not set yet. | |
| line_items | No | The lines. Leave them out only on a draft whose lines are not known yet. | |
| workspace_id | No | Target workspace. Omit when the token authorizes one workspace. Required when it authorizes several — a write lands in exactly one workspace and this call would not say which. | |
| payment_means | No | ||
| invoice_number | No | The invoice's own number, read from the document. Required unless the invoice is a draft or created to be issued: Well numbers those when they are issued. Never make one up. | |
| conversation_id | No | The conversation id returned by the previous Well result, in its meta under well/conversation_id, in its structuredContent, or in its JSON text block. Pass it back on every call in the same conversation, including a call a card makes, so the chosen workspace and the earlier answers still apply. It decides the conversation on its own: nothing the host states about the session replaces it. Omit it only on the first call of a conversation. | |
| idempotency_key | No | Optional client-supplied key. A retried write with the same key returns the original result instead of re-applying the operation. | |
| workspace_scope | No | Restrict this call to the family: the token's primary workspace plus the company workspaces under it that you are a member of. Unrelated authorized workspaces drop out of the read; row reads merge across the family, while a per-workspace figure still reports exactly one workspace. | |
| reference_number | No | A reference printed apart from the invoice's own number. Never the invoice number itself. Leave it out for a draft: Well gives each draft its own reference (DRAFT-0007) at its first save, even while it still lacks parts, takes the invoice number only when the draft is issued, and ignores any value sent. | |
| document_type_code | No | "380" is an invoice; "381" is a credit note that corrects an invoice already issued. Omitted, the invoice has no document type and cannot post. An issued invoice cannot be edited, so a correction is a credit note with its own number, then a new invoice. | |
| corrects_invoice_id | No | The UUID of the issued invoice a credit note corrects. Required for a credit note (381); refused otherwise. | |
| printed_grand_total | No | The grand total printed on a document you read, as printed. Leave it out for an invoice Well drafts. Well still stores the total it computes from the lines; when the two differ by more than rounding, the answer carries printed_total_mismatch. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| code | No | ||
| error | No | ||
| lines | No | ||
| status | No | ||
| sources | No | The tools that hold a copy of the invoice, highest source precedence first. Empty when no tool holds it. | |
| success | Yes | ||
| currency | No | ||
| tax_total | No | ||
| invoice_id | No | ||
| issue_date | No | ||
| grand_total | No | ||
| items_total | No | ||
| source_count | No | How many tools hold the invoice; sources may list fewer. | |
| customer_name | No | ||
| design_layout | No | ||
| payment_means | No | ||
| customer_siren | No | The SIREN the invoice prints for its customer. Absent while the customer has none. | |
| missing_fields | No | On a draft, every part the person gives that it still lacks before it can be issued. The draft is complete only when this list is empty. | |
| card_line_count | No | ||
| conversation_id | No | The conversation this result belongs to. Pass it back as the conversation_id argument on every later Well call in the same conversation. | |
| newly_connected | No | Tools that connected to this workspace since the last result and that no session was told about yet, oldest first. Present only when at least one tool is new. The connected-line rule says when to tell an entry; when it does, one line per entry, in the person's language: "<name> is connected.". Never fold several entries into one sentence. Each entry comes back once, on one result only: never repeat its line later. | |
| reference_number | No | ||
| invoice_item_count | No | ||
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| conversation_id_source | No | Where the conversation id came from: the host's own request meta, the caller's argument, or a fresh lane the server opened. | |
| printed_total_mismatch | No | The document's printed grand total differs from the total Well computed from the lines and stored. Tell the user both figures; a document-level discount or charge belongs on its own line. | |
| next_invoice_number_state | No | Whether the workspace's next invoice number lets the issue go ahead. Well settles it when the invoice is issued: it is never named to the person and never makes the draft incomplete. | |
| line_catalogue_attribution | No |