مرجع API

صورت‌حساب

پلن‌ها، کیف پول ریالی، شارژ، مصرف، فاکتورها و اطلاعات مالیاتی. مبلغ‌ها به ریال.

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

GET/v1/pricing

The public price list#

Plans, per-meter rials and the limits the platform enforces, from the dated price book. Cache-Control: public, max-age=300, with an ETag (If-None-Match gives 304). CORS: Access-Control-Allow-Origin * for GET. Pro is per developer seat (owner, admin, developer) per month, each seat's fee back as usage credit; a seat added mid-month pays the days left.

دسترسی: بدون اعتبارنامه

پاسخ

200Pricing

effective_fromstring (date)الزامی
currencystringالزامی
one of IRR
vat_percentnumber
grace_hoursnumber
plansPublicPlan[]الزامی
- idstringالزامی
  one of hobby, pro, enterprise
- seat_fee_per_monthinteger
  rials per seat per month
- usage_creditinteger
  rials per seat per month
- per_seatboolean
  true for Pro
- max_seatsinteger | null
  1 for Hobby; null for Pro
- seat_rolesstring[]
  Pro: the roles that take a seat
- free_rolesstring[]
  Pro: the roles that do not
- prorationstring
  Pro: daily, a seat added mid-month pays the days left
  one of daily
- overageboolean
  false: the plan stops at its included amounts
- spend_budget_defaultinteger | null
  rials (1 toman = 10 rials)
- limitsPlanLimits
- customboolean
  enterprise: priced by contract
metersobject[]الزامی
- meterstringالزامی
- labelstring
- unitstringالزامی
- label_fastring | null
- unit_fastring | null
- rialsintegerالزامی
  per unit, rounded as an invoice's unit price
- includedobject

خطاها

وضعیت	توضیح
500	`internal`: an unexpected failure

نمونه

curl "https://api.ibel.ai/v1/pricing"

GET/v1/billing

Plan, state and wallet#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: همهٔ نقش‌ها

پاسخ

200Billing

planstringالزامی
one of hobby, pro
statestringالزامی
grace_untilstring (date-time) | null
currencystringالزامی
one of IRR
balanceintegerالزامی
rials (1 toman = 10 rials)
periodstringالزامی
a Jalali month, YYYY-MM, e.g. 1405-08
pattern ^\d{4}-\d{2}$
usage_this_periodinteger
rials (1 toman = 10 rials)
seatsinteger
members that take a developer seat (owner, admin, developer)
seatobject
- rolesstring[]
- maxinteger | null
  1 on Hobby; null on Pro
- paid_this_periodinteger
  seats paid this month; removed and demoted ones stay paid to its end
- free_nowinteger
  paid seats no member uses: the next one added is free
- next_seatobject | null
  Pro: what one more seat costs now when none is free
usage_creditobject | null
Pro: the month's seats' credit
- totalinteger
  rials (1 toman = 10 rials)
- leftinteger
  rials (1 toman = 10 rials)
spendobject | null
- limitinteger
  rials (1 toman = 10 rials)
- pauseboolean
- usedinteger
  rials (1 toman = 10 rials)
burn_per_dayinteger
rials (1 toman = 10 rials)
days_leftinteger | null
plansobject
- proobject
  per seat
payment_methodsobject[]
the ways a top-up can be paid
- idstringالزامی
  goes in a top-up's method
- labelstringالزامی
  for people, e.g. card payment

خطاها

وضعیت	توضیح
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

نمونه

curl "https://api.ibel.ai/v1/billing" \
  -H "Authorization: Bearer $KEY"

GET/v1/billing/prices

The price book#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: همهٔ نقش‌ها

پاسخ

200Prices

toman_per_usdnumber
vat_percentnumber
pricesPrice[]الزامی
- meterstringالزامی
- labelstring
- unitstringالزامی
- label_fastring | null
  Persian
- unit_fastring | null
  Persian
- usdnumber
- rialsintegerالزامی
  per unit
- includedobject

خطاها

وضعیت	توضیح
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

نمونه

curl "https://api.ibel.ai/v1/billing/prices" \
  -H "Authorization: Bearer $KEY"

GET/v1/billing/usage

Usage and cost per meter for a month#

Database compute is sold by the compute-hour.

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: همهٔ نقش‌ها

پارامترها

