API тойм

Byl API-аар нэхэмжлэх, checkout, харилцагч, багц (subscription) зэргийг өөрийн системээс шууд удирдах боломжтой. API нь REST зарчмаар ажиллаж, өгөгдлийг JSON хэлбэрээр хүлээн авч, JSON хэлбэрээр буцаана.

Хурдан тест

Төслийн API токен үүсгэнэ.
Төслийн ID-г хуулж авна.
Доорх хүсэлтийг ажиллуулаад, хариунд ирэх url руу орж төлбөрийн урсгалыг туршина.

BYL_PROJECT_ID="таны төслийн ID"
BYL_TOKEN="таны API token"

curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/invoices \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{ "amount": 1000, "description": "Миний эхний нэхэмжлэх" }'

Бааз хаяг

Бүх endpoint дараах хаягаар эхэлнэ:

https://byl.mn/api/v1

Танилт (Authentication)

Хүсэлт бүрдээ API токеноо Authorization header-ээр дамжуулна:

Authorization: Bearer <таны токен>

Токен төслийн хуудаснаас үүсдэг бөгөөд тэр төсөлд л хүчинтэй; өөр төслийн хаяг дуудвал 403 буцна. Харилцагчдынхаа төлөө төсөл нээдэг platform баг багийн бүх төсөлд ажилладаг багийн токен үүсгэж харилцагч ба төслийн API-г дуудна. Токен үүсгэх, хүчингүй болгох талаар API токен хуудсыг уншина уу.

Токен байхгүй эсвэл буруу бол 401 буцна:

{
  "message": "Unauthenticated."
}

Төслийн ID

Төсөлд хамаарах бүх endpoint /v1/projects/:id хэлбэртэй байна. Жишээ нь: GET /v1/projects/1, POST /v1/projects/1/invoices.

:id нь төслийн дугаар бөгөөд удирдлагын буланд төслийн тохиргоо цэснээс харагдана.

Byl Project ID

Доорх бүх жишээнд $BYL_PROJECT_ID гэж бичсэн хэсэгт энэ дугаарыг тавина.

Хүсэлтийн хэлбэр

Method	Хэрэглээ
`GET`	Өгөгдөл унших. Ямар ч өөрчлөлт хийхгүй.
`POST`	Шинээр үүсгэх, эсвэл үйлдэл гүйцэтгэх (жш: нэхэмжлэх хүчингүй болгох).
`PUT`	Байгаа өгөгдлийг засварлах.
`DELETE`	Өгөгдөл устгах.

Хүсэлтийн бие (body)-г JSON хэлбэрээр илгээх бөгөөд дараах хоёр header-ийг үргэлж заана:

Content-Type: application/json
Accept: application/json

Хариу

Нэг объект буцах үед өгөгдөл data талбар дотор ирнэ:

{
  "data": {
    "id": 3,
    "status": "open",
    "amount": 1000,
    "description": "Миний эхний нэхэмжлэх",
    "project_id": 1,
    "created_at": "2026-06-24T05:27:42.000000Z",
    "updated_at": "2026-06-24T05:27:42.000000Z"
  }
}

Жагсаалт буцах endpoint-уудад (жишээ нь багцын жагсаалт) data нь массив байх бөгөөд хажууд links, meta хуудаслалтын мэдээлэл ирнэ. Нэг хуудсанд 25 бичлэг байх ба дараагийн хуудсыг ?page=2 параметрээр авна.

{
  "data": [ /* ... */ ],
  "links": {
    "first": "https://byl.mn/api/v1/projects/1/subscriptions?page=1",
    "last": "https://byl.mn/api/v1/projects/1/subscriptions?page=3",
    "prev": null,
    "next": "https://byl.mn/api/v1/projects/1/subscriptions?page=2"
  },
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 25,
    "total": 63
  }
}

Огноо ба цагийн бүс

Хариунд ирэх бүх огнооны талбар (created_at, updated_at, due_date, expires_at, current_period_end, trial_ends_at, canceled_at гэх мэт) ISO 8601 хэлбэрээр, UTC цагаар, төгсгөлдөө Z дагавартай буцна:

"created_at": "2026-09-01T06:30:00.000000Z"

Улаанбаатарын цагаар харуулахын тулд UTC дээр 8 цаг нэмнэ — дээрх жишээ нь Улаанбаатарын цагаар 2026 оны 9-р сарын 1-ний 14:30 болно.

Хүсэлтээр огноо илгээх үед хэлбэр илүү чөлөөтэй байна: жишээг due_date хэсгээс үзнэ үү.

Алдаа

