Watch
1
0
Fork
You've already forked arc
0
forked from hesabix/arc
arc/hesabixAPI/adapters/api/v1/tax_settings.py
Motamed ASA fa730b6ab0 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

548 lines
22 KiB
Python
Executable file

from typing import Dict, Any, Tuple
from fastapi import APIRouter, Depends, Request, Body
from sqlalchemy.orm import Session
from adapters.db.session import get_db
from adapters.db.models.document import Document
from adapters.api.v1.schema_models.tax_settings import (
TaxSettingsSaveRequest,
TaxSettingsTestConnectionRequest,
GenerateKeysRequest,
GenerateKeysResponse,
)
from app.core.auth_dependency import get_current_user, AuthContext
from app.core.permissions import require_business_access, require_business_permission_dep
from app.core.moadian_plugin_dependency import ensure_moadian_plugin_active
from app.core.responses import success_response, ApiError
from app.services.tax_setting_service import (
get_tax_setting,
serialize_tax_setting,
upsert_tax_setting,
merge_tax_setting_for_test,
validate_tax_setting_complete,
)
from app.services.tax_data_quality_service import (
get_tax_data_quality,
format_tax_data_quality,
)
from app.services.tax_key_material_service import (
generate_csr_pem,
validate_generate_keys_request,
validate_tax_setting_key_material,
)
from app.services.tax_provider_service import (
get_business_provider_state,
select_business_provider,
fanava_business_call,
sync_business_fanava_account,
)
from app.services.motamed_asa_provider_service import (
MOTAMED_ASA_PROVIDER,
renew_motamed_asa_link,
save_motamed_asa_business_credentials,
sync_motamed_asa_account,
)
from app.services.motamed_asa_tax_submission_service import (
motamed_asa_invoice_payments,
register_motamed_asa_payments,
)
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.primitives import serialization
router = APIRouter(prefix="/tax-settings", tags=["مالیات"])
@router.get("/business/{business_id}")
@require_business_access("business_id")
def get_tax_settings_endpoint(
request: Request,
business_id: int,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "manage_settings")),
):
ensure_moadian_plugin_active(db, business_id)
setting = get_tax_setting(db, business_id)
data = serialize_tax_setting(setting, business_id=business_id, db=db)
return success_response(data=data, request=request, message="TAX_SETTINGS_FETCHED")
@router.get("/business/{business_id}/provider")
@require_business_access("business_id")
def get_tax_provider_endpoint(
request: Request,
business_id: int,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "manage_settings")),
):
ensure_moadian_plugin_active(db, business_id)
return success_response(get_business_provider_state(db, business_id), request, "TAX_PROVIDER_STATE")
@router.post("/business/{business_id}/provider")
@require_business_access("business_id")
def select_tax_provider_endpoint(
request: Request,
business_id: int,
payload: Dict[str, Any] = Body(...),
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "manage_settings")),
):
ensure_moadian_plugin_active(db, business_id)
provider_code = str(payload.get("provider_code") or "").strip().lower()
consented_by_user_id = ctx.get_user_id()
if provider_code in ("fanava", MOTAMED_ASA_PROVIDER) and not consented_by_user_id:
raise ApiError("UNAUTHORIZED", "برای ثبت رضایت باید کاربر وارد شده باشد.", http_status=401)
enrollment = payload.get("enrollment") if isinstance(payload.get("enrollment"), dict) else {}
if provider_code == MOTAMED_ASA_PROVIDER and payload.get("economic_code"):
enrollment = {**enrollment, "economic_code": str(payload.get("economic_code"))}
result = select_business_provider(
db,
business_id=business_id,
provider_code=provider_code,
consent=bool(payload.get("consent")),
consented_by_user_id=consented_by_user_id,
enrollment=enrollment,
)
# Keep the response shape identical to GET /tax-settings/business/{id};
# the client model also owns the existing key material and memory settings.
setting = get_tax_setting(db, business_id)
data = serialize_tax_setting(setting, business_id=business_id, db=db)
if isinstance(result, dict) and result.get("motamed_asa_onboarding"):
# The sign-up link is returned once and never stored.
data["motamed_asa_onboarding"] = result["motamed_asa_onboarding"]
return success_response(data, request, "TAX_PROVIDER_UPDATED")
@router.post("/business/{business_id}/motamed-asa/sync")
@require_business_access("business_id")
def sync_motamed_asa_account_endpoint(
request: Request,
business_id: int,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "manage_settings")),
):
ensure_moadian_plugin_active(db, business_id)
return success_response(sync_motamed_asa_account(db, business_id), request, "MOTAMED_ASA_ACCOUNT_SYNCED")
@router.post("/business/{business_id}/motamed-asa/link")
@require_business_access("business_id")
def renew_motamed_asa_link_endpoint(
request: Request,
business_id: int,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "manage_settings")),
):
ensure_moadian_plugin_active(db, business_id)
return success_response(renew_motamed_asa_link(db, business_id), request, "MOTAMED_ASA_LINK_ISSUED")
@router.post("/business/{business_id}/motamed-asa/credentials")
@require_business_access("business_id")
def save_motamed_asa_credentials_endpoint(
request: Request,
business_id: int,
payload: Dict[str, Any] = Body(...),
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "manage_settings")),
):
ensure_moadian_plugin_active(db, business_id)
consented_by_user_id = ctx.get_user_id()
if not consented_by_user_id:
raise ApiError("UNAUTHORIZED", "برای ثبت رضایت باید کاربر وارد شده باشد.", http_status=401)
state = save_motamed_asa_business_credentials(
db,
business_id=business_id,
client_id=str(payload.get("client_id") or ""),
client_secret=str(payload.get("client_secret") or ""),
consent=payload.get("consent") is True,
consented_by_user_id=consented_by_user_id,
economic_code=str(payload.get("economic_code") or "") or None,
)
return success_response(state, request, "MOTAMED_ASA_ACCOUNT_CONNECTED")
def _motamed_asa_document(db: Session, business_id: int, invoice_id: int) -> Document:
document = (
db.query(Document)
.filter(Document.id == int(invoice_id), Document.business_id == int(business_id))
.first()
)
if document is None:
raise ApiError("INVOICE_NOT_FOUND", "فاکتور پیدا نشد.", http_status=404)
return document
@router.get("/business/{business_id}/motamed-asa/invoices/{invoice_id}/payments")
@require_business_access("business_id")
def get_motamed_asa_payments_endpoint(
request: Request,
business_id: int,
invoice_id: int,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "operate")),
):
ensure_moadian_plugin_active(db, business_id)
document = _motamed_asa_document(db, business_id, invoice_id)
return success_response(motamed_asa_invoice_payments(db, business_id, document), request, "MOTAMED_ASA_PAYMENTS_FETCHED")
@router.post("/business/{business_id}/motamed-asa/invoices/{invoice_id}/payments")
@require_business_access("business_id")
def register_motamed_asa_payments_endpoint(
request: Request,
business_id: int,
invoice_id: int,
payload: Dict[str, Any] = Body(...),
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "operate")),
):
ensure_moadian_plugin_active(db, business_id)
document = _motamed_asa_document(db, business_id, invoice_id)
result = register_motamed_asa_payments(db, business_id, document, payload.get("payments"))
db.commit()
return success_response(result, request, "MOTAMED_ASA_PAYMENTS_REGISTERED")
@router.post("/business/{business_id}/fanava/sync")
@require_business_access("business_id")
def sync_fanava_account_endpoint(
request: Request,
business_id: int,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "manage_settings")),
):
ensure_moadian_plugin_active(db, business_id)
return success_response(sync_business_fanava_account(db, business_id), request, "FANAVA_ACCOUNT_SYNCED")
@router.get("/business/{business_id}/fanava/invoices")
@require_business_access("business_id")
def list_fanava_invoices_endpoint(
request: Request,
business_id: int,
page: int = 0,
size: int = 50,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "operate")),
):
ensure_moadian_plugin_active(db, business_id)
if page < 0 or not 1 <= size <= 50:
raise ApiError("INVALID_PAGINATION", "محدودهٔ صفحه‌بندی نامعتبر است.", http_status=400)
result = fanava_business_call(
db, business_id,
lambda client, token, account: client.list_invoices(token, int(account.cartable_id), page=page, size=size),
)
return success_response(result, request, "FANAVA_INVOICES_LISTED")
@router.get("/business/{business_id}/fanava/invoices/{fanava_invoice_id}")
@require_business_access("business_id")
def get_fanava_invoice_endpoint(
request: Request,
business_id: int,
fanava_invoice_id: int,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "operate")),
):
ensure_moadian_plugin_active(db, business_id)
result = fanava_business_call(
db, business_id,
lambda client, token, account: client.get_invoice(token, int(account.cartable_id), fanava_invoice_id),
)
return success_response(result, request, "FANAVA_INVOICE_FETCHED")
@router.post("/business/{business_id}/fanava/invoices/{fanava_invoice_id}/check-status")
@require_business_access("business_id")
def check_fanava_invoice_endpoint(
request: Request,
business_id: int,
fanava_invoice_id: int,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "operate")),
):
ensure_moadian_plugin_active(db, business_id)
result = fanava_business_call(
db, business_id,
lambda client, token, account: client.check_status(token, int(account.cartable_id), fanava_invoice_id),
)
return success_response({"history": result}, request, "FANAVA_INVOICE_STATUS_CHECKED")
@router.post("/business/{business_id}/fanava/invoices/{fanava_invoice_id}/inquiry-status")
@require_business_access("business_id")
def inquire_fanava_invoice_endpoint(
request: Request,
business_id: int,
fanava_invoice_id: int,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "operate")),
):
ensure_moadian_plugin_active(db, business_id)
history = fanava_business_call(
db, business_id,
lambda client, token, account: client.check_status(token, int(account.cartable_id), fanava_invoice_id),
)
latest = history[-1] if history else {}
if str(latest.get("status") or "").upper() != "SUCCESS":
raise ApiError(
"FANAVA_INVOICE_NOT_READY_FOR_INQUIRY",
"استعلام نهایی فقط پس از موفقیت پردازش صورتحساب در فن‌آوا امکان‌پذیر است.",
http_status=409,
)
result = fanava_business_call(
db, business_id,
lambda client, token, account: client.inquiry_status(token, int(account.cartable_id), fanava_invoice_id),
)
return success_response(result, request, "FANAVA_INVOICE_INQUIRED")
@router.delete("/business/{business_id}/fanava/invoices/{fanava_invoice_id}")
@require_business_access("business_id")
def delete_fanava_invoice_endpoint(
request: Request,
business_id: int,
fanava_invoice_id: int,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "manage_settings")),
):
ensure_moadian_plugin_active(db, business_id)
history = fanava_business_call(
db, business_id,
lambda client, token, account: client.check_status(token, int(account.cartable_id), fanava_invoice_id),
)
latest = history[-1] if history else {}
if str(latest.get("status") or "").upper() != "SAVE":
raise ApiError("FANAVA_INVOICE_DELETE_NOT_ALLOWED", "فقط صورتحساب ذخیره‌شده و ارسال‌نشده از فن‌آوا قابل حذف است.", http_status=409)
result = fanava_business_call(
db, business_id,
lambda client, token, account: client.delete_invoice(token, int(account.cartable_id), fanava_invoice_id),
)
return success_response({"deleted": True, "result": result}, request, "FANAVA_INVOICE_DELETED")
@router.get("/business/{business_id}/fanava/invoice-fields/{code}/subject/{subject}")
@require_business_access("business_id")
def get_fanava_invoice_fields_endpoint(
request: Request,
business_id: int,
code: str,
subject: str,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "operate")),
):
ensure_moadian_plugin_active(db, business_id)
result = fanava_business_call(
db, business_id,
lambda client, token, account: client.invoice_fields_format(token, code, subject),
)
return success_response(result, request, "FANAVA_INVOICE_FIELDS_FETCHED")
@router.post("/business/{business_id}")
@require_business_access("business_id")
def save_tax_settings_endpoint(
request: Request,
business_id: int,
payload: TaxSettingsSaveRequest,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "manage_settings")),
):
ensure_moadian_plugin_active(db, business_id)
user_id = ctx.get_user_id()
if not user_id:
raise ApiError("UNAUTHORIZED", "Authentication required", http_status=401)
validate_tax_setting_key_material(payload.dict())
current_setting = get_tax_setting(db, business_id)
if current_setting and current_setting.submission_provider == "fanava" and payload.sandbox_mode:
raise ApiError(
"FANAVA_SANDBOX_UNAVAILABLE",
"فن‌آوا محیط آزمایشی ندارد؛ ابتدا روش ارسال مستقیم را انتخاب کنید.",
http_status=400,
)
if current_setting and current_setting.submission_provider == MOTAMED_ASA_PROVIDER and payload.sandbox_mode:
raise ApiError(
"MOTAMED_ASA_SANDBOX_UNAVAILABLE",
"ارسال از طریق معتمد آسا فقط در محیط اصلی سامانهٔ مؤدیان انجام می‌شود؛ ابتدا روش ارسال مستقیم را انتخاب کنید.",
http_status=400,
)
setting = upsert_tax_setting(
db,
business_id=business_id,
user_id=int(user_id),
payload=payload.dict(),
)
db.commit()
db.refresh(setting)
data = serialize_tax_setting(setting, business_id=business_id, db=db)
return success_response(data=data, request=request, message="TAX_SETTINGS_SAVED")
@router.post("/business/{business_id}/generate-keys")
@require_business_access("business_id")
def generate_keys_endpoint(
request: Request,
business_id: int,
payload: GenerateKeysRequest = Body(...),
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "manage_settings")),
):
ensure_moadian_plugin_active(db, business_id)
validate_generate_keys_request(payload)
private_pem, public_pem, private_key = _generate_rsa_key_pair()
csr_pem = generate_csr_pem(private_key, payload)
data = GenerateKeysResponse(
private_key=private_pem,
public_key=public_pem,
csr=csr_pem,
).dict()
return success_response(data=data, request=request, message="TAX_KEYS_GENERATED")
@router.get("/business/{business_id}/data-quality")
@require_business_access("business_id")
def tax_data_quality_endpoint(
request: Request,
business_id: int,
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "manage_settings")),
):
ensure_moadian_plugin_active(db, business_id)
report = get_tax_data_quality(db, business_id)
data = format_tax_data_quality(report)
return success_response(data=data, request=request, message="TAX_DATA_QUALITY_REPORT")
@router.post("/business/{business_id}/test-connection")
@require_business_access("business_id")
def test_tax_connection_endpoint(
request: Request,
business_id: int,
payload: TaxSettingsTestConnectionRequest | None = Body(default=None),
ctx: AuthContext = Depends(get_current_user),
db: Session = Depends(get_db),
_: None = Depends(require_business_permission_dep("moadian", "manage_settings")),
):
"""
تست اتصال به سامانه مودیان (API v2).
اگر body ارسال شود، مقادیر فرم UI با تنظیمات ذخیره‌شده ادغام می‌شود
تا بدون «ذخیره» قبلی هم بتوان اتصال را آزمایش کرد.
"""
ensure_moadian_plugin_active(db, business_id)
from app.integrations.moadian.client import MoadianClient, uses_moadian_v2
from app.core.settings import get_settings
from app.services.tax_setting_health_service import run_extended_connection_test
stored = get_tax_setting(db, business_id)
if stored is None and payload is None:
raise ApiError(
"TAX_SETTINGS_NOT_CONFIGURED",
"تنظیمات سامانه مودیان یافت نشد.",
http_status=400,
)
tax_setting = merge_tax_setting_for_test(stored, payload, business_id=business_id)
missing = validate_tax_setting_complete(tax_setting)
if missing:
labels = {
"tax_memory_id": "شناسه حافظه مالیاتی",
"economic_code": "کد اقتصادی",
"private_key": "کلید خصوصی",
"certificate": "گواهی امضای الکترونیک (PEM)",
}
missing_fa = "، ".join(labels.get(f, f) for f in missing)
raise ApiError(
"TAX_SETTINGS_INCOMPLETE",
f"تنظیمات ناقص است. فیلدهای الزامی: {missing_fa}.",
http_status=400,
details={"missing_fields": missing, "api_mode": "v2" if uses_moadian_v2(tax_setting) else "v1"},
)
client = MoadianClient(settings=get_settings(), tax_setting=tax_setting)
try:
# 1. دریافت اطلاعات سرور
server_info = client.get_server_information()
# 2. تست لاگین + بررسی JWT، هشدارها، و سوابق 4103
token = client.login()
result = run_extended_connection_test(
db,
tax_setting,
token=token,
server_info=server_info if isinstance(server_info, dict) else {},
)
result["api_version"] = client.api_version
message_key = "TAX_CONNECTION_SUCCESS"
if result.get("status") == "identity_mismatch":
message_key = "TAX_CONNECTION_IDENTITY_MISMATCH"
elif result.get("status") == "connected_with_warnings":
message_key = "TAX_CONNECTION_WITH_WARNINGS"
return success_response(
data=result,
request=request,
message=message_key,
)
except ApiError:
raise
except Exception as exc:
raise ApiError(
"TAX_CONNECTION_FAILED",
f"خطا در اتصال به سامانه: {str(exc)}",
http_status=502,
details={"error": str(exc)},
) from exc
finally:
try:
client.close()
except Exception as close_error:
# لاگ می‌کنیم اما exception را propagate نمی‌کنیم
import logging
logger = logging.getLogger(__name__)
logger.warning(f"Error closing MoadianClient during test connection: {close_error}")
def _generate_rsa_key_pair() -> Tuple[str, str, rsa.RSAPrivateKey]:
key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
private_pem = key.private_bytes(
encoding=serialization.Encoding.PEM,
format=serialization.PrivateFormat.PKCS8,
encryption_algorithm=serialization.NoEncryption(),
).decode("utf-8")
public_pem = key.public_key().public_bytes(
encoding=serialization.Encoding.PEM,
format=serialization.PublicFormat.SubjectPublicKeyInfo,
).decode("utf-8")
return private_pem, public_pem, key