API حسابداری: ثبت خودکار سند از فروشگاه اینترنتی و نرم‌افزار فروش

API حسابداری مجموعه‌ای از آدرس‌های HTTPS است که به نرم‌افزار (نه انسان) اجازه می‌دهد معاملات را در دفتر کل ثبت کند. فروشگاه اینترنتی هر سفارش پرداخت‌شده را به‌صورت سند می‌فرستد، ERP فاکتورهای خرید را ثبت می‌کند و ابزار گزارش‌گیری هر شب تراز آزمایشی را می‌خواند. هیچ‌کس چیزی را دوباره تایپ نمی‌کند و دفاتر همیشه به‌روزند.

این راهنما وب سرویس حسابداری Ledgeriano را از نگاه برنامه‌نویس توضیح می‌دهد: احراز هویت، اولین سند قطعی با curl و جاوااسکریپت، کلید یکتایی، مدیریت خطا، وب‌هوک، گزارش‌ها و چک‌لیست آزمایش. مرجع کامل در api.ledgeriano.com/docs/api است و خلاصه آن را در صفحه توسعه‌دهندگان می‌بینید.

#چرا ثبت سند را با API خودکار کنیم؟

خودکارسازی، کندترین و پرخطاترین مرحله حسابداری شرکت‌های کوچک را حذف می‌کند: کپی کردن جمع‌ها از یک سیستم به سیستم دیگر. فروشگاهی با ۴۰۰ سفارش در ماه که هر هفته خروجی اکسل می‌گیرد، معمولاً ماهانه ۳ تا ۵ ساعت صرف ورود، اصلاح و تطبیق اطلاعات می‌کند. با اتصال فروشگاه اینترنتی به حسابداری از طریق API، هر سفارش همان لحظه پرداخت به سند تبدیل می‌شود.

کاربردهای رایج:

• فروشگاه اینترنتی: یک سند فروش برای هر سفارش پرداخت‌شده (یا یک سند خلاصه در روز).
• ERP یا نرم‌افزار انبار: فاکتور خرید، رسید انبار و بهای تمام‌شده.
• درگاه پرداخت: کارمزد و تسویه به حساب بانکی.
• نرم‌افزار حقوق و دستمزد: یک سند حقوق در ماه.
• داشبوردهای داخلی: دسترسی فقط‌خواندنی به مانده‌ها و گزارش‌ها.

#احراز هویت با کلید API

هر کسب‌وکار کلیدهای API خودش را دارد و هر کلید فقط همان کسب‌وکار را می‌بیند. مالک کسب‌وکار کلیدها را در داشبورد (کسب‌وکار، بخش کلیدهای API) می‌سازد، تعویض یا باطل می‌کند. کلید کامل فقط یک بار، هنگام ساخت یا تعویض، نمایش داده می‌شود؛ پس فوراً آن را در محل امن ذخیره کنید.

کلید را به‌صورت Bearer بفرستید:

Authorization: Bearer lgr_live_xxxxxxxxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

سرآیند X-API-Key هم پذیرفته می‌شود.

#سطح دسترسی read و write

هر کلید یکی از این دو سطح را دارد:

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

پیام‌های خطا به‌طور پیش‌فرض انگلیسی‌اند. با ارسال Accept-Language: fa آن‌ها را فارسی دریافت کنید.

#اولین سند: ثبت سند قطعی با curl

هر سند حسابداری به تاریخ، شرح و دست‌کم دو ردیف نیاز دارد که جمع بدهکار و بستانکارشان برابر باشد. مثال ما سفارش شماره ۱۰۴۵ یک فروشگاه اینترنتی ایرانی است: کالا به مبلغ ۱۰۰٬۰۰۰٬۰۰۰ ریال به‌علاوه ۱۰ درصد مالیات بر ارزش افزوده، که از درگاه به حساب بانکی اصلی واریز شده. کدها از قالب استانداردهای حسابداری ایران است (۱۱۰۳ بانک، ۶۱۰۱ فروش کالا، ۳۲۰۵ مالیات و عوارض ارزش افزوده فروش).

