رابط برنامه‌نویسی سبزحساب

از کجا شروع کنید

کل این صفحه یک قرارداد را توضیح می‌دهد، و همان قرارداد به شکل ماشین‌خوان هم منتشر می‌شود: OpenAPI 3.1 روی /v1/openapi.json. هر سه SDK رسمی از همان فایل تولید می‌شوند، پس سند و کد نمی‌توانند از هم جدا بیفتند.

آموزش گام‌به‌گام — وصل کردن یک فروشگاه

سناریو ساده است: فروشگاه اینترنتی دارید و می‌خواهید هر سفارش تأییدشده خودش در سبزحساب فاکتور و سند بخورد، موجودی انبار به فروشگاه برگردد، و اگر چکی برگشت خورد خبردار شوید.

1. توکن بگیرید

   در پنل بروید به تنظیمات ← رابط برنامه‌نویسی ← توکن تازه. اختیارات لازم همین سناریو اینهاست: sales:write items:read inventory:read contacts:write webhooks:manage

   بیشتر از این نگیرید. توکنی که اختیار حسابداری دارد و لازمش ندارد، فقط دامنه خرابی را بزرگ می‌کند.

   🔴

   توکن فقط یک بار نشان داده می‌شود. ما خودمان هم بعدش نمی‌توانیم بخوانیمش، چون هش argon2id ذخیره می‌شود. اگر گمش کردید باید باطل کنید و تازه بسازید — این یک محدودیت نیست، تنها شکل درست نگه داشتن کلیدی است که به دفتر مالی شما وصل است.

2. اتصال را بسنجید

   اولین تماس هر اتصالی باید /v1/me باشد. با یک درخواست، اختیارات توکن، طرح اشتراک، سقف‌ها و سال مالی باز را یک‌جا می‌گیرید.

   bash کپی

   curl -s https://api.sabzhesab.com/v1/me \
     -H "Authorization: Bearer shk_live_7Qx9..."

   json کپی

   {
     "business": { "id": 41, "name": "نادی‌کالا" },
     "token": {
       "name": "کانکتور فروشگاه",
       "scopes": ["sales:write", "items:read", "inventory:read"],
       "expires_at": "2027-09-30",
       "mode": "live"
     },
     "plan": { "key": "multichannel", "name": "چندکاناله" },
     "limits": {
       "requests_per_minute": 600,
       "invoices_per_month": 2000,
       "invoices_used_this_month": 318
     },
     "fiscal_year": {
       "id": 7, "label": "۱۴۰۵",
       "from": "2026-03-21", "to": "2027-03-20",
       "status": "open"
     }
   }

   اگر fiscal_year خالی برگشت، هیچ سال مالی بازی نیست و هر تلاشی برای ثبت سند 422 fiscal_year_missing می‌گیرد. این را همین گام اول ببینید، نه وسط شب و وسط صد سفارش.

3. کالاها را نگاشت کنید

   فروشگاه شما SKU دارد، سبزحساب کد کالا. برای اینکه مجبور نباشید نقشه شناسه‌ها را جایی نگه دارید، هر کالا یک external_id می‌گیرد — و از آن به بعد با همان صدایش می‌زنید.

   http کپی

   POST /v1/items/batch
   Authorization: Bearer shk_live_7Qx9...
   Idempotency-Key: items-sync-1405-07-11
   
   {
     "items": [
       { "external_id": "SKU-4410", "name": "کیف چرم دستی",
         "kind": "stock", "unit": "عدد",
         "sell_price": "1850000.0000", "tax_rate": "10.00",
         "barcode": "6260100441012" }
     ]
   }

   بعدش موجودی را یک‌جا بخوانید — نه کالا به کالا. هر فروشگاهی این را هر چند دقیقه می‌پرسد و یک درخواست به‌جای سیصد درخواست، تفاوت بین ماندن و خوردن به سقف نرخ است:

   http کپی

   GET /v1/items/stock?external_ids=SKU-4410,SKU-4411&warehouse_id=3