periodstringکوئری
Jalali month; default this month
pattern ^\d{4}-\d{2}$

پاسخ

200BillingUsage

periodstringالزامی
a Jalali month, YYYY-MM, e.g. 1405-08
pattern ^\d{4}-\d{2}$
metersMeterUsage[]الزامی
- meterstringالزامی
- labelstring
- unitstring
- label_fastring | null
  Persian
- unit_fastring | null
  Persian
- quantitynumber
- includednumber
- billablenumber
- amountintegerالزامی
  rials (1 toman = 10 rials)
notestring

خطاها

وضعیت	توضیح
400	Bad request: `bad_period`
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

نمونه

curl "https://api.ibel.ai/v1/billing/usage" \
  -H "Authorization: Bearer $KEY"

GET/v1/billing/usage/history

Usage over time, for charts#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: همهٔ نقش‌ها

پارامترها

granularitystringکوئری
day (default): each day of a month up to today; month: each of the last months
one of day, month
periodstringکوئری
day: the Jalali month, default this one
pattern ^\d{4}-\d{2}$
monthsintegerکوئری
month: how many, 1-24, default 12
1–24
meterstringکوئری
meters to keep (comma list)

پاسخ

200UsageHistory

granularitystringالزامی
one of day, month
periodstring
a Jalali month, YYYY-MM, e.g. 1405-08
pattern ^\d{4}-\d{2}$
metersobject[]الزامی
- meterstringالزامی
- labelstringالزامی
- unitstringالزامی
- label_fastring | null
- unit_fastring | null
pointsobject[]الزامی
- atstringالزامی
  a Tehran date (YYYY-MM-DD) or a Jalali month (YYYY-MM)
- totalintegerالزامی
  rials (1 toman = 10 rials)
- metersobjectالزامی

خطاها

وضعیت	توضیح
400	Bad request: `bad_param`, `bad_period`
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

نمونه

curl "https://api.ibel.ai/v1/billing/usage/history" \
  -H "Authorization: Bearer $KEY"

GET/v1/billing/transactions

The wallet ledger (newest 200)#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: همهٔ نقش‌ها

پاسخ

200object

transactionsTransaction[]الزامی
- idintegerالزامی
- amountintegerالزامی
  rials (1 toman = 10 rials)
- kindstringالزامی
  one of topup, usage, plan_fee, vat, credit, refund, adjustment
- refstring | null
- memostring | null
- created_atstring (date-time)
- balanceinteger
  rials (1 toman = 10 rials)

خطاها

وضعیت	توضیح
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

نمونه

curl "https://api.ibel.ai/v1/billing/transactions" \
  -H "Authorization: Bearer $KEY"

GET/v1/billing/payments

Top-up payments (newest 100)#

Masked card numbers are the payer's: billing roles only.

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: مالک، ادمین، مالی

پاسخ

200object

paymentsPayment[]الزامی
- idstring (uuid)الزامی
- methodstring
  the payment method's label
- amountintegerالزامی
  rials (1 toman = 10 rials)
- statusstringالزامی
  one of created, paid, failed
- ref_idstring | null
- card_panstring | null
  masked
- errorstring | null
  one of cancelled, the payment was not completed
- created_atstring (date-time)
- verified_atstring (date-time) | null

خطاها

وضعیت	توضیح
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
500	`internal`: an unexpected failure

نمونه

curl "https://api.ibel.ai/v1/billing/payments" \
  -H "Authorization: Bearer $KEY"

POST/v1/billing/topups

Start a top-up#

Returns a payment page; the wallet is credited when the provider confirms.

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: مالک، ادمین، مالی

بدنهٔ درخواست`application/json`

amountintegerالزامی
rials
100000–2000000000
methodstring
the id of one of payment_methods in GET /v1/billing; default the first

پاسخ

200TopupCreated

paymentstring (uuid)الزامی
amountinteger
rials (1 toman = 10 rials)
methodstring
method_labelstring
pay_urlstringالزامی

خطاها

وضعیت	توضیح
400	Bad request: `bad_amount`, `bad_payment_method`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
500	`internal`: an unexpected failure
502	Upstream failure: `psp`

نمونه

curl -X POST "https://api.ibel.ai/v1/billing/topups" \
  -H "Authorization: Bearer $KEY" \
  -d '{"amount":100000}'

GET/v1/billing/callback/{method}

