انتقل إلى المحتوى

API ба интеграц

PetroNet System-тэй гаднаас холбогдох гурван зам бий. Аль нь танд хэрэгтэйг хэн дуудах вэ гэдэг асуулт шийднэ:

Хэн Зам Танилт
Газрын зураг, судлаач, хэвлэл — хэн ч Нээлттэй өгөгдөл /api/v1/petro/public/* Байхгүй
Өөр апп «PetroNet-ээр нэвтрэх» OIDC petronet.mn/oauth2/* Клиентээ developer.petronet.mn-д бүртгэнэ
Аж ахуйн нэгжийн систем (ERP, POS) Байгууллагын API /api/v1/petro/* Хэрэглэгчийн session — машин хоорондын түлхүүр хараахан байхгүй

Бүх хариу JSON, огноо YYYY-MM-DD, цаг ISO 8601 (Asia/Ulaanbaatar), литр нь бодит тоо, үнэ төгрөгөөр (price_mnt).

Нээлттэй өгөгдөл

Session шаардахгүй. Нэг хаягаас минутад 60 хүсэлт, 20-ийн burst — давбал 429. Компанийн нэр бүхий нөөц, аймгийн түвшний нэг операторын үлдэгдэл гэх мэт өрсөлдөгч ашиглаж болох зүйл энд байхгүй.

GET /api/v1/petro/public/daily

Улсын өдрийн нэгтгэл бүтээгдэхүүнээр, ямар хамрах хүрээнээс тооцсонтой нь. ?day=2026-10-12 — өгөөгүй бол хамгийн сүүлийн тооцоолсон өдөр.

{
  "day": "2026-10-12",
  "products": [
    {
      "product_code": "ai92",
      "product_label": "АИ-92",
      "stock_liters": 41250000,
      "capacity_liters": 98000000,
      "sales_liters": 3120000,
      "sites_total": 1612,
      "sites_reported": 1388,
      "days_of_supply": 13.2
    }
  ]
}

sites_reported / sites_total нь хамрах хүрээ: тайлан ирүүлээгүй объектын нөөц нийлбэрт ороогүй. Хамрах хүрээгүйгээр нийлбэрийг бүү нийтэл. Тооцоолсон өдөр байхгүй бол {"day": null, "products": []}.

GET /api/v1/petro/public/stations?bbox=minLon,minLat,maxLon,maxLat

Газрын зургийн цонх доторх бүртгэлтэй ШТС. bbox-ийн дараалал GeoJSON / MapLibre-гийнх; хамгийн ихдээ 35° × 15° (Монгол бүхэлдээ багтана).

{ "stations": [ … ], "count": 300, "truncated": true }

Нэг хариунд 300 хүртэл. truncated: true бол цонхоо жижигрүүл — жагсаалт бүтэн биш. ШТС бүр: id, name, brand_label, lat, lon, aimag, address, opening_hours, status, is_voucher_enabled, stock_percent, heading_count, wait_minutes ба fuels[] (type, label, price_mnt, status, stock_percent).

GET /api/v1/petro/public/stations/{id}

Нэг ШТС, дээрхтэй ижил хэлбэр. Олдохгүй бол 404.

GET /api/v1/petro/public/trips?bbox=…

Цонх доторх ШТС руу замд яваа цистерн (200 хүртэл). at_lat/at_lon нь position: "gps" бол цистерний өөрийн мэдээлэл, "estimated" бол маршрутын дагуух тооцоо.

PetroNet-ээр нэвтрэх (OIDC)

PetroNet System өөрөө OpenID Connect провайдер. Grafana (monitoring.petronet.mn) яг энэ замаар нэвтэрдэг.

  1. developer.petronet.mn-д eID-ээр нэвтэрч клиент үүсгэнэ: нэр, redirect URI, хэрэгтэй scope.
  2. Тохиргоо: https://petronet.mn/.well-known/openid-configuration. Authorization code + PKCE; токен https://petronet.mn/oauth2/token.
  3. Redirect URI-ийн host нь платформын OAUTH_REDIRECT_HOSTS жагсаалтад нэрээрээ байх ёстой — дэд домэйн өвлөгдөхгүй. Шинэ host-ыг операторт хэлж нэмүүлнэ.

Гарын үсгийн түлхүүр https://petronet.mn/.well-known/jwks.json-д; түүнийг сэлгэх нь хөгжүүлэгчийн консолын «Гарын үсгийн түлхүүр» хэсэгт.

Байгууллагын API

/api/v1/petro/* — ШТС ба агуулахын бүртгэл, сав, хөдөлгөөн, тайлангийн үе, тайлан илгээх. Эрх нь маршрут бүрт нэрлэгдсэн (petro.read, petro.report.submit, fuel.manage …), мөрийн түвшинд RLS байгууллагаар хязгаарлана.

Одоогоор энэ нь хэрэглэгчийн session-оор ажилладаг: портал, Excel workbook илгээх (client_max_body_size 8m), native апп. ERP эсвэл POS-оос хүнгүйгээр дуудах машин хоорондын түлхүүр хараахан нийтийн гэрээ биш — ШТС-ын POS ба ирмэгийн агент (хөгжүүлэлтийн төлөвлөгөө) түүнийг тодорхойлно. Түүнээс өмнө интеграц хийх бол оператортой холбогдоно уу.

Алдаа

{ "error": "bbox is required, as minLon,minLat,maxLon,maxLat" }
Код Утга
400 Параметр буруу — мессеж нь юу буруу болохыг хэлнэ
401 / 403 Session алга / эрх хүрэхгүй
404 Объект олдсонгүй
429 Хязгаар хэтэрсэн — хэсэг хүлээгээд дахин
5xx Платформын алдаа; monitoring.petronet.mn дээр харагдана