Тээврийн хэрэгслийн RFID тагийн лавлагааны API

Улсын бүртгэлээс тээврийн хэрэгслийн RFID тагийн мэдээлэл лавлах зөвхөн унших зориулалттай REST API.

Үндсэн хаяг: https://rfid.mrt.gov.mn/api/v1
Формат: JSON (UTF-8), зөвхөн GET
Хүсэлтийн хязгаар: 60 хүсэлт/минут (гэрээгээр өөрчилж болно)

1. Нэвтрэлт

Байгууллага бүрд тусдаа токен олгоно. Хүсэлт бүрд Authorization толгойд дамжуулна:

Authorization: Bearer 12|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Анхаарах

Токен нь нууц үгтэй адил. Кодод шууд бичихгүй, орчны хувьсагчид хадгална.
Байгууллага бүрд зөвшөөрөгдсөн IP жагсаалт тохируулж болно. Серверээ шилжүүлэх бол урьдчилан мэдэгдэнэ үү.
Токен алдагдсан гэж сэжиглэвэл нэн даруй мэдэгдээрэй — хуучныг нь хүчингүй болгож шинийг олгоно.

Холболтоо шалгах

curl -H "Authorization: Bearer $TOKEN" https://rfid.mrt.gov.mn/api/v1/ping

Хариу

{
    "success": true,
    "data": {
        "client": "iot",
        "name": "АЙ ӨҮ ТЕХНОЛОЖИ",
        "abilities": ["rfid:read"],
        "rate_limit": 60,
        "expires_at": null
    },
    "meta": { "request_id": "…", "queried_at": "…" }
}

2. Тагийн мэдээлэл лавлах

GET /api/v1/rfid-tags

vehicle_id эсвэл plate_no-гийн аль нэгийг заавал дамжуулна. Хоёуланг нь зэрэг дамжуулбал 422 буцна.

Параметр	Төрөл	Тайлбар
`vehicle_id`	бүхэл	Улсын бүртгэл дэх тээврийн хэрэгслийн дотоод ID
`plate_no`	текст	Улсын дугаар, ж: `3616УБЕ`. Хоосон зай, зураасыг үл тооно; том/жижиг үсэг хамаарахгүй

vehicle_id-гаар

curl -G "https://rfid.mrt.gov.mn/api/v1/rfid-tags" \
     -H "Authorization: Bearer $TOKEN" \
     --data-urlencode "vehicle_id=1661068"

Улсын дугаараар

curl -G "https://rfid.mrt.gov.mn/api/v1/rfid-tags" \
     -H "Authorization: Bearer $TOKEN" \
     --data-urlencode "plate_no=3616УБЕ"

Кирилл үсэгтэй дугаарыг URL-encode хийнэ (curl --data-urlencode, JS-д encodeURIComponent()).

Амжилттай хариу — 200

{
    "success": true,
    "data": {
        "vehicle_id": 1661068,
        "plate_no": "3616УБЕ",
        "tag_count": 1,
        "has_active_tag": true,
        "tags": [
            {
                "tag_id": 5,
                "serial_number": "8657000000053",
                "tid": "E28068942000502104F72607",
                "epc": "8657000000053D4CAC986EB9",
                "qrcode": "GOVE517BA20047596CD9FB13242CCD19",
                "is_active": true,
                "is_inconsistent": false,
                "status": 1,
                "created_date": "2023-08-25T00:00:00+08:00",
                "updated_date": null
            }
        ]
    },
    "meta": { "request_id": "…", "queried_at": "…", "pii": false }
}

3. Талбарын тайлбар

