---
title: "API حسابداری برای برنامه‌نویسان: تمام دفاتر از طریق REST"
description: "API حسابداری حسابدار من: ثبت سند، مدیریت حساب‌ها و دریافت گزارش‌های مالی با REST؛ همراه کلید API زیر نظر مالک، کلید یکتاسازی و وب‌هوک امضاشده با HMAC."
canonical: https://hesabdar.my/developers
language: fa
publisher: "حسابدار من"
updated: 2026-11-05
---

# API حسابداری برای برنامه‌نویسان: تمام دفاتر از طریق REST

> API حسابداری حسابدار من: ثبت سند، مدیریت حساب‌ها و دریافت گزارش‌های مالی با REST؛ همراه کلید API زیر نظر مالک، کلید یکتاسازی و وب‌هوک امضاشده با HMAC.

API حسابداری حسابدار من هر کاری را که در داشبورد برای یک کسب‌وکار انجام می‌دهید در اختیار کد شما می‌گذارد: حساب‌ها، اسناد، سال‌های مالی، طرف‌حساب‌ها، نرخ ارز، گزارش‌های مالی، انبار و حسابداری صنعتی، بودجه و حسابداری مدیریت، وب‌هوک‌ها و ردپای حسابرسی. ورودی و خروجی JSON است و مستندات OpenAPI را می‌توانید همان‌جا در مرورگر امتحان کنید.

- **REST**: JSON روی HTTPS با مستندات OpenAPI
- **Bearer**: کلید API زیر نظر مالک
- **۱۲۰ در دقیقه**: سقف پیش‌فرض درخواست برای هر کلید
- **۱۶**: نوع رویداد وب‌هوک

هر کسب‌وکار کلیدهای خودش را دارد؛ کلید تعیین می‌کند با دفاتر کدام کسب‌وکار کار می‌کنید.

آدرس پایه

## از صفر تا ثبت اولین سند قطعی در سه قدم

### ساخت کلید

به‌عنوان مالک کسب‌وکار، در تنظیمات کسب‌وکار یک کلید API بسازید و دسترسی آن را انتخاب کنید: **فقط خواندن** یا **خواندن و نوشتن**. کلید را همان لحظه کپی کنید؛ متن کامل آن فقط یک بار نمایش داده می‌شود.

### یک درخواست خواندنی

درخواست `GET /accounts` را با هدر `Authorization: Bearer lgr_live_…` بفرستید. پاسخ، کدینگ حساب‌های آن کسب‌وکار است و هدرها سقف باقی‌مانده درخواست و موجودی اعتبار را نشان می‌دهند.

### ثبت سند

درخواست `POST /journal-entries` را با ردیف‌های تراز و هدر `Idempotency-Key` بفرستید. از کد یا شناسه حساب استفاده کنید؛ با `"status": "posted"` سند همان لحظه قطعی می‌شود و بدون آن به‌صورت موقت برای بازبینی می‌ماند.

## ثبت سند حسابداری با curl، جاوااسکریپت یا پایتون

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

خواندن حساب‌ها و گزارش‌ها

کپی

کپی شد

## کلید API که فقط مالک می‌سازد، عوض می‌کند و باطل می‌کند

کلید را به‌صورت توکن Bearer بفرستید: `Authorization: Bearer lgr_live_…`. هدر `X-API-Key` هم پذیرفته می‌شود. هر کلید متعلق به یک کسب‌وکار است؛ اتصال سه شرکت یعنی سه کلید، و لو رفتن یک کلید دفاتر شرکت‌های دیگر را در معرض خطر قرار نمی‌دهد.

کلیدی با دسترسی **خواندن** فقط می‌تواند مسیرهای خواندنی را فراخوانی کند و هر تغییری در داده به دسترسی **نوشتن** نیاز دارد؛ در غیر این صورت پاسخ `403` است. کلید می‌تواند تاریخ انقضا داشته باشد، چرخانده شود (کلید قبلی از کار می‌افتد و کلید تازه با همان تنظیمات صادر می‌شود) یا هر زمان باطل شود. هر درخواست با کلیدی که آن را فرستاده ثبت می‌شود.

