Create invoice from data
well_create_invoice_from_dataCreate an invoice in Well from data you extracted by reading an invoice (your own OCR) — you send the structured fields, not the file.
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 what the draft still lacks. 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[]: { name, quantity?, unit_price, currency?, tax_rate? } — never send totals: Well computes them from the 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
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, currency, grand_total, issue_date, design_layout (null until a design is chosen) and lines. The card shows them, so the reply does not list them 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. 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 names a draft by the number it will take when issued (DRAFT-061 while the next invoice number is INV-061) 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 | ||
| invoice_id | No | ||
| issue_date | No | ||
| grand_total | No | ||
| source_count | No | How many tools hold the invoice; sources may list fewer. | |
| customer_name | No | ||
| design_layout | No | ||
| payment_means | No | ||
| missing_fields | 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. |