4. سفارش را فاکتور کنید

   این گام قلب اتصال است. سه چیز در آن هست که کار را ساده می‌کند: طرف حساب را لازم نیست از قبل بسازید، تاریخ را می‌توانید شمسی بفرستید، و شماره سفارش خودتان نقش Idempotency-Key را بازی می‌کند.

   http کپی

   POST /v1/sales-invoices
   Authorization: Bearer shk_live_7Qx9...
   Idempotency-Key: ord-SHOP-884512
   Content-Type: application/json
   
   {
     "external_id": "SHOP-884512",
     "date": "1405-07-11",
     "date_calendar": "jalali",
     "contact": {
       "external_id": "shop-user-77231",
       "name": "مریم رضایی",
       "mobile": "09120000000"
     },
     "channel": "webshop",
     "warehouse_id": 3,
     "status": "posted",
     "lines": [
       { "item": { "external_id": "SKU-4410" },
         "quantity": "2.0000",
         "unit_price": "1850000.0000",
         "discount": "0.0000",
         "tax_rate": "10.00" }
     ],
     "charges": [
       { "kind": "freight", "title": "هزینه ارسال",
         "amount": "450000.0000" }
     ]
   }

   json · 201 Created کپی

   {
     "id": 9931,
     "number": "1405-0442",
     "external_id": "SHOP-884512",
     "date": "2026-10-03",
     "status": "posted",
     "subtotal":       "3700000.0000",
     "discount_total":       "0.0000",
     "tax_total":       "370000.0000",
     "charges_total":   "450000.0000",
     "total":          "4520000.0000",
     "paid":                 "0.0000",
     "due":            "4520000.0000",
     "contact": { "id": 1182, "code": "1001-0344", "name": "مریم رضایی" },
     "journal_entry": { "id": 20451, "number": 1288, "status": "posted" },
     "moadian": { "status": "not_sent", "tax_id": null },
     "links": {
       "self": "/v1/sales-invoices/9931",
       "pdf":  "/v1/sales-invoices/9931/pdf"
     }
   }

   ✓

   contact را جای contact_id فرستادیم. اگر آن external_id قبلا دیده نشده باشد طرف حساب ساخته می‌شود، و اگر دیده شده باشد همان به کار می‌رود. کانکتور شما نیازی ندارد اول طرف حساب بسازد و شناسه‌اش را نگه دارد.

   🔴

   status: "posted" یعنی سند حسابداری همان لحظه خورد — و از آن لحظه فاکتور تغییرناپذیر است. PATCH رویش 409 document_posted می‌گیرد.

   اگر می‌خواهید بعدا ویرایشش کنید، "draft" بفرستید و وقتی سفارش قطعی شد POST /v1/sales-invoices/{id}/post بزنید. اصلاح فاکتور ثبت‌شده فقط با سند جدید انجام می‌شود: برگشت از فروش، یا سند برگشتی.

5. وبهوک را ثبت کنید

   تا اینجا شما به سبزحساب حرف زدید. این گام برعکسش است: سبزحساب به شما خبر می‌دهد. بدون این، مجبورید هر چند دقیقه بپرسید «چیزی عوض شد؟» — و همان چیزی است که سقف نرخ را می‌خورد.

   http کپی

   POST /v1/webhooks
   
   {
     "url": "https://shop.example.ir/hooks/sabzhesab",
     "events": ["sales_invoice.paid", "cheque.bounced", "stock.low"]
   }

   پاسخ یک secret دارد که فقط همان یک بار می‌آید. با آن امضای هر پیام را بسنجید:

   php کپی

   $raw       = file_get_contents('php://input');
   $timestamp = $_SERVER['HTTP_SABZHESAB_TIMESTAMP'] ?? '';
   $signature = $_SERVER['HTTP_SABZHESAB_SIGNATURE'] ?? '';
   
   $expected = 'v1='.hash_hmac('sha256', $timestamp.'.'.$raw, $secret);
   
   // مقایسه زمان‌ثابت — هرگز با === مقایسه نکنید
   if (! hash_equals($expected, $signature)) {
       http_response_code(401);
       exit;
   }
   
   // پنجره ۵ دقیقه، تا پیام ضبط‌شده دوباره پخش نشود
   if (abs(time() - (int) $timestamp) > 300) {
       http_response_code(401);
       exit;
   }
   
   // فوری ۲۰۰ بدهید و کار را به صف خودتان بیندازید
   http_response_code(200);

   🔴

   hash_equals و نه ===. مقایسه رشته‌ای معمولی در اولین نویسه متفاوت برمی‌گردد، و از همین اختلاف زمان می‌شود امضا را حرف‌به‌حرف حدس زد.

   و مقصد باید در ۵ ثانیه پاسخ بدهد. اگر کار سنگینی دارید، فوری ۲۰۰ بدهید و بعد انجامش دهید — وگرنه ما تلاش را ناموفق می‌شماریم و دوباره می‌فرستیم.

