خریدها | Layatanahi
dr

Api

خریدها#

GET /api/v2/purchases فاکتورهای خرید دریافت‌شده توسط تجارت را برمی‌گرداند، و GET /api/v2/purchases/{id} یک خرید را با فاکتور، تأمین‌کننده، اقلام و پرداخت‌هایش برمی‌گرداند.

اجازه#

الزاممقدار
صلاحیتpurchases:read
اجازه صفحهpurchase.purchases.read
رفتار شعبهسطح کل تجارت یا شعبه‌فیلترشده

پارامترهای کوئری#

پارامترنوعپیش‌فرضیادداشت
fromdate—شروع شامل دوره خرید
todate—پایان شامل؛ باید برابر یا بعد از from باشد
language_codestringApp localeنام محصولات در اقلام
pageinteger ≥ 11شماره صفحه
per_pageinteger 1–10025اندازه صفحه
idinteger ≥ 1—به‌جای فهرست، یک خرید را در data برمی‌گرداند

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

bash
curl -s "https://app.example.com/api/v2/purchases?from=2026-10-01&to=2026-10-31" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Business-Branch: 4" \
  -H "Accept: application/json"

پاسخ فهرست#

json
{
  "data": [
    {
      "id": 451,
      "business_branch_id": 4,
      "invoice_number": "PUR-2026-0451",
      "grand_total": 42000,
      "paid_amount": 20000,
      "currency": "AFN",
      "supplier_name": "Kabul Electronics",
      "status": "Completed",
      "status_id": 10,
      "purchase_datetime": "2026-10-21 10:14:00",
      "created_at": "2026-10-21 10:14:02"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 25,
    "total": 1
  }
}

درخواست جزئیات#

bash
curl -s "https://app.example.com/api/v2/purchases/451" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json"

پاسخ جزئیات#

json
{
  "data": {
    "id": 451,
    "status": "Completed",
    "is_editable": false,
    "is_deletable": false,
    "created_at": "2026-10-21 10:14:02",
    "invoice": {
      "id": 8801,
      "invoice_number": "PUR-2026-0451",
      "total_amount": 42000,
      "tax_amount": 0,
      "discount_amount": 0,
      "miscellaneous_amount": 500,
      "grand_total": 42500,
      "paid_amount": 20000,
      "due_date": "2026-11-20",
      "currency": {
        "code": "AFN",
        "symbol": "؋"
      },
      "notes": null
    },
    "branch": {
      "id": 4,
      "username": "kabul-main",
      "name": "Kabul Main"
    },
    "supplier": {
      "id": 12,
      "name": "Kabul Electronics",
      "phone": "+93700000000",
      "email": null
    },
    "items": [
      {
        "id": 9901,
        "product_code": "NET-0042",
        "product_name": "Router AX3000",
        "sku": "AX3000-BLK",
        "quantity": 20,
        "unit_price": 2100,
        "total_price": 42000,
        "comment": null
      }
    ],
    "payments": [
      {
        "id": 771,
        "amount": 20000,
        "payment_date": "2026-10-21",
        "payment_status": "completed",
        "account": "Kabul Cash"
      }
    ]
  }
}

فیلدها#

فیلدمعنا
status, status_idبرچسب وضعیت تجارت و شناسه عددی آن
is_editable, is_deletableعلامت‌های قفل سند؛ مفید برای دانستن اینکه آیا سیستم مبدأ هنوز ممکن است تغییر کند
invoiceمجموع‌ها، ارز، سررسید و یادداشت‌ها
branchشعبه دریافت‌کننده خرید
supplierهویت تأمین‌کننده وقتی طرف مقابل یک تأمین‌کننده است
itemsاقلام با مقدار، قیمت واحد و مجموع
paymentsپرداخت‌های ثبت‌شده علیه فاکتور

مبلغ‌ها به‌صورت عدد به ارز فاکتور برگردانده می‌شوند؛ currency.code آن را شناسایی می‌کند. هیچ تبدیلی انجام نمی‌شود.

رکوردهای غایب#

یک خرید بیرون از دامنه شعبه دیدنی، یا یک خرید حذف‌شده، 404 برمی‌گرداند:

json
{
  "error": {
    "error": "not_found",
    "message": "Purchase not found."
  }
}

به شکل تودرتو توجه کنید: کلید بیرونی error است و شیء درونی هم error را به‌عنوان فیلد کود استفاده می‌کند.

استفاده‌های رایج#

استفادهروش
کهولت حساب‌های پرداختنی (ageing)بر اساس دوره فهرست کنید، grand_total - paid_amount را محاسبه نمایید
صورت‌حساب تأمین‌کنندهبا تاریخ فیلتر کنید، بر اساس supplier_name گروه‌بندی نمایید
مغایرت‌گیری سطح قلمجزئیات خریدهای علامت‌زده به‌عنوان غیرقابل‌ویرایش را بگیرید
همگام‌سازی ERPبا created_at بپولید، id خرید را ذخیره کنید

محدودیت‌ها#

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

صفحات مرتبط#