crm/docs/integrations/tahesab.md

اتصال ته‌حساب (فاز ۱)

مرجع API: Tahesab API Reference · OpenAPI: docs/integrations/tahesab-openapi.json

اصول

• هر سازمان می‌تواند چند اتصال داشته باشد (baseUrl + token + dbName).
• توکن با AES-256-GCM و کلید محیطی INTEGRATIONS_ENCRYPTION_KEY رمز می‌شود و هرگز کامل به فرانت برنمی‌گردد.
• مانده و اسناد: منبع حقیقت ته‌حساب است؛ CRM فقط cache و لینک نگه می‌دارد.
• ثبت سند فقط از فرم اختصاصی تب دارایی با Factor_Code یکتا (≥۲۰ کاراکتر) و جدول AccountingDocumentLog (idempotent).

مدل‌ها

مدل	نقش
AccountingConnection	اتصال چند-DB
PersonAccountingLink	لینک شخص ↔ moshtariCode روی یک اتصال
AccountingDocumentLog	لاگ push سند
AccountingBalanceCache	cache مانده
AccountingSyncJob	لاگ جستجو/وارد کردن

APIهای CRM

پیشوند: /api/integrations/tahesab

• اتصالات (owner/admin): GET/POST/PATCH/DELETE /connections · POST /connections/:id/test
• لیست عمومی اتصالات: GET /connections/public
• لینک شخص: GET/POST .../people/:id/links · DELETE .../links/:connectionId
• تطبیق: POST .../people/:id/match · ثبت: POST .../create-in-tahesab
• دارایی: GET .../people/:id/assets · اسناد: GET .../people/:id/asnad
• ثبت سند: POST .../people/:id/sanad
• sync دوطرفه: POST /sync/search · POST /sync/import · POST /sync/import-bulk (بازه کد یا لیست کدها)

تطبیق مشتری

1. نرمال‌سازی موبایل → DoListMoshtari-ByPhone
2. اگر خالی → DoListMoshtari-ByName
3. اگر بیش از یک نتیجه → انتخاب دستی (لینک خودکار روی ابهام ممنوع)
4. لینک دستی با کد · یا DoNewMoshtari

انواع سند فاز ۱

کلید CRM	متد ته‌حساب
buy_sale_gold	DoNewSanadBuySaleGOLD
buy_sale_sekeh	DoNewSanadBuySaleSEKEH
talab_bedehi	DoNewSanadTalabBedehi
vkh_gold	DoNewSanadVKHGOLD
vkh_bank	DoNewSanadVKHBank

مانده: مسیر GetMandeHesabByCode با کلید body getmandehesabbycode (مثل همکار).

استقرار

1. INTEGRATIONS_ENCRYPTION_KEY را روی سرور بگذارید (۶۴ کاراکتر hex).
2. npx prisma migrate deploy در apps/api
3. rebuild API/web و restart PM2

وارد کردن مشتریان

افزودن اتصال به‌تنهایی مشتری را به CRM کپی نمی‌کند. از تنظیمات → ته‌حساب → وارد کردن مشتریان:

1. بازهٔ کد (مثلاً ۱ تا ۵۰۰) را بزنید و «وارد کردن کل بازه»، یا
2. با موبایل/نام/کد جستجو کنید و تکی/دسته‌ای وارد کنید.

مانده و اسناد بعد از لینک، در پروفایل شخص → تب دارایی دیده می‌شود.

چک‌لیست تست دستی

• افزودن اتصال + تست health
• افزودن اتصال دوم با DB دیگر؛ انتخاب پیش‌فرض
• وارد کردن بازه کد مشتریان + دیدن در اشخاص
• تطبیق شخص با موبایل / لینک دستی / ثبت جدید
• نمایش مانده و جزئیات در تب دارایی
• لیست اسناد با بازه شمسی
• ثبت سند؛ retry با همان Factor_Code نباید سند تکراری بسازد

خارج از فاز ۱

push خودکار از معامله/فاکتور، RFID/اتیکت، PDF/Excel اسناد، ویرایش سند در ته‌حساب.