Нэхэмжлэл

Нэхэмжлэх хайх (collection)

Нэг /invoices collection дээр яг нэг шүүлтүүр query-аар:

GET /api/v1/invoices?ttd={ttd}        # татварын бүртгэлийн дугаар (ТТД)
GET /api/v1/invoices?vehicle={plate}  # тээврийн хэрэгслийн дугаар
GET /api/v1/invoices?taxRef={taxRef}  # татварын нэхэмжлэх дугаар

curl -H "X-API-Key: YOUR_KEY" \
  "https://sandbox-tts.qpay.mn/api/v1/invoices?ttd=1234567"

ttd, vehicle, taxRef-ийн яг нэгийг өгнө — 0 эсвэл 2+ өгвөл 400.

Аль төрлийн төлбөр аль шүүлтүүрээр хайгдахыг Төлбөрийн төрлүүд хуудаснаас үзнэ үү.

ref_num-аар хайх

GET /api/v1/invoices/ref/{refNum}

ref_num-аар лавлана.

GovPay invoice id-аар (cache vs шинээр)

GET /api/v1/invoices/{id}          # DB-д хадгалсан хувь (MoF дуудалтгүй)
GET /api/v1/invoices/{id}/refresh  # ref_num ШИНЭЭР лавлаж сүүлийн төлөв

Хариуны бүтэц

?ttd / ?vehicle / ?taxRef collection хайлт нь жагсаалт буцаана — invoices массив + total (дүнгийн нийлбэр, төгрөг):

{
  "invoices": [ /* InvoiceDto объектууд */ ],
  "total": 150000
}

ref/{refNum}, {id}, {id}/refresh нь ганц InvoiceDto объект буцаана (invoices/total ороохгүй). Олдохгүй бол 404.

Нэхэмжлэлийн объект (`InvoiceDto`)

{
  "id": "5f8d0a3e-1b2c-4d6e-8a9f-0c1d2e3f4a5b",
  "description": "2024 оны орлогын татвар",
  "amount": 150000,
  "status": "open",
  "dueDate": null,
  "issuedAt": null,
  "vehicleNo": null,
  "payer": { "register": "6129722", "name": "Лидер вишн групп" },
  "payee": { "id": "6097898", "name": "ТАТВАРЫН ЕРӨНХИЙ ГАЗАР" },
  "year": "2018"
}

Талбар	Тип	Тайлбар
`id`	string (UUID)	GovPay дотоод ID — төлбөрт үүнийг ашиглана
`description`	string	Нэхэмжлэлийн тайлбар
`amount`	number	Дүн (төгрөг)
`status`	enum	`open` / `paid` / `overdue` / `canceled`
`dueDate`	string\|null	Төлөх эцсийн огноо (ISO) эсвэл `null`
`issuedAt`	string\|null	Үүсгэсэн огноо (ISO) эсвэл `null`
`vehicleNo`	string\|null	Тээврийн дугаар (хамаарвал)
`payer`	object	Төлөгч: `{ register, name }` — регистр/ТТД + нэр (`null` боломжтой)
`payee`	object	Хүлээн авагч (төрийн байгууллага): `{ id, name }` — байгууллагын id + нэр
`year`	string	Зөвхөн байгаа үед (ж: тээврийн татвар)

ℹ️ Хариунд source буцдаггүй — энэ нь GovPay-ийн дотоод утга. Төлбөр хийхэд source шаардлагагүй (нэхэмжлэлээс автоматаар тодорхойлогдоно). ref_num нь дотоод externalId болж хадгалагдах ба хариунд орохгүй; партнер id-г ашиглана.