صفحه‌بندی و expand

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

فهرست‌ها

هر GET روی یک مجموعه (/v1/payments، /v1/receipts، /v1/deposits، /v1/payment_links، /v1/customers، /v1/events، /v1/webhook_endpoints، /v1/cards، /v1/devices) یک شیء فهرست از جدید به قدیم برمی‌گرداند:

JSON

{
  "object": "list",
  "url": "/v1/payments",
  "has_more": true,
  "data": [{ "id": "pay_8xkq2LmZr0Pa1Bcd", "object": "payment" }]
}

فهرست‌ها
پارامتر	توضیح
`limit`	تعداد شیء در هر صفحه، از ۱ تا ۱۰۰. پیش‌فرض ۱۰.
`starting_after`	شناسهٔ آخرین شیء صفحه‌ای که دارید: صفحهٔ بعد شیءهای قدیمی‌تر را دارد.
`ending_before`	شناسهٔ اولین شیء صفحه‌ای که دارید: صفحهٔ قبل از آن، به سمت شیءهای جدیدتر.
`created`	یک ثانیهٔ یونیکس یا یک بازه: `created[gte]=1793000000&created[lt]=1793086400` (`gt`، `gte`، `lt`، `lte`).

یا starting_after بفرستید یا ending_before، نه هر دو. نشانگری که به هیچ شیئی از فهرست اشاره نکند resource_missing می‌گیرد.

مرور همهٔ صفحه‌ها

curl -G https://a.bezanbecard.com/v1/payments \
  -H "Authorization: Bearer sk_test_…" \
  -d limit=100 \
  -d status=succeeded \
  -d "created[gte]=1793000000" \
  -d starting_after=pay_8xkq2LmZr0Pa1Bcd

هر فهرست فیلترهای خودش را دارد: پرداخت‌ها با status، customer و reference؛ واریزها با status، payment و card؛ لینک‌های پرداخت با active؛ مشتری‌ها با phone و email؛ رویدادها با type (یک نوع یا payment.*) و types[]؛ کارت‌ها با status؛ دستگاه‌ها با health. مرجع API فیلترهای هر مسیر را فهرست کرده است.

Expand

بعضی فیلدها شناسهٔ شیء دیگری را نگه می‌دارند. خود شیء را با expand[] بخواهید:

Expand
شیء	قابل expand
`payment`	`customer` (شیء مشتری به‌جای شناسه‌اش)، `deposits` (همهٔ واریزهای وصل‌شده به‌صورت کامل به‌جای خلاصه)، `receipts` (رسیدهایش از جدید به قدیم، تا ۱۰۰ عدد؛ کلید محدود دسترسی `read` روی `receipts` می‌خواهد)
`payment_link`	`card` (کارت جایگزین به‌جای شناسه‌اش)

curl -G https://a.bezanbecard.com/v1/payments/pay_8xkq2LmZr0Pa1Bcd \
  -H "Authorization: Bearer sk_test_…" \
  -d "expand[]=customer" \
  -d "expand[]=deposits"

روی فهرست‌ها پیشوند data. بگذارید (expand[]=data.customer). در POST، expand را در بدنه بفرستید. در هر درخواست حداکثر ۱۰ مورد؛ هر چیز دیگری parameter_invalid می‌گیرد.

بدون expand، فیلد deposits پرداخت تا ۱۰ خلاصه (id، amount، created) دارد و اگر بیشتر باشد has_more را هم، و پرداخت اصلاً فیلد receipts ندارد.