همین پنج گام یک اتصال کامل است. اگر نمی‌خواهید منطق حسابداری را بدانید، راه کوتاه‌تری هم هست: POST /v1/external-orders سفارش خام را می‌گیرد و سبزحساب خودش طرف حساب، فاکتور، سند و حواله انبار را می‌سازد.

نشانی و قالب

مستأجر هرگز پارامتر نیست

پول

{ "amount": "125000.0000", "currency": "IRR" }

چرا رشته و نه عدد: JSON.parse("125000.0001") در جاوااسکریپت یک double می‌دهد، و double در حسابداری ریال ایران — جایی که مبالغ به‌سادگی از دو به توان پنجاه‌وسه عبور می‌کنند — ریال گم می‌کند. یک ریال گم‌شده در یک سند، یک سند ناتراز است.

تومان در API وجود ندارد. تومان لایه نمایش است؛ اگر رابط شما تومان نشان می‌دهد، تقسیم بر ۱۰ کار خودتان است. ما هیچ‌جا حدس نمی‌زنیم که عدد فرستاده‌شده ریال بود یا تومان.

تاریخ

ذخیره و تبادل: میلادی ISO 8601. نمایش شمسی کار سمت شماست.

{ "date": "2026-10-03", "created_at": "2026-10-03T14:22:11+03:30" }

ولی هر مسیری که تاریخ می‌گیرد، شمسی را هم می‌پذیرد — به شرط اینکه صریح علامت بخورد:

{ "date": "1405-07-11", "date_calendar": "jalali" }

شناسه بیرونی

هر منبع یک میدان external_id دارد: رشته آزاد، یکتا در دامنه خودش. شناسه سفارش فروشگاه، شناسه کاربر، SKU — هر چیزی که در سیستم خودتان کلید است، اینجا می‌نشیند.

GET /v1/sales-invoices?external_id=SHOP-884512

نتیجه‌اش این است که لازم نیست جدول نگاشت شناسه‌ها را خودتان نگه دارید. هر جا contact_id یا item_id می‌پذیریم، یک شی با external_id هم می‌پذیریم.

تضمین یک‌بار

Idempotency-Key: ord-SHOP-884512

کلید ۲۴ ساعت نگه داشته می‌شود. این سخت‌گیری عمدی است: مشکل شماره یک هر کانکتوری در دنیا این است که یک سفارش دو بار سند می‌خورد — و سند دوم را کسی تا پایان سال مالی نمی‌بیند.

صفحه‌بندی و صافی

مکان‌نما، نه skip:

GET /v1/sales-invoices?limit=50&cursor=eyJpZCI6MTg4MiwiZCI6IjIwMjYtMTAtMDEifQ

{
  "data": [ ... ],
  "meta": {
    "limit": 50,
    "has_more": true,
    "next_cursor": "eyJpZCI6MTkzMiwiZCI6IjIwMjYtMDktMjgifQ"
  }
}

limit پیش‌فرض ۵۰، سقف ۲۰۰.

صافی

?updated_after=2026-09-01T00:00:00%2B03:30
?status=posted&contact_id=1182
?from=2026-07-01&to=2026-09-30
?sort=-date,number

updated_after ستون فقرات هر همگام‌سازی است: هر کانکتوری باید بتواند بپرسد «از آخرین بار چه عوض شد» — و این تنها راهی است که اتصال شما بدون خواندن کل دفتر، تازه بماند.

خطاها

{
  "error": {
    "code": "document_posted",
    "message": "سند ثبت‌شده تغییر نمی‌کند. برای اصلاح، سند برگشتی بزنید.",
    "message_en": "A posted document is immutable. Issue a reversing entry instead.",
    "field": null,
    "doc": "https://sabzhesab.com/docs/api#err-document_posted",
    "request_id": "req_01JA8X7KQ3M2"
  }
}