HTTP код	Тайлбар
`401`	Токен байхгүй, буруу эсвэл хүчингүй болсон.
`403`	Тухайн төслийн багийн гишүүн биш, эсвэл багийн эрх түр зогссон.
`404`	Хүссэн өгөгдөл олдсонгүй (эсвэл өөр төсөлд хамаарч байна).
`409`	Одоогийн төлөвт энэ үйлдэл хийх боломжгүй (жш: цуцлагдсан багцыг дахин цуцлах).
`422`	Валидацын алдаа эсвэл бизнес логикийн шаардлага зөрчигдсөн.
`503`	Байгууллагын тохиргоо дутуу, эсвэл төлбөрийн үйлчилгээ үзүүлэгч талд алдаа гарсан.
`5xx`	Byl талын алдаа. Хүсэлтийг дахин илгээж үзнэ.

Валидацын алдаа

Параметр буруу, дутуу байвал 422 кодтой, errors талбартай хариу ирнэ:

{
  "message": "The amount field is required.",
  "errors": {
    "amount": ["The amount field is required."]
  }
}

Бизнес логикийн алдаа

Параметр зөв ч үйлдэл нь одоогийн төлөвт боломжгүй бол 422 кодтой, error болон error_code талбартай хариу ирнэ:

{
  "error": "invalid_invoice_state",
  "error_code": 405,
  "message": "Нэхэмжлэхийн төлөв буруу."
}

error_code нь Byl-ийн дотоод код бөгөөд HTTP статустай хамааралгүй. Кодоор бус error талбараар салгаж шалгахыг зөвлөж байна.

`error`	`error_code`	Тайлбар
`invalid_invoice_state`	405	Нэхэмжлэхийн төлөв энэ үйлдэлд тохирохгүй (жш: төлөгдсөн нэхэмжлэх дээр төлбөр үүсгэх).
`inactive_payment_method_type`	402	Тухайн төлбөрийн хэлбэр төсөлд идэвхгүй.
`invalid_payment_amount_for_pocket_driver`	407	Pocket-ээр төлөх дүн 500 төгрөгөөс их байх шаардлагатай.
`closed_checkout`	408	Checkout хаагдсан (төлөгдсөн эсвэл хугацаа дууссан).
`checkout_cannot_be_edited`	403	Checkout-г засах боломжгүй төлөвт байна.
`invoice_subscription_state`	406	Багцын төлөв энэ үйлдэлд тохирохгүй.

Байгууллагын тохиргооны алдаа

Таны төслийн тохиргоо дутуу, эсвэл төлбөрийн үйлчилгээ үзүүлэгч талд алдаа гарвал 503 кодтой, ижил хэлбэрийн хариу ирнэ:

`error`	`error_code`	Хэрхэн засах
`valid_subscription_required`	505	Live горимд ажиллахад Byl багц идэвхтэй байх шаардлагатай.
`missing_bank_account`	501	Бизнест банкны данс нэмнэ.
`missing_primary_bank_account`	502	Бизнесийн данснуудаас нэгийг үндсэн болгоно.
`payment_method_error`	504	Төлбөрийн үйлчилгээ үзүүлэгч талын түр зуурын алдаа — дахин оролдоно уу.

Endpoint жагсаалт

Доорх бүх хаягийн урд https://byl.mn/api/v1 байна.

Нэхэмжлэх

Method	Хаяг	Тайлбар
`POST`	`/projects/:id/invoices`	Нэхэмжлэх үүсгэх
`GET`	`/projects/:id/invoices/:invoice_id`	Нэхэмжлэх лавлах
`GET`	`/projects/:id/invoices/by-client-reference-id/:ref`	Өөрийн дугаараар лавлах
`POST`	`/projects/:id/invoices/:invoice_id/void`	Хүчингүй болгох
`DELETE`	`/projects/:id/invoices/:invoice_id`	Устгах

Checkout

Method	Хаяг	Тайлбар
`POST`	`/projects/:id/checkouts`	Checkout үүсгэх
`GET`	`/projects/:id/checkouts/:checkout_id`	Checkout лавлах

Харилцагч

Method	Хаяг	Тайлбар
`POST`	`/projects/:id/customers`	Харилцагч үүсгэх
`GET`	`/projects/:id/customers/:customer_id`	Харилцагч лавлах
`GET`	`/projects/:id/customers/by-client-reference-id/:ref`	Өөрийн ID-гээр лавлах

Багц (Subscription)

Method	Хаяг	Тайлбар
`GET`	`/projects/:id/subscriptions`	Жагсаалт
`POST`	`/projects/:id/subscriptions`	Туршилт эхлүүлэх
`GET`	`/projects/:id/subscriptions/:subscription_id`	Лавлах
`POST`	`/projects/:id/subscriptions/:subscription_id/cancel`	Цуцлах
`POST`	`/projects/:id/subscriptions/:subscription_id/resume`	Цуцлалт буцаах

Billing portal

Method	Хаяг	Тайлбар
`POST`	`/projects/:id/billing-portal/sessions`	Portal session үүсгэх

Дараагийн алхам

API токен — токен үүсгэж, эхний хүсэлтээ илгээх
Webhook — төлбөр төлөгдсөн мэдэгдлийг өөрийн системд хүлээн авах
Laravel SDK — Laravel хэрэглэдэг бол API-г шууд дуудахгүйгээр холбох