feat(tax): add Motamed ASA as a tax submission provider #23
Merged
morrning
merged 2 commits from 2026-10-23 13:56:29 +03:30
asatsp/arc:feature/motamed-asa-provider into master 2026-10-20
refactor(tax): send Motamed ASA sales returns as the return document's lines
As agreed in the review, Hesabix no longer rebuilds the rows left after a return. The return document's own lines go to /api/invoice/send with ins=4 and returnRows "returned"; Motamed ASA (API v2 1.0.0.71) matches each line to the registered reference rows by goods id, unit price, VAT rate and discount per unit, refuses an ambiguous line instead of guessing (INVOICE_RETURN_ROW_AMBIGUOUS), spreads a line over identical rows, and builds the remaining rows with every tax field (vop, ssrv, ...) of the reference. - irtaxid is the sale's tax id as Motamed ASA gave it; ASA finds the chain's latest invoice itself, so no inquiry is needed first. - buyer fields are left out of a return (outside the pattern; they come from the reference). - a return already rejected at ASA is not rewritten through editInvoice. Removes build_motamed_asa_return_invoice and _remaining_row. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
feat(tax): add Motamed ASA as a tax submission provider
«معتمد آسا» becomes a third, optional sending method beside «ارسال مستقیم» and «همراه فنآوا». It follows the Fanava provider pattern and reuses tax_provider_credentials, business_tax_provider_accounts and tax_settings.submission_provider: no new table and no migration. Direct and Fanava behaviour is unchanged; the default stays moadian_direct. Connection (informed consent): - The tax settings page shows what is shared with Motamed ASA and why, with links to its terms and to https://asatsp.ir/privacy#partner-software, and asks for explicit consent; consent user and time are stored as for Fanava. - The owner signs up on Motamed ASA's own page (tax-system one-time code); Hesabix collects no identity documents. The business API key is handed to Hesabix once, after the owner agrees there; a business that already has an ASA API v2 key can enter its client id/secret instead. - The business private key and memory id are not needed: the trusted company signs and sends. Sending (ASA TSP API v2, https://api-v2.asatsp.ir): - original: POST /api/invoice/send with a stable internalId per document; a rejected or unsent invoice is edited in place (editInvoice); - correction: editInvoice with confirmCorrection; - cancellation: cancelInvoice; marked cancelled only once accepted; - sales return: ins=4 whose Body is the rows remaining after the return (RC_IITP.IS_V7.9 table 1), read from the chain's accepted invoice; - timeouts are reconciled by internalId and never re-sent blindly; - ASA issues the tax id; Hesabix stores it from the answer. Inquiry and the tax workspace: - inquire_tax_status, the auto-inquiry loop and the workspace health check read Motamed ASA invoices from ASA (inquiryInternalIds). - The کارپوشه status (buyer reaction) and the Article 6 status (عدول / عدم عدول) of the document's own invoice are kept and shown as two new workspace columns (tax_workspace_status, tax_article6_status). A buyer rejection is shown there and no longer marks a registered invoice failed. - «پرداختها و ثبت در کارپوشه» on a sent Motamed ASA invoice opens its payment table: every row with its registration status, and new rows (method, date/time, amount with VAT, trace and terminal numbers) registered through ASA's registerPayment; locked rows stay read-only and a lost answer reads the rows back instead of sending them again. Admin: «اتصال معتمد آسا» under system settings › external services holds the partner client id/secret Motamed ASA issues for Hesabix. Tests: tests/test_motamed_asa_{client,invoice_payload,provider_service}.py Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>