Талбар	Тайлбар
`vehicle_id`	ТХ-ийн дотоод ID. Дараагийн лавлагаанд үүнийг ашиглавал хурдан
`plate_no`	Бүртгэл дэх улсын дугаар
`tag_count`	Устгагдаагүй тагийн тоо
`has_active_tag`	Идэвхтэй таг байгаа эсэх — «наалттай юу?» гэдгийг шалгах хамгийн хялбар талбар
`tags[].tid`	Тагийн үйлдвэрийн хувиршгүй код
`tags[].epc`	Уншигч төхөөрөмжийн барьж авдаг EPC код
`tags[].qrcode`	Тагийн дээрх QR кодын утга
`tags[].serial_number`	Тагийн сериал дугаар
`tags[].is_active`	Тухайн таг идэвхтэй эсэх
`tags[].is_inconsistent`	Мэдээлэл зөрүүтэй гэж тэмдэглэгдсэн эсэх
`tags[].created_date`	Бүртгэсэн огноо (ISO 8601, +08:00)

tags нь хоосон массив байж болно — «ТХ бүртгэлтэй, гэхдээ таг наагаагүй» гэсэн үг. Эрэмбэ: эхэлж идэвхтэй нь, дараа нь шинэ нь.

Хувийн мэдээлэл

note, phone_number талбарууд нь зөвхөн rfid:pii эрх олгогдсон токенд ирнэ. Эрхгүй бол тэдгээр талбар огт байхгүй (хоосон утгаар ирэхгүй), meta.pii нь false байна. Өөрийн эрхээ /ping-ээс харна.

4. Алдааны кодууд

Бүх алдаа ижил бүтэцтэй:

{
    "success": false,
    "error": { "code": "VEHICLE_NOT_FOUND", "message": "…" },
    "meta": { "request_id": "…" }
}

Програм дотроо error.code-оор салгаж боловсруулна — message нь хүнд зориулсан бөгөөд өөрчлөгдөж болно.

HTTP	Код	Утга / хийх зүйл
401	`UNAUTHENTICATED`	Токен буруу, дуусгавар болсон, эсвэл дамжуулаагүй
403	`IP_NOT_ALLOWED`	Бүртгэгдээгүй IP-ээс хандсан — шинэ IP-гээ бүртгүүлнэ
403	`CLIENT_DISABLED`	Байгууллагын эрх түдгэлзсэн
403	`CLIENT_EXPIRED`	Гэрээний хугацаа дууссан
403	`INSUFFICIENT_ABILITY`	Токенд тухайн эрх олгогдоогүй
404	`VEHICLE_NOT_FOUND`	Тийм ТХ бүртгэлд алга
404	`ENDPOINT_NOT_FOUND`	Хаяг буруу
422	`VALIDATION_ERROR`	Параметр буруу. error.details талбарт дэлгэрэнгүй
429	`RATE_LIMIT_EXCEEDED`	Минутын хязгаар хэтэрсэн. Түр хүлээгээд дахин оролдоно
503	`UPSTREAM_UNAVAILABLE`	Бүртгэлийн сан түр боломжгүй. Дахин оролдоно
500	`SERVER_ERROR`	Дотоод алдаа. request_id-г бидэнд мэдэгдэнэ үү

Хариу бүрд X-Request-Id толгой ирнэ. Асуудал мэдээлэхдээ энэ утгыг хамт илгээвэл тухайн дуудлагыг шууд олж мөшгинө.

5. Зөвлөмж

Кэшлэх. Тагийн мэдээлэл ховор өөрчлөгддөг. Өөрийн талдаа 5–15 минут кэшлэвэл хязгаарт мөргөхгүй.
vehicle_id-г хадгалах. Нэг удаа улсын дугаараар лавлаад ID-г нь хадгалчихвал дараагийн лавлагаа хурдан бөгөөд найдвартай — улсын дугаар солигдож болно, vehicle_id солигдохгүй.
429, 503 үед дахин оролдох. Экспоненциал хүлээлттэйгээр (1с, 2с, 4с…) 3 удаа хүртэл.
Timeout. Холболтод 5 секунд, хариу хүлээхэд 15 секунд хангалттай.

6. Postman

Бэлэн коллекц — 6 хүсэлт, автомат шалгалттай. Хоёуланг нь татаж Postman-д Import хийгээд, орчны token талбарт токеноо буулгахад бэлэн болно.

Коллекц татах Орчин татах

Токен авах, IP нэмэх, хязгаар өөрчлөх, алдаа мэдээлэх — системийн хариуцсан нэгжтэй холбогдоно уу.