Нэхэмжлэх

Нэхэмжлэх нь тодорхой мөнгөн дүнг харилцагчаас хүсэх хамгийн шулуун арга юм. Үүсгэхэд дахин давтагдашгүй веб хаяг (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	Тайлбар.
number	String	Дахин давтагдашгүй нэхэмжлэхийн дугаар.
url	String	Харилцагчид үзүүлэх нэхэмжлэхийн веб хуудас.
customer_id	Number	Холбогдсон харилцагчийн ID.
project_id	Number	Byl төслийн ID.
due_date	Date	Төлвөл зохих эцсийн хугацаа.
created_at	Date	Анх үүссэн огноо.
updated_at	Date	Өөрчлөлт орсон огноо.

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

POST /v1/projects/:project_id/invoices

Параметер	Төрөл	Заавал эсэх	Тайлбар
amount	Number	true	Мөнгөн дүн. Хамгийн багадаа 10, аравтын 2 орон хүртэл.
description	String	false	Тайлбар. 255 тэмдэгт хүртэл.
due_date	Date	false	Төлвөл зохих эцсийн хугацаа. Ирээдүйн огноо байх ёстой. Өгөгдмөл: 1 хоногийн дараа.
auto_advance	Boolean	false	true (өгөгдмөл) бол шууд open төлөвт шилжинэ. false бол draft хэвээр үлдэнэ.
customer_id	Number	false	Харилцагчийн ID. Заавал төслийн харилцагч байна.

Жишээ хүсэлт

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