feat(tax): add Motamed ASA as a tax submission provider #23

Merged
morrning merged 2 commits from asatsp/arc:feature/motamed-asa-provider into master 2026-10-23 13:56:29 +03:30

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>
2026-10-20 17:06:42 +03:00
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>
2026-10-20 02:01:02 +03:00