پرش به مطلب اصلی

موجودی و تراکنش‌ها

این مجموعه از API‌ها برای مدیریت موجودی و مشاهده تراکنش‌های برنامه‌ی شما استفاده می‌شود. با استفاده از این سرویس‌ها می‌توانید موجودی فعلی برنامه‌تان را بررسی کنید و جزئیات تراکنش‌ها را مشاهده نمایید.

دسترسی‌های مورد نیاز​

برای استفاده از این API‌ها فقط نیاز به کلید API با دسترسی‌های مناسب دارید:

  • برای موجودی: دسترسی API Key با BALANCE_RETRIEVE
  • برای تراکنش‌ها: دسترسی API Key با TRANSACTION_RETRIEVE و TRANSACTION_LIST

مشاهده موجودی​

GET https://open-api.divar.ir/experimental/open-platform/balance
x-api-key: {{apikey}}

پاسخ موجودی​

{
    "balance_rials": "150000"
}

پارامترهای پاسخ​

پارامترنوعتوضیحات
balance_rialsint64موجودی برنامه به ریال

مشاهده جزئیات تراکنش​

GET https://open-api.divar.ir/experimental/open-platform/transactions/{{id}}
x-api-key: {{apikey}}

پارامترهای درخواست​

پارامترنوعاجباریتوضیحات
idstringبلهشناسه منحصر به فرد تراکنش، همان id درخواست

پاسخ جزئیات تراکنش​

{
    "transaction": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "cost_rials": 50000,
        "extra_details": "Details for tracking purposes",
        "state": "TRANSACTION_STATE_COMPLETED",
        "type": "TRANSACTION_TYPE_REORDER",
        "created_at": "2023-10-20T10:30:00Z"
    }
}

لیست تراکنش‌ها​

GET https://open-api.divar.ir/experimental/open-platform/transactions?page_size=100&page_token={{next_page_token}}
x-api-key: {{apikey}}

پارامترهای درخواست​

پارامترنوعاجباریتوضیحات
page_sizeint32خیرتعداد تراکنش‌ها در هر صفحه (۱ تا ۱۰۰)
page_tokenstringخیرتوکن برای صفحه بعدی نتایج

پاسخ لیست تراکنش‌ها​

{
    "transactions": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "cost_rials": 50000,
            "extra_details": "Details for tracking purposes",
            "state": "TRANSACTION_STATE_COMPLETED",
            "type": "TRANSACTION_TYPE_REORDER",
            "created_at": "2023-10-20T10:30:00Z"
        }
    ],
    "next_page_token": "eyJwYWdlIjoyLCJsaW1pdCI6MjB9"
}

پارامترهای پاسخ​

پارامترنوعتوضیحات
transactionsTransaction[]لیست تراکنش‌های منطبق با درخواست
next_page_tokenstringتوکن برای صفحه بعدی نتایج

شیء Transaction​

پارامترنوعتوضیحات
idstringهمان uuid که در درخواست ایجاد تراکنش
cost_rialsint64هزینه تراکنش به ریال برای برنامه‌ی شما
extra_detailsstringهمان جزئیات اضافی که در درخواست ارسال کردید
stateStateوضعیت تراکنش
typeTypeنوع تراکنش
created_atTimestampزمان ایجاد تراکنش

انواع وضعیت تراکنش (State)​

وضعیتتوضیحات
TRANSACTION_STATE_PENDINGدر انتظار
TRANSACTION_STATE_COMPLETEDتکمیل شده
TRANSACTION_STATE_FAILEDناموفق
TRANSACTION_STATE_REFUNDEDبرگشت داده شده

انواع تراکنش (Type)​

نوعتوضیحات
TRANSACTION_TYPE_REORDERنردبان

نکات مهم​

  • برای دریافت تمام تراکنش‌ها، صفحات را دنبال کنید تا لیست خالی دریافت کنید
  • موجودی برنامه‌ی شما پس از هر تراکنش موفق به‌روزرسانی می‌شود
  • تراکنش‌های REFUNDED مبلغ آن‌ها به موجودی شما برگردانده شده است
  • تراکنش‌های FAILED هیچ تأثیری بر موجودی شما ندارند
  • تراکنش‌های PENDING در حال انجام یا بررسی هستند. مبلغ این تراکنش‌ها از کیف پول شما برداشته شده است و پس از مشخص شدن وضعیت تراکنش، به روز خواهد شد