Retry bank matching for a period
well_retry_period_matchingAsk Well to look again for the bank payment behind a fiscal period's invoices that are marked paid with no confirmed bank payment, now. The automatic pass looks again at an invoice only when new bank activity arrives, so do not wait for it. Call it when well_list_period_unmatched_invoices shows unmatched_count above 0 for the period and the user asked to fix the gaps.
It takes the period only. Well picks the invoices on its side, from the period's unmatched invoices (at most 20 per call, in a fixed order); you never pass invoice ids. An invoice whose matching is already queued or running is skipped, so a repeat call while it runs adds nothing; call it once per ask.
The call itself books nothing. It only queues the matching, so it returns before any match lands: never say the gap is fixed. A match the matcher confirms later posts its payment journal like any automatic match, so do not tell the user that nothing will be posted. Say Well is looking again for enqueued_invoice_ids, and name each skipped invoice with its reason (not_found, already_matched, already_queued, dispatch_failed). not_attempted_count is the part of the period's unmatched invoices this call did not send. This call does not retry them, and the automatic pass re-checks them only when new bank activity arrives: do not tell the user they are covered. Read the period again later to see what matched.
Take fiscal_year and fiscal_period from a well_list_period_unmatched_invoices or well_list_periods entry; never derive them from a calendar month yourself.
success: false means nothing was sent. Never report a failed call as a retry in progress.
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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fiscal_year | Yes | The fiscal year of the period. | |
| 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. | |
| fiscal_period | Yes | The fiscal period, month 1-12. | |
| 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | ||
| skipped | Yes | ||
| success | Yes | ||
| fiscal_year | Yes | ||
| fiscal_period | Yes | ||
| 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. | |
| unmatched_count | Yes | ||
| not_attempted_count | Yes | ||
| conversation_id_note | No | Present only when the server opened a fresh lane, stating that no choice recorded earlier was read. | |
| enqueued_invoice_ids | Yes | ||
| 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. |