Агуулга руу шилжих
BylBylByl гарын авлага

Нэхэмжлэх

Нэхэмжлэх нь тодорхой мөнгөн дүнг харилцагчаас хүсэх хамгийн шулуун арга юм. Үүсгэхэд дахин давтагдашгүй веб хаяг (url) буцах бөгөөд харилцагчаа тэр хаяг руу чиглүүлэхэд төлбөрийн хэлбэр сонгох, төлөх, баримт авах бүх зүйлийг Byl зохицуулна.

Нэхэмжлэх төлөгдмөгц webhook-оор invoice.paid event илгээгдэх тул өөрийн системд цаг алдалгүй мэдэх боломжтой.

Төлөвүүд

“Төлөвүүд” хэсэг
Төлөв Тайлбар
draft Үүссэн ч эцэслээгүй. Төлбөр хүлээн авахгүй.
open Эцэслэгдсэн, төлбөр хүлээж байна. Харилцагчид үзүүлж болно.
paid Төлөгдсөн. invoice.paid webhook илгээгдсэн байна.
void Хүчингүй болгосон. Дахин төлөх боломжгүй.

Шинээр үүсгэсэн нэхэмжлэх auto_advance (өгөгдмөл true) тохиргооны улмаас шууд open төлөвт шилжинэ. auto_advance: false дамжуулбал draft төлөвт үүснэ.

Нэхэмжлэх объект

“Нэхэмжлэх объект” хэсэг
Талбар Төрөл Тайлбар
id Number Нэхэмжлэхийн ID.
status String Төлөв: draft, open, paid, void.
amount Number Мөнгөн дүн (төгрөг).
description String Тайлбар.
client_reference_id String Танай систем дэх захиалгын дугаар. Байхгүй бол null.
number String Дахин давтагдашгүй нэхэмжлэхийн дугаар.
url String Харилцагчид үзүүлэх нэхэмжлэхийн веб хуудас.
customer_id Number Холбогдсон харилцагчийн ID.
project_id Number Byl төслийн ID.
due_date Date Төлвөл зохих эцсийн хугацаа.
created_at Date Анх үүссэн огноо.
updated_at Date Өөрчлөлт орсон огноо.

Огнооны талбарууд (due_date, created_at, updated_at) нь ISO 8601 хэлбэрээр, UTC цагаар, Z дагавартай буцна — жишээ нь "2026-09-01T06:30:00.000000Z". Дэлгэрэнгүйг Огноо ба цагийн бүс хэсгээс үзнэ үү.

Нэхэмжлэх үүсгэх

“Нэхэмжлэх үүсгэх” хэсэг
POST /v1/projects/:project_id/invoices
Параметер Төрөл Заавал эсэх Тайлбар
amount Number true Мөнгөн дүн. Хамгийн багадаа 10, аравтын 2 орон хүртэл.
description String false Тайлбар. 255 тэмдэгт хүртэл.
due_date Date false Төлвөл зохих эцсийн хугацаа. Y-m-d H:i:s, Y-m-d эсвэл ISO 8601 хэлбэртэй байна. Цагийн бүс заагаагүй бол Улаанбаатарын цагаар (UTC+8) тооцно. Одоогийн цагаас хойш байх ёстой. Өгөгдмөл: 1 хоногийн дараа.
auto_advance Boolean false true (өгөгдмөл) бол шууд open төлөвт шилжинэ. false бол draft хэвээр үлдэнэ.
client_reference_id String false Танай систем дэх захиалгын дугаар. 48 тэмдэгт хүртэл. Хариу болон webhook-д буцаж ирэх бөгөөд энэ дугаараар лавлах боломжтой.
customer_id Number false Харилцагчийн ID. Заавал төслийн харилцагч байна.

due_date-ийн хэлбэр

“due_date-ийн хэлбэр” хэсэг

due_date-д дараах хэлбэрүүдийн аль нь ч тохирно:

Хэлбэр Жишээ Хэрхэн тооцох
Y-m-d H:i:s 2026-09-01 14:30:00 Улаанбаатарын цагаар (UTC+8).
Y-m-d 2026-09-01 Тухайн өдрийн 00:00:00, Улаанбаатарын цагаар.
ISO 8601, цагийн бүстэй 2026-09-01T14:30:00+08:00 Заасан цагийн бүсээр.
ISO 8601, UTC 2026-09-01T06:30:00Z UTC цагаар.

Ямар хэлбэрээр илгээснээс үл хамааран хариунд due_date нь үргэлж ISO 8601, UTC (Z дагавартай) хэлбэрээр буцна. Жишээ нь 2026-09-01 14:30:00 илгээвэл хариунд "due_date": "2026-09-01T06:30:00.000000Z" ирнэ.

due_date нь одоогийн цагаас хойш байх ёстой — өнгөрсөн огноо илгээвэл 422 валидацын алдаа буцна.

Жишээ хүсэлт

Терминал
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": 500,
          "description": "Test invoice",
          "auto_advance": true
      }'

Жишээ гаралт