| منبع | مسیرها | توضیح |
| --- | --- | --- |
| سال‌های مالی | `GET` `POST` `/fiscal-years`، `GET` `PUT` `DELETE` `/fiscal-years/{id}`، `POST /{id}/close`، `POST /{id}/reopen` | بستن سال، سند اختتامیه و افتتاحیه را صادر می‌کند |
| حساب‌ها | `/accounts` (CRUD)، `GET /accounts/{id}/balance`، `PUT /accounts/cost-behavior` | کدینگ حساب‌های سال مالی جاری؛ تعیین گروهی رفتار هزینه (ثابت، متغیر، نیمه‌متغیر) |
| طرف‌حساب‌ها | `/parties` (CRUD) | مشتریان و تأمین‌کنندگان |
| مراکز هزینه | `/cost-centers` (CRUD) | واحدها و شعب |
| پروژه‌ها | `/projects` (CRUD) | پروژه‌ها و قراردادها |
| انواع سند | `/voucher-types` (CRUD) | کدهایی مثل SAL، PUR، PAY |
| اسناد حسابداری | `/journal-entries` (CRUD)، `POST /bulk-post`، `POST /{id}/post`، `POST /{id}/reverse`، `POST /{id}/duplicate`، `/{id}/attachments` | سند موقت ویرایش می‌شود؛ سند قطعی با برگشت اصلاح می‌شود |
| نرخ ارز | `GET` `POST` `/exchange-rates`، `DELETE /exchange-rates/{id}` | وقتی سند نرخ مخصوص خودش را ندارد استفاده می‌شود |
| گزارش‌ها | `/reports/trial-balance`، `balance-sheet`، `income-statement`، `cash-flow`، `equity-changes`، `general-ledger`، `journal`، `party-balances`، `dashboard` | همان اعداد داشبورد |
| راه‌اندازی انبار | `GET` `POST` `DELETE` `/inventory/setup` | فعال یا غیرفعال کردن ماژول انبار و حسابداری صنعتی و نگاشت حساب‌های آن |
| اطلاعات پایه انبار | `/units`، `/warehouses`، `/item-categories`، `/items` (CRUD) | روش ارزیابی هر کالا: FIFO، میانگین موزون، استاندارد یا شناسایی ویژه |
| سری ساخت و سریال | `/lots` (CRUD)، `/inventory-reports/lot-balances`، `expiring-lots`، `lot-trace`، `serial-history` | تخصیص FEFO، ردیابی رو به عقب و رو به جلو |
| اسناد انبار | `/stock-documents` (CRUD)، `POST /{id}/post`، `POST /{id}/cancel` | رسید، برگشت، حواله، تحویل، انتقال، تعدیل، هزینه تکمیلی خرید، کاهش ارزش |
| انبارگردانی | `/stock-counts`، `POST /{id}/complete`، `POST /{id}/cancel` | تکمیل شمارش، سند تعدیل را قطعی می‌کند |
| گزارش‌های انبار | `/inventory-reports/on-hand`، `kardex`، `movement-summary`، `reconciliation`، `ageing`، `reorder` | تطبیق دفتر انبار با دفتر کل |
| تولید | `/boms` (CRUD)، `POST /boms/{id}/roll-up`، `/cost-center-rates`، `/production-orders` با `release`، `issue`، `receive`، `close`، `reopen`، `GET /{id}/cost-sheet` | هزینه‌یابی سفارش کار و محاسبه بهای استاندارد |
| دستمزد و سربار | `/labor-entries`، `/overhead-applications`، `/overhead-allocations`، `/overhead-closings` (با `preview`) | تسهیم مستقیم، یک‌طرفه و دوطرفه |
| هزینه‌یابی مرحله‌ای | `/process-runs` (CRUD)، `POST /{id}/post`، `POST /{id}/cancel` | واحدهای معادل، میانگین موزون یا FIFO |
| گزارش‌های بهای تمام‌شده | `/costing-reports/cogm`، `overhead`، `profitability`، `wip`، `variances` | بهای تمام‌شده کالای ساخته‌شده و فروش‌رفته، انحرافات |
| ضایعات و هزینه‌های مستقیم | `POST /production-orders/{id}/scrap`، `GET /production-scraps`، `POST /production-scraps/{id}/cancel`، `GET` `POST` `/direct-costs`، `POST /direct-costs/{id}/cancel` | ضایعات عادی و غیرعادی، پیمانکاری فرعی و سایر هزینه‌های مستقیم |
| برنامه‌ریزی | `GET` `POST` `/mrp`، `GET` `POST` `/capacity-load` | باز کردن فهرست مواد چندسطحی، پیشنهاد سفارش، مقایسه ساعت لازم با ظرفیت عادی |
| بودجه‌ها | `/budgets` (CRUD)، `PUT /{id}/lines`، `POST /{id}/lines/from-actuals`، `POST /{id}/lines/from-budget`، `POST /budgets/spread`، `POST /{id}/duplicate`، `approve`، `unapprove`، `archive`، `default`، `GET /budget-periods` | ردیف‌های ماهانه به تفکیک حساب، مرکز هزینه و پروژه |
| گزارش‌های بودجه | `GET /budgets/{id}/vs-actual`، `GET /budgets/{id}/flexible` | انحرافات به تفکیک بخش، حساب، مرکز هزینه، پروژه یا ماه |
| برنامه بودجه جامع | `/budget-plans` (CRUD)، `POST /{id}/compute`، `POST /{id}/generate-budget` | بودجه عملیاتی و نقدی، صورت سود و زیان بودجه‌ای |
| تحلیل‌های مدیریتی | `/management/cvp`، `variable-costing`، `segments`، `ratios` | نقطه سربه‌سر، تطبیق هزینه‌یابی جذبی، ROI و سود باقی‌مانده، ۱۹ نسبت مالی |
| تصمیم‌گیری و ABC | `POST /management/decisions/{type}`، `/abc-models` (CRUD)، `POST /abc-models/{id}/compute` | ساخت یا خرید، سفارش خاص، حذف یا ادامه، فروش یا پردازش بیشتر، عامل محدودکننده |
| وب‌هوک‌ها | `/webhooks` (CRUD)، `GET /{id}/deliveries`، `POST /{id}/test`، `POST /{id}/deliveries/{delivery}/redeliver` | امضاشده با HMAC SHA-256 |
| ردپای حسابرسی | `GET /audit-logs` | چه کسی، چه کاری، چه زمانی و از کجا |

