Нэхэмжлэх

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

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

Нэхэмжлэх vs Checkout

Тодорхой дүн төлүүлэх бол нэхэмжлэх. Бүтээгдэхүүн, тоо хэмжээ, хөнгөлөлтийн код, хүргэлтийн хаяг зэрэгтэй худалдан авалт бол Checkout илүү тохиромжтой.

Төлөвүүд

Төлөв	Тайлбар
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-д дараах хэлбэрүүдийн аль нь ч тохирно:

Хэлбэр	Жишээ	Хэрхэн тооцох
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 цагаар.

Цагийн бүс

Огноог цагийн бүсгүйгээр илгээвэл Byl түүнийг Улаанбаатарын цагаар (UTC+8) ойлгоно. Тодорхой цагийн бүс шаардлагатай бол ISO 8601 хэлбэрээр (+08:00 эсвэл Z дагавартай) илгээнэ үү.

Ямар хэлбэрээр илгээснээс үл хамааран хариунд 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

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

TIP

Төлбөр төлөгдсөнийг мэдэхийн тулд энэ endpoint-ыг тасралтгүй дуудах (polling) шаардлагагүй — webhook тохируулбал invoice.paid event тэр даруй танд ирнэ.

Жишээ хүсэлт

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 (танай захиалгын дугаар)-аар шууд лавлана. Хариу нь нэхэмжлэх лавлах-тай ижил.

Хамгийн сүүлийн нэхэмжлэх буцна

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

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

Зөвхөн draft төлөвт

Одоогийн байдлаар API-аар хүчингүй болгох нь draft төлөвт байгаа нэхэмжлэх дээр л ажиллана. open, paid, void төлөвт байгаа нэхэмжлэх дээр дуудвал 403 буцна.

auto_advance өгөгдмөлөөр true тул API-аар үүсгэсэн нэхэмжлэх шууд open болдгийг анхаарна уу — дараа нь хүчингүй болгох шаардлагатай бол auto_advance: false-оор үүсгэнэ. Аль хэдийн open болсон нэхэмжлэхийг удирдлагын буланд хүчингүй болгож болно.

Жишээ хүсэлт

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 огноо буцна.

Зөвхөн draft төлөвт

Устгах нь мөн draft төлөвт байгаа нэхэмжлэх дээр л ажиллана — бусад төлөвт 403 буцна. Эцэслэгдсэн нэхэмжлэх нь тайлан, түүхийн бүрэн бүтэн байдлыг хангахын тулд устдаггүй.

Жишээ хүсэлт

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 — бүтээгдэхүүнтэй худалдан авалт