Заавар — VRS RFID API

1. Нэвтрэлт

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

Authorization: Bearer 12|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Анхаарах

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

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

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

Хариу

{
    "success": true,
    "data": {
        "client": "****",
        "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`	текст	Улсын дугаар. Том/жижиг үсэг хамаарахгүй

vehicle_id-гаар

curl -G "https://rfid.mrt.gov.mn/api/v1/rfid-tags" \
     -H "Authorization: Bearer $TOKEN" \
     --data-urlencode "vehicle_id=<ТХ-ийн ID>"

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

curl -G "https://rfid.mrt.gov.mn/api/v1/rfid-tags" \
     -H "Authorization: Bearer $TOKEN" \
     --data-urlencode "plate_no=<УЛСЫН ДУГААР>"

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

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

{
    "success": true,
    "data": {
        "vehicle_id": 0,
        "plate_no": "****",
        "tag_count": 1,
        "has_active_tag": true,
        "tags": [
            {
                "tag_id": 0,
                "serial_number": "****",
                "tid": "****",
                "epc": "****",
                "qrcode": "****",
                "is_active": true,
                "is_inconsistent": false,
                "status": 1,
                "created_date": "****",
                "updated_date": null
            }
        ]
    },
    "meta": { "request_id": "…", "queried_at": "…", "pii": false }
}

3. Тагаас тээврийн хэрэгсэл ба оношилгоо

GET /api/v1/vehicle-by-tag

Уншигч төхөөрөмжөөс ирсэн кодоор тээврийн хэрэгслийг олох урвуу лавлагаа. vehicle:read эрх шаардана.

Доорх аль нэг талбараар хайна — хоёр ба түүнээс олныг зэрэг дамжуулбал 422 буцна.

Параметр	Формат
`tid`	24 тэмдэгт, hex
`epc`	24 тэмдэгт, hex
`qrcode`	32 тэмдэгт, `GOV`-оор эхэлнэ
`serial_number`	13 оронтой тоо
`tag_id`	бүхэл тоо

TID-гаар

curl -G "https://rfid.mrt.gov.mn/api/v1/vehicle-by-tag" \
     -H "Authorization: Bearer $TOKEN" \
     --data-urlencode "tid=<TID КОД>"

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

{
    "success": true,
    "data": {
        "tag": {
            "tag_id": 0,
            "serial_number": "****",
            "tid": "****",
            "epc": "****",
            "qrcode": "****",
            "is_active": true,
            "is_inconsistent": false
        },
        "vehicle": {
            "vehicle_id": 0,
            "plate_no": "****",
            "cabin_no": "****",
            "mark": "****",
            "model": "****",
            "build_year": 0,
            "color": "****",
            "country": "****",
            "vehicle_type": "****",
            "purpose": "****",
            "fuel": "****",
            "engine_capacity": 0,
            "axle_count": 0,
            "seat_count": 0,
            "total_weight": 0,
            "is_stolen": false,
            "status": "****"
        },
        "inspection": {
            "last": {
                "inspection_id": 0,
                "date": "****",
                "valid_until": "****",
                "passed": true,
                "result": "****",
                "branch": "****",
                "odometer": 0,
                "is_expired": false,
                "checks": { "brake": "****", "light": "****", "emission": "****" }
            },
            "history": [ "…" ]
        }
    },
    "meta": { "request_id": "…", "matched_by": "tid", "inspection": true }
}

Анхаарах

inspection блок зөвхөн inspection:read эрхтэй токенд ирнэ.
is_expired нь сүүлийн үзлэгийн хугацаа дууссан эсэхийг шууд хэлнэ — өөрөө огноо харьцуулах шаардлагагүй.
Үзлэгийн систем түр боломжгүй бол inspection нь null ирнэ; үлдсэн мэдээлэл хэвийн.
Эзэмшигчийн хувийн мэдээлэл (нэр, регистр, утас, хаяг) энэ API-аар огт буцахгүй.

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

Талбар	Тайлбар
`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-ээс харна.

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

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

{
    "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	`TAG_NOT_FOUND`	Тийм кодтой RFID таг бүртгэлд алга
404	`ENDPOINT_NOT_FOUND`	Хаяг буруу
422	`VALIDATION_ERROR`	Параметр буруу. error.details талбарт дэлгэрэнгүй
429	`RATE_LIMIT_EXCEEDED`	Минутын хязгаар хэтэрсэн. Түр хүлээгээд дахин оролдоно
503	`UPSTREAM_UNAVAILABLE`	Бүртгэлийн сан түр боломжгүй. Дахин оролдоно
500	`SERVER_ERROR`	Дотоод алдаа. request_id-г бидэнд мэдэгдэнэ үү

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

7. Postman

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

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

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

1. Нэвтрэлт

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

2. ТХ-ээс тагийн мэдээлэл лавлах

3. Тагаас тээврийн хэрэгсэл ба оношилгоо

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

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

7. Postman