## کلید یکتاسازی، خطاها، سقف درخواست و اعتبار

### کلید یکتاسازی (Idempotency)

هنگام ثبت سند هدر `Idempotency-Key` (یا فیلد `idempotency_key`) را بفرستید. تکرار درخواست با همان کلید، سند موجود را با کد وضعیت 200 به‌جای 201 برمی‌گرداند؛ قطع شدن شبکه هرگز یک فروش را دو بار ثبت نمی‌کند.

### ساختار واحد خطا

هر خطا یک `code` ماشینی، یک `message` فارسی یا انگلیسی (با `Accept-Language: fa`) و در خطای اعتبارسنجی، `errors` به تفکیک فیلد مثل `lines.0.debit` دارد.

### سقف درخواست

هر کلید به‌طور پیش‌فرض ۱۲۰ درخواست در دقیقه مجاز است. هدرهای `X-RateLimit-Limit` و `X-RateLimit-Remaining` را دنبال کنید؛ پاسخ `429` مقدار `retry_after` را به ثانیه دارد.

### اعتبار در هدرها

هر درخواست هزینه `api.call` را دارد و عملیات‌ها هزینه خودشان را اضافه می‌کنند، مثل `entry.create`. هدرهای `X-Credits-Charged` و `X-Credits-Balance` هزینه و مانده را نشان می‌دهند؛ پاسخ `402` یعنی اعتبار تمام شده است.

