feat(tax): send Motamed ASA invoices to the tax sandbox in sandbox mode #41

Merged
morrning merged 1 commit from asatsp/arc:feature/motamed-asa-sandbox into master 2026-11-07 15:39:23 +03:30
Contributor

خلاصه

به درخواست شما، ارسال از طریق «معتمد آسا» در «حالت سندباکس» هم کار می‌کند. API نسخه ۲ آسا محیط Sandbox جداگانه‌ای ندارد: همان نشانی (https://api-v2.asatsp.ir)، همان توکن و همان شناسه و رمز کلاینت به کار می‌رود و هر عضو data[] در /api/invoice/send با فیلد sandBox مشخص می‌کند به کدام محیط برود (بخش 05F مستند API نسخه ۲). ساختار تغییری نکرده است: جدول، ستون یا migration تازه‌ای نیست و همان الگوی ارائه‌دهنده و همان tax_settings.sandbox_mode استفاده شده است. رفتار «ارسال مستقیم» و فن‌آوا تغییری نکرده است.

رفتار

  • ارسال: با روشن بودن sandbox_mode، هر عضو /api/invoice/send (صورت‌حساب اصلی و برگشت از فروش) با sandBox: true و بدون fiscalId فرستاده می‌شود. آسا آن را فقط با شناسه حافظه مالیاتی Sandbox همان کسب‌وکار (پیش‌فرض Sandbox یا تنها شناسه فعال آن) می‌پذیرد و به محیط آزمایشی سازمان امور مالیاتی می‌فرستد. شناسه حافظه‌ای که هنگام ثبت‌نام صادر شده عملیاتی است و در درخواست Sandbox پذیرفته نمی‌شود، برای همین فرستاده نمی‌شود. در حالت عادی، عضو با sandBox: false و همان شناسه حافظه قبلی فرستاده می‌شود.
  • اصلاحی، ابطال و ثبت پرداخت: editInvoice، cancelInvoice و registerPayment فیلد sandBox ندارند و صورت‌حساب در همان محیطی می‌ماند که ثبت شده است (بخش 08D: «حافظهٔ مالیاتی و محیط … همان صورتحساب می‌ماند»).
  • بدون جابه‌جایی بین محیط‌ها: محیط هر سند در extra_info.asa_sandbox ثبت می‌شود؛ سندهایی که پیش از این تغییر ارسال شده‌اند عملیاتی‌اند. زنجیره Sandbox کد داخلی جداگانه دارد (hesabix-sandbox-{id})، چون آسا internalId را برای هر کسب‌وکار در هر دو محیط یکتا نگه می‌دارد. روشن یا خاموش کردن حالت سندباکس هیچ صورت‌حسابی را جابه‌جا نمی‌کند:
    • اصلاحی، ابطال یا ثبت پرداختِ صورت‌حسابی که در محیط دیگر ثبت شده، پیش از تغییر وضعیت سند، با خطای روشن MOTAMED_ASA_ENVIRONMENT_MISMATCH رد می‌شود (مثلاً ابطال یک صورت‌حساب واقعی در حالت سندباکس انجام نمی‌شود).
    • صورت‌حساب اصلی یا برگشتی که آسا آن را در محیط دیگر ندارد یا رد شده است، در محیط فعلی از نو فرستاده می‌شود؛ اگر ثبت شده یا در جریان باشد، رد می‌شود.
    • برگشت از فروش فقط به فروشی از همان محیط ارجاع می‌دهد (MOTAMED_ASA_REFERENCE_OTHER_ENVIRONMENT).
  • استعلام: هر زنجیره با همان internalId ذخیره‌شده‌اش استعلام می‌شود، در هر محیطی که باشد. خواندن جدول پرداخت هم در هر دو حالت ممکن است.
  • محدودیت‌های قبلی: همه موارد MOTAMED_ASA_SANDBOX_UNAVAILABLE (ذخیره تنظیمات، انتخاب روش، ورود دستی کلید و ارسال) برداشته شد. محدودیت فن‌آوا سر جایش است.
  • رابط کاربری: گزینه «ارسال از طریق معتمد آسا» در حالت سندباکس هم قابل انتخاب است. وقتی این روش انتخاب شده و حالت سندباکس روشن است، پیامی زیر آن می‌گوید صورت‌حساب‌ها به محیط آزمایشی سازمان می‌روند، شناسه حافظه مالیاتی Sandbox کسب‌وکار باید در معتمد آسا ثبت شده باشد و صورت‌حساب‌های محیط اصلی در این حالت فقط استعلام می‌شوند. کلید motamedAsaSandboxNote جای کلید بی‌استفاده motamedAsaSandboxUnavailable را گرفته است (ARB فارسی و انگلیسی و فایل‌های تولیدی).

راه‌اندازی برای یک کسب‌وکار

  1. کسب‌وکار از قبل به معتمد آسا متصل است (همان روند فعلی).
  2. شناسه یکتای حافظه مالیاتی Sandbox کسب‌وکار از محیط آزمایشی سازمان (https://sandboxrc.tax.gov.ir) گرفته و در معتمد آسا برای همان کسب‌وکار ثبت می‌شود. اگر چند شناسه Sandbox فعال بدون پیش‌فرض داشته باشد، یکی پیش‌فرض می‌شود.
  3. در «تنظیمات مودیان»، «حالت سندباکس» روشن و ذخیره می‌شود.

آزمون‌ها

cd hesabixAPI
pytest -q tests/test_motamed_asa_client.py tests/test_motamed_asa_invoice_payload.py tests/test_motamed_asa_provider_service.py tests/test_motamed_asa_sandbox.py
# 82 passed (23 تست تازه در test_motamed_asa_sandbox.py)
pytest -q -k "tax or invoice or moadian or fanava" --continue-on-collection-errors
# 248 passed; همان 10 شکست و 8 خطای جمع‌آوری که روی master هم هست (نبودن PIL، weasyprint و tzdata در محیط ما، PostgreSQL محلی، یک مسیر ثابت /opt)

cd hesabixUI/hesabix_ui
flutter analyze lib/pages/business/tax_settings_page.dart lib/l10n/app_localizations*.dart
# هیچ مورد تازه‌ای نسبت به master
flutter build web --release
# موفق

Summary (English)

Sandbox support for the Motamed ASA provider, without architectural change (no table, column or migration).

  • With tax_settings.sandbox_mode on, every /api/invoice/send member (original and return) carries sandBox: true and no fiscalId; ASA accepts it only with the business's Sandbox fiscal memory (its default or only active one) and sends it to the tax organisation's sandbox (API v2 docs, 05F). Otherwise sandBox: false with the business's memory id, as before.
  • editInvoice, cancelInvoice and registerPayment take no sandBox; an invoice stays in the environment it was registered in (08D).
  • Each document records its environment (extra_info.asa_sandbox; older chains are production) and a sandbox chain has its own internalId (hesabix-sandbox-{id}). Changing the setting never moves an invoice: a correction, cancellation or payment of an invoice from the other environment is refused (MOTAMED_ASA_ENVIRONMENT_MISMATCH) before the document is marked as being sent; an original or return unknown to ASA or refused there restarts in the current environment; a return must refer to a sale of its own environment.
  • Inquiries read each chain by its stored internalId.
  • The MOTAMED_ASA_SANDBOX_UNAVAILABLE guards are removed; Fanava's are kept.
  • Tax settings show a note while sandbox mode is on for Motamed ASA.
  • Tests: tests/test_motamed_asa_sandbox.py.

تیم فنی معتمد آسا

🤖 Generated with Claude Code

## خلاصه به درخواست شما، ارسال از طریق «معتمد آسا» در «حالت سندباکس» هم کار می‌کند. API نسخه ۲ آسا محیط Sandbox جداگانه‌ای ندارد: همان نشانی (`https://api-v2.asatsp.ir`)، همان توکن و همان شناسه و رمز کلاینت به کار می‌رود و هر عضو `data[]` در `/api/invoice/send` با فیلد `sandBox` مشخص می‌کند به کدام محیط برود (بخش 05F مستند API نسخه ۲). ساختار تغییری نکرده است: جدول، ستون یا migration تازه‌ای نیست و همان الگوی ارائه‌دهنده و همان `tax_settings.sandbox_mode` استفاده شده است. رفتار «ارسال مستقیم» و فن‌آوا تغییری نکرده است. ## رفتار - **ارسال:** با روشن بودن `sandbox_mode`، هر عضو `/api/invoice/send` (صورت‌حساب اصلی و برگشت از فروش) با `sandBox: true` و بدون `fiscalId` فرستاده می‌شود. آسا آن را فقط با شناسه حافظه مالیاتی Sandbox همان کسب‌وکار (پیش‌فرض Sandbox یا تنها شناسه فعال آن) می‌پذیرد و به محیط آزمایشی سازمان امور مالیاتی می‌فرستد. شناسه حافظه‌ای که هنگام ثبت‌نام صادر شده عملیاتی است و در درخواست Sandbox پذیرفته نمی‌شود، برای همین فرستاده نمی‌شود. در حالت عادی، عضو با `sandBox: false` و همان شناسه حافظه قبلی فرستاده می‌شود. - **اصلاحی، ابطال و ثبت پرداخت:** `editInvoice`، `cancelInvoice` و `registerPayment` فیلد `sandBox` ندارند و صورت‌حساب در همان محیطی می‌ماند که ثبت شده است (بخش 08D: «حافظهٔ مالیاتی و محیط … همان صورتحساب می‌ماند»). - **بدون جابه‌جایی بین محیط‌ها:** محیط هر سند در `extra_info.asa_sandbox` ثبت می‌شود؛ سندهایی که پیش از این تغییر ارسال شده‌اند عملیاتی‌اند. زنجیره Sandbox کد داخلی جداگانه دارد (`hesabix-sandbox-{id}`)، چون آسا `internalId` را برای هر کسب‌وکار در هر دو محیط یکتا نگه می‌دارد. روشن یا خاموش کردن حالت سندباکس هیچ صورت‌حسابی را جابه‌جا نمی‌کند: - اصلاحی، ابطال یا ثبت پرداختِ صورت‌حسابی که در محیط دیگر ثبت شده، پیش از تغییر وضعیت سند، با خطای روشن `MOTAMED_ASA_ENVIRONMENT_MISMATCH` رد می‌شود (مثلاً ابطال یک صورت‌حساب واقعی در حالت سندباکس انجام نمی‌شود). - صورت‌حساب اصلی یا برگشتی که آسا آن را در محیط دیگر ندارد یا رد شده است، در محیط فعلی از نو فرستاده می‌شود؛ اگر ثبت شده یا در جریان باشد، رد می‌شود. - برگشت از فروش فقط به فروشی از همان محیط ارجاع می‌دهد (`MOTAMED_ASA_REFERENCE_OTHER_ENVIRONMENT`). - **استعلام:** هر زنجیره با همان `internalId` ذخیره‌شده‌اش استعلام می‌شود، در هر محیطی که باشد. خواندن جدول پرداخت هم در هر دو حالت ممکن است. - **محدودیت‌های قبلی:** همه موارد `MOTAMED_ASA_SANDBOX_UNAVAILABLE` (ذخیره تنظیمات، انتخاب روش، ورود دستی کلید و ارسال) برداشته شد. محدودیت فن‌آوا سر جایش است. - **رابط کاربری:** گزینه «ارسال از طریق معتمد آسا» در حالت سندباکس هم قابل انتخاب است. وقتی این روش انتخاب شده و حالت سندباکس روشن است، پیامی زیر آن می‌گوید صورت‌حساب‌ها به محیط آزمایشی سازمان می‌روند، شناسه حافظه مالیاتی Sandbox کسب‌وکار باید در معتمد آسا ثبت شده باشد و صورت‌حساب‌های محیط اصلی در این حالت فقط استعلام می‌شوند. کلید `motamedAsaSandboxNote` جای کلید بی‌استفاده `motamedAsaSandboxUnavailable` را گرفته است (ARB فارسی و انگلیسی و فایل‌های تولیدی). ## راه‌اندازی برای یک کسب‌وکار 1. کسب‌وکار از قبل به معتمد آسا متصل است (همان روند فعلی). 2. شناسه یکتای حافظه مالیاتی Sandbox کسب‌وکار از محیط آزمایشی سازمان (`https://sandboxrc.tax.gov.ir`) گرفته و در معتمد آسا برای همان کسب‌وکار ثبت می‌شود. اگر چند شناسه Sandbox فعال بدون پیش‌فرض داشته باشد، یکی پیش‌فرض می‌شود. 3. در «تنظیمات مودیان»، «حالت سندباکس» روشن و ذخیره می‌شود. ## آزمون‌ها ``` cd hesabixAPI pytest -q tests/test_motamed_asa_client.py tests/test_motamed_asa_invoice_payload.py tests/test_motamed_asa_provider_service.py tests/test_motamed_asa_sandbox.py # 82 passed (23 تست تازه در test_motamed_asa_sandbox.py) pytest -q -k "tax or invoice or moadian or fanava" --continue-on-collection-errors # 248 passed; همان 10 شکست و 8 خطای جمع‌آوری که روی master هم هست (نبودن PIL، weasyprint و tzdata در محیط ما، PostgreSQL محلی، یک مسیر ثابت /opt) cd hesabixUI/hesabix_ui flutter analyze lib/pages/business/tax_settings_page.dart lib/l10n/app_localizations*.dart # هیچ مورد تازه‌ای نسبت به master flutter build web --release # موفق ``` --- ## Summary (English) Sandbox support for the Motamed ASA provider, without architectural change (no table, column or migration). - With `tax_settings.sandbox_mode` on, every `/api/invoice/send` member (original and return) carries `sandBox: true` and no `fiscalId`; ASA accepts it only with the business's Sandbox fiscal memory (its default or only active one) and sends it to the tax organisation's sandbox (API v2 docs, 05F). Otherwise `sandBox: false` with the business's memory id, as before. - `editInvoice`, `cancelInvoice` and `registerPayment` take no `sandBox`; an invoice stays in the environment it was registered in (08D). - Each document records its environment (`extra_info.asa_sandbox`; older chains are production) and a sandbox chain has its own internalId (`hesabix-sandbox-{id}`). Changing the setting never moves an invoice: a correction, cancellation or payment of an invoice from the other environment is refused (`MOTAMED_ASA_ENVIRONMENT_MISMATCH`) before the document is marked as being sent; an original or return unknown to ASA or refused there restarts in the current environment; a return must refer to a sale of its own environment. - Inquiries read each chain by its stored internalId. - The `MOTAMED_ASA_SANDBOX_UNAVAILABLE` guards are removed; Fanava's are kept. - Tax settings show a note while sandbox mode is on for Motamed ASA. - Tests: `tests/test_motamed_asa_sandbox.py`. --- تیم فنی معتمد آسا 🤖 Generated with [Claude Code](https://claude.com/claude-code)
feat(tax): send Motamed ASA invoices to the tax sandbox in sandbox mode
Some checks are pending
Flutter Windows / verify-windows (pull_request) Blocked by required conditions
2d06563b6c
Hesabix asked for a sandbox. Motamed ASA's API v2 has no separate sandbox
host: the same base URL, token and client credentials are used, and each
/send member says where it goes with sandBox (API v2 docs, section 05F).
No new table, column or migration; Direct and Fanava are unchanged.

- With tax_settings.sandbox_mode on, every /api/invoice/send member
  (original, return) carries sandBox: true and no fiscalId: ASA accepts it
  only with the business's Sandbox fiscal memory (its default, or the only
  active one) and sends it to the tax organisation's sandbox. The memory id
  issued at sign-up is a production one. In production mode the member
  carries sandBox: false and that memory id, as before.
- editInvoice, cancelInvoice and registerPayment take no sandBox: an invoice
  keeps the environment it was registered in (docs 08D). Each document
  records its environment in extra_info.asa_sandbox (chains sent before this
  change are production), and a sandbox chain has its own internalId
  (hesabix-sandbox-{id}), as ASA keeps internalIds unique per business across
  both environments.
- Changing the setting never moves an invoice. Before the document is marked
  as being sent, a correction or cancellation of an invoice from the other
  environment is refused (MOTAMED_ASA_ENVIRONMENT_MISMATCH); an original or
  return whose chain there is unknown to ASA or was refused starts again in
  the current environment, one registered or in flight is refused. Payment
  registration follows the same rule; reading payments and inquiries work in
  either mode, each chain by its stored internalId. A return must refer to a
  sale of its own environment (MOTAMED_ASA_REFERENCE_OTHER_ENVIRONMENT).
- The MOTAMED_ASA_SANDBOX_UNAVAILABLE guards are removed (settings save,
  provider selection, manual credentials, sending); Fanava's stay.
- Tax settings: Motamed ASA stays selectable in sandbox mode, and a note says
  where invoices go and that the business's Sandbox fiscal memory must be
  registered with Motamed ASA. motamedAsaSandboxNote replaces the now unused
  motamedAsaSandboxUnavailable (ARB and generated files).

Tests: tests/test_motamed_asa_sandbox.py

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Owner

مشکلی که وجود داره اینکه تفکیک بین محیط سندباکس و واقعی وجود نداره. برای مثال یک فاکتور به محیط سندباکس ارسال شده و الان میخوایم به محیط واقعی ارسال کنیم. افزونه فکر میکنه که قبلا ارسال شده این صورتحساب. من فکر میکنم باگ باشه

مشکلی که وجود داره اینکه تفکیک بین محیط سندباکس و واقعی وجود نداره. برای مثال یک فاکتور به محیط سندباکس ارسال شده و الان میخوایم به محیط واقعی ارسال کنیم. افزونه فکر میکنه که قبلا ارسال شده این صورتحساب. من فکر میکنم باگ باشه
Owner

ما اینو مرچ میکنیم ولی باید این مشکل حل بشه

ما اینو مرچ میکنیم ولی باید این مشکل حل بشه
morrning merged commit f3b494f0b9 into master 2026-11-07 15:39:23 +03:30
Some checks are pending
Flutter Windows / verify-windows (pull_request) Blocked by required conditions
Some workflows are waiting to be reviewed.
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
hesabix/arc!41
No description provided.