curl -X POST https://api.ledgeriano.com/api/v1/journal-entries \
  -H "Authorization: Bearer $LEDGERIANO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Accept-Language: fa" \
  -H "Idempotency-Key: shop-order-1045" \
  -d '{
    "entry_date": "2026-09-14",
    "voucher_type": "SAL",
    "reference": "ORDER-1045",
    "description": "فروش اینترنتی سفارش ۱۰۴۵",
    "status": "posted",
    "tags": ["shop"],
    "lines": [
      { "account_code": "1103", "debit": 110000000, "description": "واریز درگاه پرداخت" },
      { "account_code": "6101", "credit": 100000000, "description": "فروش کالا" },
      { "account_code": "3205", "credit": 10000000, "description": "مالیات بر ارزش افزوده ۱۰٪" }
    ]
  }'

تاریخ در API به‌صورت میلادی (YYYY-MM-DD) ارسال می‌شود؛ ۲۰۲۶/۰۹/۱۴ برابر ۲۳ شهریور ۱۴۰۵ است و در داشبورد فارسی با تقویم شمسی نمایش داده می‌شود. سند جدید با وضعیت 201 Created برمی‌گردد و در data شناسه، شماره سند، وضعیت، جمع‌ها، منبع (api) و ردیف‌ها را دارد. سند قطعی از همین لحظه غیرقابل ویرایش است. اگر status را نفرستید (یا "draft" بفرستید)، سند موقت ساخته می‌شود که با PUT /journal-entries/{id} ویرایش و بعداً با POST /journal-entries/{id}/post قطعی می‌شود.

#همین درخواست با جاوااسکریپت

const res = await fetch("https://api.ledgeriano.com/api/v1/journal-entries", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.LEDGERIANO_API_KEY,
    "Content-Type": "application/json",
    Accept: "application/json",
    "Accept-Language": "fa",
    "Idempotency-Key": "shop-order-" + order.id,
  },
  body: JSON.stringify({
    entry_date: order.paidAt.slice(0, 10),
    voucher_type: "SAL",
    reference: "ORDER-" + order.id,
    description: "فروش اینترنتی سفارش " + order.id,
    status: "posted",
    lines: [
      { account_code: "1103", debit: order.total },
      { account_code: "6101", credit: order.net },
      { account_code: "3205", credit: order.vat },
    ],
  }),
});

const body = await res.json();
if (!res.ok) throw new Error(body.code + ": " + body.message);
console.log("سند ثبت شد:", body.data.number);

گرد کردن مبالغ را در فروشگاه انجام دهید، نه در حسابداری. اگر net + vat دقیقاً با total برابر نباشد، API سند را نامتوازن رد می‌کند و این دقیقاً رفتاری است که می‌خواهید.

#کلید یکتایی (Idempotency-Key): تکرار امن بدون سند تکراری

کلید یکتایی رشته‌ای منحصربه‌فرد است که همراه درخواست ساخت سند می‌فرستید تا تکرار همان درخواست هرگز سند دوم نسازد. شبکه قطع می‌شود و تایم‌اوت به شما نمی‌گوید سند ذخیره شده یا نه. با Idempotency-Key: shop-order-1045، درخواست تکراری سند موجود را برمی‌گرداند (وضعیت 200 به‌جای 201) و آن را دوباره ثبت نمی‌کند.

کلید خوب این ویژگی‌ها را دارد:

1. از رکورد خودتان ساخته می‌شود، مثل شماره سفارش یا فاکتور، نه یک مقدار تصادفی در هر تلاش.
2. پیشوند دارد، مثل shop-order-1045 و refund-1045، تا برگشت از فروش با خود فروش تداخل نکند.
3. کنار رکورد شما ذخیره می‌شود تا بعداً سند مربوط را پیدا کنید.

#برگشت از فروش و سفارش لغوشده