Payment page redirect (not for API clients)#

Verifies the payment, credits the wallet and redirects to the dashboard.

دسترسی: بدون اعتبارنامه

پارامترها

methodstringمسیرالزامی
the payment method's id
Authoritystringکوئری
the payment's reference

پاسخ

302Redirect to the dashboard's billing page with ?payment=paid|failed&id=<payment>

خطاها

وضعیت	توضیح
500	`internal`: an unexpected failure

نمونه

درخواست

curl "https://api.ibel.ai/v1/billing/callback/card"

PUT/v1/billing/spend

Set the Pro spend budget#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: مالک، ادمین، مالی
تایید دوم: با نشست داشبورد، عامل دوم در ۱۰ دقیقهٔ اخیر لازم است؛ کلید API نیازی ندارد.

بدنهٔ درخواست`application/json`

limitinteger | null
at least 0
pauseboolean

پاسخ

200Spend

limitinteger | null
at least 0
pauseboolean

خطاها

وضعیت	توضیح
400	Bad request: `bad_limit`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
500	`internal`: an unexpected failure

نمونه

curl -X PUT "https://api.ibel.ai/v1/billing/spend" \
  -H "Authorization: Bearer $KEY" \
  -d '{"limit":0,"pause":true}'

POST/v1/billing/plan

Change plan#

Pro: the month's fee for every seat, plus VAT, now. Hobby: one seat at most; no refund.

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: مالک، ادمین، مالی
تایید دوم: با نشست داشبورد، عامل دوم در ۱۰ دقیقهٔ اخیر لازم است؛ کلید API نیازی ندارد.

بدنهٔ درخواست`application/json`

planstringالزامی
one of pro, hobby

پاسخ

200object

planstringالزامی

خطاها

وضعیت	توضیح
400	Bad request: `bad_plan`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
402	Payment required: `insufficient_balance`
403	Not allowed: `forbidden`, `step_up_required`
409	Conflict: `seat_limit`
500	`internal`: an unexpected failure

نمونه

curl -X POST "https://api.ibel.ai/v1/billing/plan" \
  -H "Authorization: Bearer $KEY" \
  -d '{"plan":"pro"}'

GET/v1/billing/tax-details

The buyer's tax details#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: مالک، ادمین، مالی

پاسخ

200object

tax_detailsTaxDetails | nullالزامی
- buyer_typestringالزامی
  one of person, company
- legal_namestringالزامی
  up to 200 characters
- national_idstringالزامی
- economic_codestring | null
- postal_codestring | null
  pattern ^\d{10}$
- addressstring | null
  up to 500 characters
- updated_atstring (date-time)

خطاها

