Queue invoice collection
well_enqueue_invoice_fetchQueue invoice collection for named counterparties. This creates one durable backlog task per counterparty. The browser agent (a provider that carries a blueprint or a real portal URL) or the manual-upload route picks up each task later.
Call this tool only after the user explicitly confirms the launch. Never call it on your own initiative.
Get counterparty_company_ids from well_list_missing_invoices. This tool takes no period argument: a collection task belongs to a counterparty, not a month.
A repeat call for a counterparty that already has a non-terminal task reuses that task (already_active: true) instead of creating a second one.
provider.has_blueprint and provider.has_portal_url on an enqueued row state which counterparties a browser agent will visit (either one is enough), and which fall back to manual upload (neither).
Creating the tasks launches nothing in the browser. Inside Well the tasks page and the chat card start and track them. From outside Well, hand the user THIS result's collect_url to start the runs, never the collect_url of well_preview_invoice_fetch: this link carries the task each run answers, so the tasks follow the runs and well_wait_for_process can report each vendor. Give the link as returned and never edit it. It names every enqueued counterparty whose provider has a blueprint or a real portal URL, at most 25 portals; a counterparty past that ceiling appears in collect_url_omits instead of on the link. A counterparty with provider: null, or with neither has_blueprint nor has_portal_url, is routed to manual upload and is not on the link. collect_url is null when no enqueued counterparty can go on a link. Never tell the user the link covers a counterparty it does not name.
Use well_preview_invoice_fetch first to see what a fetch would cover — it is read-only and launches nothing. Use well_enqueue_close_invoice_fetch instead of this tool when you are inside a close run: it is the same action, scoped to that run's flow_run_id. Use this tool outside a close run.
Report the counts back to the user: how many tasks were enqueued, how many of those were already active, and how many counterparties were skipped, with each skip's reason.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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. | |
| 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. | |
| counterparty_company_ids | Yes | Counterparty companies to queue collection for, from well_list_missing_invoices. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| skipped | No | ||
| success | Yes | ||
| enqueued | No | ||
| collect_url | No | The `/collect` link that starts the browser runs of the enqueued counterparties and binds each run to its task. Null when no enqueued counterparty has a provider with a blueprint or a real portal URL. | |
| skipped_count | No | ||
| enqueued_count | No | Rows in enqueued — created or reused. | |
| refusal_reason | No | The WellError code when the write is refused. | |
| 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. | |
| collect_url_omits | No | Enqueued counterparties the link does not name because one link carries at most 25 portals. Present only when the ceiling left some out. | |
| already_active_count | No | Of enqueued_count, how many reused an existing task rather than creating one. | |
| 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. |