3.0 KiB
Invoicing
An optional client of the platform's Invoicing service. It stores no invoices, numbering sequence
or totals locally. It ships off. pnpm kit module:on invoicing includes it and requests invoice
read/draft plus series-read scopes; it neither enables the service nor approves permissions.
Issue, credit, void and series administration require deliberate additional platform scope approval.
The module remains unsupported on Convex.
The page is mounted under a project at /<org>/<workspace>/<project>/invoicing; its records and
permissions are explicitly scoped to the app organization, across that organization's projects.
It does not claim project-private invoice storage. The gateway separately binds the app organization
to the approved Cloud organization/project/environment connection. A request resolves current app
membership before readiness or service dispatch. Browser slugs, party references and resource IDs
confer no authority.
The contracts expose invoice/series reads, draft creation/editing, explicit issue/credit/void, series creation and UBL download. The common form supports multiple lines, postal/electronic party addresses, VAT identifiers, category/rate and exemption reason. It preserves unedited identifiers, payment details, notes, adjustments and extensions in an existing draft. Advanced terms remain available through the typed contract. CRM party links are metadata, not an implicit cross-service lookup or permission. App member subject references must match the prepared binding.
Draft writers need the editor role. Fiscal actions and series configuration require an administrator; the server checks these permissions independently of hidden UI controls. An issue/credit/void input requires explicit confirmation and the exact current revision. Identical retries retain their operation key; editing the submitted terms produces a different key. The service alone allocates numbers, calculates amounts, resolves retries and preserves issued snapshots. Neither app code nor binary rollback rewinds those facts. Credits create a new draft that must be reviewed and issued. Nothing automatically sends an invoice or invokes a payment provider.
Money and revisions cross the app boundary as validated strings. The generated SDK uses exact int64 encoding; quantities become bigint only inside the adapter. The form never calculates fiscal totals with JavaScript floats. Missing series, configuration, grant, entitlement, incompatible API/profile, revoked partition and degraded dependencies remain distinct bounded readiness errors. Remote error details are not shown. UBL is an explicit bounded XML download.
Local tests use memory ports and synthetic HTTP; they establish app permissions, foreign-org denial, wire values and control behavior. Real runtime-role service, numbering/retry/restore and gateway/app journeys are separate release gates. Fiscal retention/export/erasure remain service-owned; see the platform compliance inventory. No customer data belongs in fixtures.