وضعیت	توضیح
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`
500	`internal`: an unexpected failure

نمونه

curl "https://api.ibel.ai/v1/billing/tax-details" \
  -H "Authorization: Bearer $KEY"

PUT/v1/billing/tax-details

Set the buyer's tax details#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: مالک، ادمین، مالی
تایید دوم: با نشست داشبورد، عامل دوم در ۱۰ دقیقهٔ اخیر لازم است؛ کلید API نیازی ندارد.

بدنهٔ درخواست`application/json`

buyer_typestringالزامی
one of person, company
legal_namestringالزامی
up to 200 characters
national_idstringالزامی
economic_codestring | null
postal_codestring | null
pattern ^\d{10}$
addressstring | null
up to 500 characters
updated_atstring (date-time)

پاسخ

200object

savedboolean

خطاها

وضعیت	توضیح
400	Bad request: `bad_type`, `bad_name`, `bad_national_id`, `bad_economic_code`, `bad_postal_code`, `bad_json`
401	`unauthorized`: missing, invalid, expired or revoked credential
403	Not allowed: `forbidden`, `step_up_required`
500	`internal`: an unexpected failure

نمونه

curl -X PUT "https://api.ibel.ai/v1/billing/tax-details" \
  -H "Authorization: Bearer $KEY" \
  -d '{"buyer_type":"person","legal_name":"…","national_id":"…"}'

GET/v1/billing/invoices

Issued invoices#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: همهٔ نقش‌ها

پاسخ

200object

invoicesInvoiceSummary[]الزامی
- numberstringالزامی
  pattern ^\d{4}-\d{6}$
- periodstringالزامی
  a Jalali month, YYYY-MM, e.g. 1405-08
  pattern ^\d{4}-\d{2}$
- issued_atstring (date-time)
- netinteger
  rials (1 toman = 10 rials)
- vatinteger
  rials (1 toman = 10 rials)
- totalintegerالزامی
  rials (1 toman = 10 rials)

خطاها

وضعیت	توضیح
401	`unauthorized`: missing, invalid, expired or revoked credential
500	`internal`: an unexpected failure

نمونه

curl "https://api.ibel.ai/v1/billing/invoices" \
  -H "Authorization: Bearer $KEY"

GET/v1/billing/invoices/{number}

An invoice, or `preview` for this month so far#

دسترسی: کلید API یا نشست داشبورد
نقش‌ها: همهٔ نقش‌ها

پارامترها

numberstringمسیرالزامی
invoice number, e.g. 1405-000001, or preview
periodstringکوئری
preview only: Jalali month
pattern ^\d{4}-\d{2}$

پاسخ

200Invoice

numberstring | nullالزامی
draftbooleanالزامی
periodstringالزامی
a Jalali month, YYYY-MM, e.g. 1405-08
pattern ^\d{4}-\d{2}$
issued_atstring (date-time) | null
linesInvoiceLine[]الزامی
- kindstringالزامی
  one of usage, discount, plan
- meterstring
- descriptionstringالزامی
- description_fastring
  Persian (not on invoices issued before 4 Nov 2026)
- quantitynumber
  plan lines: seats
- unitstring
  plan lines: seat-month (the month's seats) or seat (a seat added in the month)
- unit_fastring
  Persian
- unit_priceinteger
  rials (1 toman = 10 rials)
- amountintegerالزامی
  rials (1 toman = 10 rials)
- credit_totalinteger
  discount line on Pro: the month's usage credit from its seats, rials
netintegerالزامی
rials (1 toman = 10 rials)
vatintegerالزامی
rials (1 toman = 10 rials)
totalintegerالزامی
rials (1 toman = 10 rials)
statementobject
- fromstring (date-time)
- tostring (date-time)
- openinginteger
  rials (1 toman = 10 rials)
- topupsinteger
  rials (1 toman = 10 rials)
- creditsinteger
  rials (1 toman = 10 rials)
- chargesinteger
  rials (1 toman = 10 rials)
- closinginteger
  rials (1 toman = 10 rials)
buyerobject | null
tax details as at issue; for viewer and developer roles only buyer_type and legal_name
sellerobject
- namestring
- economic_codestring
- national_idstring
- addressstring

خطاها

وضعیت	توضیح
400	Bad request: `bad_period`
401	`unauthorized`: missing, invalid, expired or revoked credential
404	Not found: `not_found`
500	`internal`: an unexpected failure

نمونه

curl "https://api.ibel.ai/v1/billing/invoices/1405-000001" \
  -H "Authorization: Bearer $KEY"

The public price list#

پاسخ

خطاها

نمونه

Plan, state and wallet#

پاسخ

خطاها

نمونه

The price book#

پاسخ

خطاها

نمونه

Usage and cost per meter for a month#

پارامترها

پاسخ

خطاها

نمونه

Usage over time, for charts#

پارامترها

پاسخ

خطاها

نمونه

The wallet ledger (newest 200)#

پاسخ

خطاها

نمونه

Top-up payments (newest 100)#

پاسخ

خطاها

نمونه

Start a top-up#

بدنهٔ درخواستapplication/json

پاسخ

خطاها

نمونه

Payment page redirect (not for API clients)#

پارامترها

پاسخ

خطاها

نمونه

Set the Pro spend budget#

بدنهٔ درخواستapplication/json

پاسخ

خطاها

نمونه

Change plan#

بدنهٔ درخواستapplication/json

پاسخ

خطاها

نمونه

The buyer's tax details#

پاسخ

خطاها

نمونه

Set the buyer's tax details#

بدنهٔ درخواستapplication/json

پاسخ

خطاها

نمونه

Issued invoices#

پاسخ

خطاها

نمونه

An invoice, or preview for this month so far#

پارامترها

پاسخ

خطاها

نمونه

بدنهٔ درخواست`application/json`

بدنهٔ درخواست`application/json`

بدنهٔ درخواست`application/json`

بدنهٔ درخواست`application/json`

An invoice, or `preview` for this month so far#