هر خطا دوزبانه است، و doc به بخش توضیح همان خطا در این صفحه لینک می‌دهد. request_id را در گزارش به پشتیبانی بفرستید؛ با آن دقیقا همان درخواست را پیدا می‌کنیم.

کدهای HTTP

کدهای خطای دامنه

توکن شخصی (PAT)

راه پیش‌فرض، و برای اتصال خودتان به دفتر خودتان همین درست است. در پنل: تنظیمات ← رابط برنامه‌نویسی ← توکن تازه.

Authorization: Bearer shk_live_7Qx9...

پیشوند معنا دارد:

اینکه از روی خود رشته بشود فهمید کدام است، یک اشتباه رایج را می‌بندد: توکن تولید که اشتباهی در فایل تست جا مانده.

هر توکن اینها را دارد: عنوان، فهرست اختیارات، تاریخ انقضا (پیش‌فرض یک سال)، و فهرست IP مجاز (اختیاری).

OAuth2

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

authorization_code با PKCE:

GET  /v1/oauth/authorize
       ?client_id=...
       &redirect_uri=https://plugin.example.ir/callback
       &scope=sales:write items:read
       &code_challenge=...&code_challenge_method=S256
       &state=...

POST /v1/oauth/token      # grant_type=authorization_code
POST /v1/oauth/token      # grant_type=refresh_token
POST /v1/oauth/revoke

اختیارات

اختیارات دقیقا همان دامنه‌های دسترسی داخل پنل‌اند. یک مدل مجوز، دو مخاطب — پس API هیچ‌وقت چیزی را اجازه نمی‌دهد که رابط کاربری نمی‌دهد.

سقف نرخ و طرح

هدرها روی هر پاسخ:

RateLimit-Limit: 600
RateLimit-Remaining: 584
RateLimit-Reset: 37
Retry-After: 37          # فقط روی ۴۲۹

گزارش‌های سنگین (ترازآزمایشی، ترازنامه، سود و زیان) سقف جداگانه دارند: ۱۰ در دقیقه. در عوض تعهدشان این است که ترازآزمایشی روی صد هزار سند زیر دو ثانیه برگردد.

جعبه‌شن

https://sandbox.sabzhesab.com/v1 — یک کسب‌وکار آزمایشی با کدینگ ایرانی و داده نمونه. هر شب از نو ساخته می‌شود.

• بدون سقف نرخ سخت — حلقه بزنید و خطا بسازید.
• استعلام هزینه ندارد و داده ثابت برمی‌گرداند.
• ارسال به مؤدیان شبیه‌سازی می‌شود و به سامانه واقعی نمی‌رود.
• وبهوک‌ها واقعا فرستاده می‌شوند، پس امضا را همین‌جا بسنجید.

مسیرها — شناخت و فراداده

قاعده کلی هر منبع: GET فهرست · POST ساخت · GET /{id} یک رکورد · PATCH اصلاح · DELETE حذف. استثناها در جدول‌ها علامت خورده‌اند.

طرف حساب

میدان‌ها

id · external_id · code · name · kind · is_customer · is_vendor · national_code · economic_code · registration_number · tax_type · phone · mobile · email · province · city · address · postal_code · credit_limit · opening_balance · group_id · labels · custom_fields · note · active · created_at · updated_at

کالا و خدمات

میدان‌ها

id · external_id · code · name · kind · barcode · unit · sub_unit · conversion_factor · buy_price · sell_price · price_lists · tax_code · tax_rate · group_id · track_stock · track_serial · reorder_point · variants · labels · custom_fields · active

tax_code همان شناسه کالای سامانه مؤدیان است. اگر قرار است فاکتورهایتان به مؤدیان برود، این میدان را خالی نگذارید — وگرنه ارسال در همان سامانه رد می‌شود، نه اینجا.

فروش

نمونه کامل ساخت فاکتور، همراه توضیح هر میدان، در آموزش گام‌به‌گام گام چهارم است.

خرید

انبار

/v1/stock-ledger کاردکس است: هر ورود و خروج با بهای تمام‌شده. اینجا جایی است که بهایابی موجودی منفی دیده می‌شود — اگر کالایی منفی رفته و بعد رسید خورده، سند اصلاح بهای تمام‌شده در همین دفتر ظاهر می‌شود.

خزانه

POST /v1/cheques/{id}/act رویدادهای چرخه چک را می‌گیرد: deposit · clear · bounce · transfer · return · cancel.