برگشت از فروش یک سند جدید است، نه تغییر در سند فروش. اگر مبلغ سفارش ۱۰۴۵ کامل برگردانده شود، ردیف‌های معکوس را ثبت کنید (بدهکار ۶۲۰۱ برگشت از فروش ۱۰۰٬۰۰۰٬۰۰۰ و ۳۲۰۵ مالیات ۱۰٬۰۰۰٬۰۰۰ ریال، بستانکار ۱۱۰۳ بانک ۱۱۰٬۰۰۰٬۰۰۰ ریال) با کلید refund-1045 و مرجعی که به سفارش اصلی اشاره کند. اگر فروش اشتباهی ثبت شده (سفارش آزمایشی یا سند تکراری از اتصال قدیمی)، به‌جای آن POST /journal-entries/{id}/reverse را فراخوانی کنید: سند برگشت آن را ردیف‌به‌ردیف خنثی می‌کند و هر دو سند برای حسابرس قابل مشاهده می‌مانند. ثبت برگشت در حساب جداگانه ۶۲۰۱ باعث می‌شود برگشت از فروش در صورت سود و زیان به‌صورت قلم جدا دیده شود.

#کد یا شناسه: کدام را بفرستیم؟

کد بفرستید. هر ردیف یا شناسه‌ها (account_id، party_id، cost_center_id، project_id) را می‌پذیرد یا کدها (account_code، party_code، cost_center_code، project_code). در Ledgeriano سرفصل حساب‌ها به سال مالی تعلق دارد؛ یعنی حساب ۱۱۰۳ در سال ۱۴۰۵ شناسه‌ای متفاوت با حساب ۱۱۰۳ در سال ۱۴۰۶ دارد. کد، شناسه پایداری است که اتصال شما می‌تواند در جدول نگاشت نگه دارد.

حساب‌هایی که طرف‌حساب (تفصیلی) لازم دارند، مثل حساب‌های دریافتنی و پرداختنی تجاری، ردیف بدون طرف‌حساب را رد می‌کنند. برای سفارش‌های عمده، ابتدا مشتری را با POST /parties بسازید و کدش را دوباره استفاده کنید. راهنمای کدینگ حسابداری طراحی کدهایی را که اتصال‌ها بتوانند به آن تکیه کنند توضیح می‌دهد.

#مدیریت خطا: ۴۲۲، ۴۰۲، ۴۰۹ و بقیه

همه خطاها شکل یکسانی دارند: message برای انسان، code ثابت برای برنامه و (در خطای اعتبارسنجی) شیء errors که کلیدهایش نام فیلدهاست. هر وضعیت را آگاهانه مدیریت کنید، نه با تکرار کورکورانه.

{
  "message": "حساب 6110 در این سال مالی پیدا نشد.",
  "code": "validation_failed",
  "errors": {
    "lines.1.account_code": ["حساب 6110 در این سال مالی پیدا نشد."]
  }
}

#خواندن خطای فیلدها

کلید فیلد دقیقاً ردیف را نشان می‌دهد: lines.1.account_code یعنی ردیف دوم (شمارش از صفر است). سند نامتوازن زیر lines با هر دو جمع و مبلغ اختلاف گزارش می‌شود.

هشدار: خطای ۴۰۹ روی entry_date معمولاً یعنی سال مالی بسته شده یا دوره قفل است. آن را در کد با عوض کردن تاریخ به امروز «درست» نکنید. ثبت فروش شهریور در مهر، هر دو ماه را خراب می‌کند؛ این موارد را به یک نفر ارجاع دهید. راهنمای بستن حساب‌ها و سند اختتامیه تاریخ قفل و بازگشایی سال را توضیح می‌دهد.

#وب‌هوک و بررسی امضا

وب‌هوک رویدادها را با درخواست POST و بدنه JSON به سرور شما می‌فرستد تا لازم نباشد مدام سؤال کنید. رویدادهای موجود: 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.

هر ارسال سرآیندهای X-Ledgeriano-Event، X-Ledgeriano-Delivery، X-Ledgeriano-Timestamp و X-Ledgeriano-Signature دارد. امضا برابر است با sha256= و پس از آن HMAC SHA-256 مهر زمانی، یک نقطه و بدنه خام درخواست، با کلید مخفی همان وب‌هوک.

#بررسی امضا در Node.js

پیش از اعتماد به محتوا، امضا را بررسی کنید:

import crypto from "node:crypto";