{
  "data": {
    "id": 5708,
    "status": "open",
    "amount": 500,
    "description": "Test invoice",
    "client_reference_id": null,
    "number": "DEMO-0011",
    "customer_id": null,
    "project_id": 1,
    "url": "https://byl.mn/h/invoice/5708/XN3GbRBxTslkMCeDj10CJtqlHiPfcmZ8",
    "due_date": "2026-08-06T13:13:07.000000Z",
    "created_at": "2026-08-05T13:13:07.000000Z",
    "updated_at": "2026-08-05T13:13:07.000000Z"
  }
}

Хариунд ирсэн url руу харилцагчаа чиглүүлнэ. Хаягт secret багтсан тул таахын аргагүй боловч зөвхөн тухайн харилцагчид дамжуулахыг зөвлөж байна.

Нэхэмжлэх лавлах

“Нэхэмжлэх лавлах” хэсэг
GET /v1/projects/:project_id/invoices/:invoice_id

Төлөгдсөн эсэхийг шалгах, дүн, дугаарыг дахин уншихад ашиглана.

Жишээ хүсэлт

Терминал
curl -X GET https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/invoices/5708 \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json'

Жишээ гаралт

{
  "data": {
    "id": 5708,
    "status": "paid",
    "amount": 500,
    "description": "Test invoice",
    "client_reference_id": null,
    "number": "DEMO-0011",
    "customer_id": null,
    "project_id": 1,
    "url": "https://byl.mn/h/invoice/5708/XN3GbRBxTslkMCeDj10CJtqlHiPfcmZ8",
    "due_date": "2026-08-06T13:13:07.000000Z",
    "created_at": "2026-08-05T13:13:07.000000Z",
    "updated_at": "2026-08-05T13:13:20.000000Z"
  }
}

Харилцагчийн дугаараар лавлах

“Харилцагчийн дугаараар лавлах” хэсэг
GET /v1/projects/:project_id/invoices/by-client-reference-id/:client_reference_id

Byl-ийн нэхэмжлэхийн ID-г өөр талдаа хадгалаагүй бол үүсгэхдээ дамжуулсан client_reference_id (танай захиалгын дугаар)-аар шууд лавлана. Хариу нь нэхэмжлэх лавлах-тай ижил.

Лавлалт зөвхөн тухайн төслийн дотор хийгддэг — өөр төслийн ижил дугаартай нэхэмжлэх хэзээ ч буцахгүй. Тохирох нэхэмжлэх байхгүй бол 404 буцна.

Жишээ хүсэлт

Терминал
curl -X GET https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/invoices/by-client-reference-id/order_842 \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json'

Жишээ гаралт

{
  "data": {
    "id": 5708,
    "status": "paid",
    "amount": 500,
    "description": "Test invoice",
    "client_reference_id": "order_842",
    "number": "DEMO-0011",
    "customer_id": null,
    "project_id": 1,
    "url": "https://byl.mn/h/invoice/5708/XN3GbRBxTslkMCeDj10CJtqlHiPfcmZ8",
    "due_date": "2026-08-06T13:13:07.000000Z",
    "created_at": "2026-08-05T13:13:07.000000Z",
    "updated_at": "2026-08-05T13:13:20.000000Z"
  }
}

Нэхэмжлэх хүчингүй болгох

“Нэхэмжлэх хүчингүй болгох” хэсэг
POST /v1/projects/:project_id/invoices/:invoice_id/void

Нэхэмжлэхийг хүчингүй болгоно — түүнээс хойш төлбөр хүлээн авахгүй. Хүчингүй болсон нэхэмжлэх түүх, тайланд үлдэх тул буруу үүсгэсэн нэхэмжлэхийг устгахын оронд хүчингүй болгохыг зөвлөж байна.

Жишээ хүсэлт

Терминал
curl -X POST https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/invoices/5711/void \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json'

Жишээ гаралт

{
  "data": {
    "id": 5711,
    "status": "void",
    "amount": 500,
    "description": "Test invoice",
    "client_reference_id": null,
    "number": "DEMO-0011",
    "customer_id": null,
    "project_id": 1,
    "url": "https://byl.mn/h/invoice/5711/XN3GbRBxTslkMCeDj10CJtqlHiPfcmZ8",
    "due_date": "2026-09-08T16:33:41.000000Z",
    "created_at": "2026-09-07T16:33:41.000000Z",
    "updated_at": "2026-09-07T16:33:50.000000Z"
  }
}

Нэхэмжлэх устгах

“Нэхэмжлэх устгах” хэсэг
DELETE /v1/projects/:project_id/invoices/:invoice_id

Нэхэмжлэхийг жагсаалтаас нуух үйлдэл. Хариунд deleted_at огноо буцна.

Жишээ хүсэлт

Терминал
curl -X DELETE https://byl.mn/api/v1/projects/$BYL_PROJECT_ID/invoices/5711 \
    -H "Authorization: Bearer $BYL_TOKEN" \
    -H 'Accept: application/json'

Жишээ гаралт

{
  "data": {
    "id": 5711,
    "deleted_at": "2026-09-07T16:30:35.000000Z"
  }
}

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

“Дараагийн алхам” хэсэг
  • Webhook — invoice.paid event-ийг өөрийн системд хүлээн авах
  • Checkout — бүтээгдэхүүнтэй худалдан авалт