حسابداری

کدینگ چهارسطحی

کدینگ ایرانی چهار سطح دارد: گروه، کل، معین، تفصیلی. سند فقط روی سطح آخر می‌نشیند.

{
  "data": [
    {
      "id": 2041,
      "code": "1101-01-0007",
      "name": "بانک ملت — جاری ۱۲۳",
      "level": "detail",
      "level_number": 4,
      "parent_id": 118,
      "path": "1/11/1101/1101-01-0007",
      "nature": "debit",
      "kind": "asset",
      "dimension_types": ["project"],
      "postable": true
    }
  ]
}

سند دستی

{
  "date": "2026-10-03",
  "description": "تسعیر ارز پایان مهر",
  "lines": [
    {
      "account_id": 2041,
      "debit":  "48500000.0000",
      "credit":        "0.0000",
      "description": "سود تسعیر",
      "dimensions": { "project": 14 }
    },
    {
      "account_id": 3310,
      "debit":         "0.0000",
      "credit": "48500000.0000"
    }
  ]
}

گزارش

همه گزارش‌ها reports:read می‌خواهند، Accept: text/csv هم می‌پذیرند، و سقف نرخشان ۱۰ در دقیقه است.

مالیات و مؤدیان

حقوق و دستمزد

insurance-file فایل لیست بیمه تأمین اجتماعی را با فرمت خود سازمان می‌دهد — آماده بارگذاری، بدون تبدیل دستی.

استعلام پولی

هر پاسخ cost و credit_remaining دارد، پس هزینه را همان‌جا می‌بینید. GET /v1/inquiries/credit اعتبار را بدون خرج کردن می‌دهد.

پیوست و بایگانی

multipart/form-data با attachable_type و attachable_id. سقف ۲۰ مگابایت.

کانکتور و مارکت‌پلیس

دو راه برای وصل کردن یک فروشگاه

/v1/settlements تسویه مارکت‌پلیس را می‌گیرد، و variances مغایرت را نشان می‌دهد. مبلغ واریزی مارکت‌پلیس هیچ‌وقت با جمع فاکتورها برابر نیست — کمیسیون، جریمه و مرجوعی وسط است — و پیدا کردن همان اختلاف، کاری است که دستی روزها وقت می‌برد.

وبهوک

هدرهای هر پیام

SabzHesab-Event: sales_invoice.posted
SabzHesab-Delivery: dlv_01JA8X7KQ3M2
SabzHesab-Timestamp: 1791038531
SabzHesab-Signature: v1=5f4dcc3b5aa765d61d8327deb882cf99

امضا HMAC-SHA256 روی رشته timestamp + "." + raw_body با secret است. نمونه کد سنجش امضا در آموزش گام پنجم است.

تلاش مجدد

روی هر پاسخ غیر 2xx: هشت بار با عقب‌نشینی نمایی — ۱۰ ثانیه، ۳۰ ثانیه، ۲ دقیقه، ۱۰ دقیقه، ۳۰ دقیقه، ۲ ساعت، ۶ ساعت، ۲۴ ساعت. بعدش وبهوک خودکار غیرفعال می‌شود و ایمیل اطلاع می‌رود.

فهرست رویدادها

نسخه‌بندی

• نسخه در مسیر است: /v1/. هیچ نسخه‌ای در هدر پنهان نمی‌شود، چون نسخه پنهان یعنی توسعه‌دهنده نمی‌داند با کدام قرارداد حرف می‌زند.
• تغییر ناشکننده (میدان تازه، مقدار تازه در فهرستی که مستند شده باز است، مسیر تازه) بدون نسخه جدید می‌آید. مشتری شما باید میدان ناشناخته را نادیده بگیرد.
• تغییر شکننده (حذف یا تغییر نام میدان، تغییر نوع، سخت‌تر شدن اعتبارسنجی) نسخه تازه می‌خواهد.
• نسخه قدیم حداقل ۱۲ ماه پس از اعلام نسخه تازه زنده می‌ماند، با هدر Sunset و تاریخ دقیق.

SDK

هر سه SDK از همان openapi.json تولید می‌شوند — یعنی سند و کد نمی‌توانند از هم جدا بیفتند. افزونه ووکامرس بدون یک خط کد از پنل وردپرس کار می‌کند.