export function verifyLedgeriano(rawBody, headers, secret) {
  const ts = headers["x-ledgeriano-timestamp"];
  const sig = headers["x-ledgeriano-signature"] || "";
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; // قدیمی‌تر از ۵ دقیقه
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(ts + "." + rawBody).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(sig);
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

از بدنه خام درخواست استفاده کنید، نه JSON دوباره ساخته‌شده؛ وگرنه هش مطابقت نمی‌کند. ارسال‌های ناموفق با فاصله زمانی افزایشی دوباره تلاش می‌شوند، هر ارسال با وضعیت پاسخ ثبت می‌شود و می‌توانید از داشبورد یا API رویداد آزمایشی بفرستید یا ارسالی را دوباره انجام دهید.

#دریافت گزارش‌های مالی از API

همان API که سند ثبت می‌کند، نتیجه را هم می‌خواند. گزارش‌ها زیر /reports هستند: trial-balance، balance-sheet، income-statement، cash-flow، equity-changes، general-ledger، journal، party-balances و dashboard.

curl "https://api.ledgeriano.com/api/v1/reports/trial-balance?from=2026-03-21&to=2026-09-22" \
  -H "Authorization: Bearer $LEDGERIANO_API_KEY" -H "Accept: application/json"

این درخواست تراز آزمایشی ۱ فروردین تا ۳۱ شهریور ۱۴۰۵ را برمی‌گرداند: برای هر حساب ستون‌های بدهکار و بستانکار ابتدای دوره، گردش دوره و مانده پایان دوره، به‌همراه جمع‌ها و پرچم is_balanced. صورت وضعیت مالی پارامترهای as_of و compare (مقایسه با سال قبل) را می‌پذیرد. محتوای هر صورت مالی را در راهنمای صورت‌های مالی ببینید.

#محدودیت نرخ و سرآیندهای اعتبار

به‌طور پیش‌فرض هر کلید در دقیقه ۱۲۰ درخواست مجاز دارد. هر پاسخ این سرآیندها را دارد:

• X-RateLimit-Limit و X-RateLimit-Remaining برای محدودیت نرخ.
• X-Credits-Charged: اعتبار مصرف‌شده این درخواست.
• X-Credits-Balance: مانده اعتبار مالک.

هزینه API به‌صورت اعتبار از حساب مالک کسب‌وکار کسر می‌شود: هر درخواست هزینه فراخوانی API دارد و عملیات هم هزینه خودشان را (ثبت سند، برگشت سند، تهیه گزارش). این قیمت‌ها را مدیر سیستم تعیین می‌کند و در صفحه قیمت‌ها آمده است. مانده را در لاگ نگه دارید و وقتی کمتر از مصرف یک هفته شد هشدار بگیرید تا حراج آخر هفته با خطای ۴۰۲ تمام نشود.

#یک سند برای هر سفارش یا یک سند در روز؟

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

#چک‌لیست آزمایش پیش از راه‌اندازی

این فهرست را روی یک کسب‌وکار آزمایشی اجرا کنید (برای آزمایش کسب‌وکار جدا بسازید تا دفاتر واقعی تمیز بماند):

1. کلیدی با سطح write بسازید و مطمئن شوید GET /accounts پاسخ می‌دهد.
2. برای هر سناریو یک سند ثبت کنید: فروش، برگشت از فروش، کارمزد درگاه، تسویه.
3. همان درخواست را با همان Idempotency-Key تکرار کنید و ببینید وضعیت 200 و همان شماره سند برمی‌گردد.
4. یک سند نامتوازن و یک کد حساب ناموجود بفرستید و مطمئن شوید خطاهای ۴۲۲ ثبت می‌شوند.
5. در دوره بسته یا قفل‌شده سند بفرستید و مطمئن شوید ۴۰۹ به یک نفر ارجاع می‌شود.
6. کلید را باطل کنید و ببینید ۴۰۱ بدون حلقه تکرار مدیریت می‌شود.
7. یک وب‌هوک را به ابزار بررسی درخواست وصل کنید، رویداد آزمایشی بفرستید و امضا را بررسی کنید.
8. تراز آزمایشی API را با تراز داشبورد مقایسه کنید.

اگر سندهایی که می‌سازید باید در شرکت خواهر هم ثبت شوند، API را با گردش‌کارهای بین شرکتی ترکیب کنید: فروشگاه فروش را در یک کسب‌وکار ثبت می‌کند و Ledgeriano خرید متناظر را در کسب‌وکار دیگر ثبت می‌کند.