API тойм

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

Хурдан тест

1. Төслийн API токен үүсгэнэ.
2. Төслийн ID-г хуулж авна.
3. Доорх хүсэлтийг ажиллуулаад, хариунд ирэх 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": "Миний эхний нэхэмжлэх" }'

TIP

Төсөл Test горимд байхад API яг ижилхэн ажиллах бөгөөд гүйлгээ 50 төгрөгөөр хязгаарлагдана. Дэлгэрэнгүйг Test ба Live хуудаснаас уншина уу.

Бааз хаяг

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

https://byl.mn/api/v1

Танилт (Authentication)

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

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

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

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

{
  "message": "Unauthenticated."
}

Төслийн ID

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

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

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

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

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

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

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

WARNING

Accept: application/json header-ийг мартвал алдааны хариу JSON биш, HTML хэлбэрээр ирж болзошгүй.

Хариу

Нэг объект буцах үед өгөгдөл 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
  }
}

Алдаа

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	Банкны данснуудаас нэгийг үндсэн (primary) болгоно.
payment_method_error	504	Төлбөрийн үйлчилгээ үзүүлэгч талын түр зуурын алдаа — дахин оролдоно уу.

Endpoint жагсаалт

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

Нэхэмжлэх

Method	Хаяг	Тайлбар
POST	/projects/:id/invoices	Нэхэмжлэх үүсгэх
GET	/projects/:id/invoices/:invoice_id	Нэхэмжлэх лавлах
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-г шууд дуудахгүйгээр холбох