نمونه خطا

- کد وضعیت
- معنا

- 401
- کلید API ارسال نشده، نامعتبر، منقضی یا باطل‌شده است

- 402
- اعتبار کافی نیست (`insufficient_credits`)

- 403
- کلید دسترسی `write` یا مجوز لازم را ندارد

- 404
- این منبع در این کسب‌وکار وجود ندارد

- 409
- با وضعیت فعلی در تضاد است، مثل ویرایش سند قطعی یا ثبت در سال بسته‌شده

- 422
- اعتبارسنجی ناموفق بود؛ `errors` را به تفکیک فیلد ببینید

- 423
- کسب‌وکار یا حساب مالک تعلیق شده است

- 429
- سقف درخواست پر شده؛ پس از `retry_after` ثانیه دوباره تلاش کنید

## وب‌هوک امضاشده برای اسناد، حساب‌ها، طرف‌حساب‌ها، سال‌های مالی و انبار

یک آدرس را برای رویدادهای موردنیازتان ثبت کنید تا حسابدار من برای هر رویداد یک درخواست JSON از نوع `POST` بفرستد. هر ارسال هدرهای `X-Webhook-Event`، شناسه یکتای `X-Webhook-Delivery`، `X-Webhook-Timestamp` و `X-Webhook-Signature` را دارد.

امضا عبارت `sha256=` و پس از آن HMAC SHA-256 رشته `timestamp + "." + raw_body` با کلید مخفی وب‌هوک شماست. ارسال‌های ناموفق تا ۵ بار با فاصله رو‌به‌افزایش (از ۳۰ ثانیه تا ۳۰ دقیقه) تکرار می‌شوند و می‌توانید از طریق API آن‌ها را ببینید، آزمایش کنید و دوباره بفرستید.

رویدادها

- entry.created
- entry.updated
- entry.posted
- entry.reversed
- entry.deleted
- account.created
- account.updated
- account.deleted
- fiscal_year.created
- fiscal_year.closed
- party.created
- party.updated
- stock_document.posted
- stock_document.cancelled
- production_order.closed
- costing.run_posted

بررسی امضا

یک نمونه ارسال

## پرسش‌های رایج درباره API حسابداری

### آیا می‌توانم API حسابداری را رایگان امتحان کنم؟

بله. حساب‌های جدید اعتبار رایگان می‌گیرند. یک کسب‌وکار بسازید، کلید تولید کنید و API را فراخوانی کنید؛ هر درخواست مقدار کمی اعتبار مصرف می‌کند که در هدر `X-Credits-Charged` می‌بینید.

### آیا یک کلید API به چند کسب‌وکار دسترسی دارد؟

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

### سند قطعی را چطور با API اصلاح کنم؟

مسیر `POST /journal-entries/{id}/reverse` را فراخوانی کنید. حسابدار من سند برگشتی قطعی با جابه‌جایی بدهکار و بستانکار می‌سازد و سند اصلی را برگشت‌خورده علامت می‌زند. سپس سند درست را ثبت کنید.

### آیا API از سند ارزی پشتیبانی می‌کند؟

بله. `currency_code` و `exchange_rate` را روی سند بفرستید، یا نرخ را نفرستید تا آخرین نرخ ذخیره‌شده در `/exchange-rates` استفاده شود.

### مستندات کامل مسیرها کجاست؟

مستندات مرجع OpenAPI با Scalar در api.hesabdar.my/docs/api است. برای آموزش گام‌به‌گام با مثال، [راهنمای API حسابداری](https://hesabdar.my/guides/accounting-api) را بخوانید.