5.0 KiB
اتصال ته‌حساب (فاز ۱)
مرجع 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 |
لاگ جستجو/وارد کردن |
ProductAccountingLink |
لینک محصول ↔ نام کارساخته روی یک اتصال |
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(بازه کد یا لیست کدها) - sync محصولات/کارساخته:
POST /sync/products/search·POST /sync/products/import·POST /sync/products/import-bulk
تطبیق مشتری
- نرمال‌سازی موبایل →
DoListMoshtari-ByPhone - اگر خالی →
DoListMoshtari-ByName - اگر بیش از یک نتیجه → انتخاب دستی (لینک خودکار روی ابهام ممنوع)
- لینک دستی با کد · یا
DoNewMoshtari
انواع سند فاز ۱
| کلید CRM | متد ته‌حساب |
|---|---|
buy_sale_gold |
DoNewSanadBuySaleGOLD |
buy_sale_sekeh |
DoNewSanadBuySaleSEKEH |
talab_bedehi |
DoNewSanadTalabBedehi |
vkh_gold |
DoNewSanadVKHGOLD |
vkh_bank |
DoNewSanadVKHBank |
مانده: مسیر GetMandeHesabByCode با کلید body getmandehesabbycode (مثل همکار).
استقرار
INTEGRATIONS_ENCRYPTION_KEYرا روی سرور بگذارید (۶۴ کاراکتر hex).npx prisma migrate deployدرapps/api- rebuild API/web و restart PM2
وارد کردن مشتریان
افزودن اتصال به‌تنهایی مشتری را به CRM کپی نمی‌کند. از تنظیمات → ته‌حساب → وارد کردن مشتریان:
- بازهٔ کد (مثلاً ۱ تا ۵۰۰) را بزنید و «وارد کردن کل بازه»، یا
- با موبایل/نام/کد جستجو کنید و تکی/دسته‌ای وارد کنید.
مانده و اسناد بعد از لینک، در پروفایل شخص → تب دارایی دیده می‌شود.
وارد کردن کارساخته (محصولات)
از تنظیمات → ته‌حساب → وارد کردن کارساخته:
- اتصال را انتخاب و «دریافت لیست» بزنید (
DoListNameKarsakhte). - تکی، نتایج فیلترشده، یا همه را وارد کنید.
هر نام به‌عنوان Product با دستهٔ کارساخته ساخته و در ProductAccountingLink لینک می‌شود (عیار در تگ/توضیح). موجودی همچنان منبع حقیقت ته‌حساب است؛ این فقط کاتالوگ CRM برای معامله/فاکتور است.
در کسب‌وکارهای غیرطلا ممکن است همان لیست API با عنوان دیگری شناخته شود؛ فعلاً برچسب CRM «کارساخته» است.
چک‌لیست تست دستی
- افزودن اتصال + تست health
- افزودن اتصال دوم با DB دیگر؛ انتخاب پیش‌فرض
- وارد کردن بازه کد مشتریان + دیدن در اشخاص
- دریافت لیست کارساخته + وارد کردن تکی/دسته‌ای به محصولات
- تطبیق شخص با موبایل / لینک دستی / ثبت جدید
- نمایش مانده و جزئیات در تب دارایی
- لیست اسناد با بازه شمسی
- ثبت سند؛ retry با همان Factor_Code نباید سند تکراری بسازد
خارج از فاز ۱
push خودکار از معامله/فاکتور، RFID/اتیکت، PDF/Excel اسناد، ویرایش سند در ته‌حساب.