Prepare the micro-entrepreneur turnover declaration
well_prepare_micro_declarationPrepare a French micro-entrepreneur's URSSAF turnover declaration for one period, as a draft PDF stored in the workspace: the turnover of each activity box from the bank receipts matched to issued invoices, and an estimate of what URSSAF will ask. Well fills the turnover on autoentrepreneur.urssaf.fr in the person's own Chrome; the person clicks Send and files it. This call declares, sends and pays nothing.
Call it when the person asks to prepare or file their URSSAF turnover declaration, after the period's turnover was read with well_get_micro_turnover and every payment with no invoice was answered. Pass no window for the next declaration due whose period has ended (when none is due yet, the latest period that has ended, whose due date has passed: say it is late), or from and to (YYYY-MM-01, to exclusive) for one declaration period. Before every fill, call it again: it reads the URSSAF rates again first.
Refusals, with no PDF:
profile_incomplete: the profile lacks the keys inmissing(the URSSAF filing frequency, the legal form). Propose a value only from what a read returned, save it withwell_upsert_accounting_settingson the person's yes, and call again.not_owed: the profile is not a micro-entrepreneur's.not_a_period: the window is not one declaration period.period_not_ended: the period is still running.already_filed: a draft of this period is already filed (document_id,filed_at). Never offer the fill: a second one would declare the period twice.unsupported_jurisdiction(not France),unsupported_currency(books not in EUR),too_many_receipts(the period holds more receipts than one read takes),failed.
On ok, a period with no turnover is still a declaration: nil is true and each box reads « néant ». document_id names the PDF, the input of the browser fill. lines lists each declared box in whole euros; the fill types only these. estimate is what URSSAF will likely ask: URSSAF computes the amount itself, so say it is an estimate, give estimate.total_euros, and say each estimate.gaps item in one clause (ACRE not asked, undated or ending inside the period, CIPAV not applied, CFP at the commercial rate, chamber fees left out, flat income tax option unknown, a rate with no value, receipts in another currency left out). Four gaps change the turnover itself; say each and ask the person to confirm the boxes before the fill: vat_share_assumed (some receipts have no known VAT share, so they count net of VAT at the standard 20 % rate), vat_regime_assumed_franchise (the profile states no VAT regime, so receipts with no invoice count in full, as in the VAT franchise: ask the VAT regime and save it with well_upsert_accounting_settings on the person's yes), bank_copy_not_fresh and no_bank_source (the receipts can be incomplete, and the fill waits). stale_sources lists each bank source that is not fresh enough: for an installation with syncable: true, call well_request_sync with its workspace_connector_id, then prepare again; with syncable: false it belongs to another workspace, so never request its sync and say the bank copy dates from synced_at; for a statement, say the statements stop at covered_to and ask for the statement that covers the rest of the period; for an uncovered_account, name the account and ask the person to connect its bank or send its statements. unsourced_receipts above zero means receipts came from a bank that is no longer connected or from no bank: say so. sources_truncated true means the period has more bank sources than one read lists. Either one holds the fill like a stale source. When estimate.total_euros is null, a rate is missing: say the amount is to be completed, never zero. rate_read: rule_changed means a URSSAF rate changed since the last draft of this period: say the new amount and ask again before the fill. read_failed means the rates could not be read: the fill waits until a later call reads them. Null means no box needed a rate. receipts_waiting above zero means payments still wait for the person's answer: ask about them before the fill. other_currency_receipts above zero means receipts in another currency than the euro are not in any box, because Well does not convert them: say so, and the fill waits. Never say the declaration is filed.
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 |
|---|---|---|---|
| to | No | EXCLUSIVE end: the first day of the month after the period, YYYY-MM-01. | |
| from | No | First day of the period, YYYY-MM-01. Give it with `to`, or omit both for the next declaration due. | |
| 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. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| nil | No | True when every declared box is zero: the period is declared « néant ». | |
| file | No | ||
| error | No | ||
| lines | No | ||
| period | No | ||
| status | Yes | ||
| missing | No | ||
| success | Yes | ||
| currency | No | ||
| estimate | No | ||
| filed_at | No | When the period's draft was filed, on an `already_filed` refusal. | |
| filename | No | ||
| rate_read | No | ||
| document_id | No | ||
| stale_sources | No | The bank sources not fresh enough for the period: the receipts can be incomplete, and the fill waits. | |
| 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. | |
| receipts_waiting | No | ||
| sources_truncated | No | True when the period has more bank sources than one read lists: the fill waits. | |
| unsigned_receipts | No | ||
| browser_skill_slug | No | ||
| resolved_workspace | No | The workspace that answered, when the caller named none and the token authorizes several. | |
| unsourced_receipts | No | Receipts of the period that no listed bank source stands for: the fill waits while above zero. | |
| 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. | |
| other_currency_receipts | No | Receipts in another currency than the euro, which no box counts: the fill waits while above zero. |