İzləmə sisteminin REST API-si: nəqliyyat vasitəsi məlumatlarını JSON formatında ERP, iş vaxtının uçotu və dispetçer idarəetməsinə təhlükəsiz inteqrasiya edin

9 noyabr 2026  |  İzləmə  |  İnterfeyslər və inteqrasiya

Nəqliyyat vasitəsi məlumatları yalnız müəssisənizin istifadə etdiyi sistemlərə çatdıqda həqiqətən faydalı olur: ERP sisteminə, iş vaxtının uçotuna, dispetçer idarəetməsinə, təhlillərə və işgüzar tərəfdaşlarınızın proqramlarına. Biricon IT Services-in izləmə platforması artıq bunun üçün REST interfeysi təqdim edir. Öz proqramınız nəqliyyat vasitələrini, qrupları, coğrafi zonaları, iş vaxtlarını və hadisələri JSON formatında əldə edir — OAuth 2.0 (Client Credentials) və imzalanmış JWT tokenləri ilə qorunur, OpenAPI 3.1 üzrə təsvir olunur.

Bu məqalə interfeysi müştəri portalında necə aktivləşdirməyi, sorğunun addım-addım necə yerinə yetirildiyini, hansı son nöqtələrin mövcud olduğunu, izləmə sistemini digər sistemlərə necə qoşmağı və bu zaman hansı məlumatların qorunması və təhlükəsizlik qaydalarının tətbiq olunduğunu göstərir.

Qısa xülasə

İnterfeys nə üçün lazımdır? Təcrid olunmuş həll əvəzinə sistemlərarası uyğunluq

Gözəl xəritəsi olan izləmə platforması asanlıqla digər sistemlərdən təcrid oluna bilər: dispetçerlər yürüş göstəricilərini əl ilə köçürür, əməkhaqqını hesablayanlar iş vaxtlarını yenidən hesablayır, hesabatlarda isə ERP-də həmin formada olmayan nəqliyyat vasitəsi adları yer alır. Bu əl işlərinin hər biri vaxt aparır və səhv mənbəyidir.

Standartlaşdırılmış interfeys bu problemi həll edir, çünki demək olar ki, bütün müasir proqramların dəstəklədiyi standartlara əsaslanır:

• HTTP və REST: istənilən proqramlaşdırma dili, skript və avtomatlaşdırma platforması veb sorğular göndərə bilər.
• JSON: bu məlumat formatı oxunaqlı və yığcamdır, demək olar ki, bütün mühitlərdə əlavə kitabxana olmadan emal edilə bilir.
• OAuth 2.0: parol paylaşmadan proqramlar arasında giriş üçün geniş yayılmış üsul.
• OpenAPI 3.1: interfeysin təsviri maşınla oxuna bilir. Tərtibatçılar sahələri əl ilə yenidən qurmaq əvəzinə bu təsvir əsasında müştəri proqramları, test ssenariləri və sənədlər yaradırlar.

İzləmə sistemi mövqe və səfər məlumatları üçün əsas sistem olaraq qalır. Digər sistemləriniz bu məlumatları oxuyur və sabit identifikatorlar (vehicle_id, tracker_id, group_id) vasitəsilə öz əsas məlumatları ilə əlaqələndirir.

Addım 1: müştəri portalında girişi aktivləşdirin

Texniki dəstəyə müraciət etmədən interfeysi özünüz aktivləşdirə bilərsiniz. İzləmə portalında İdarəetmə → REST-API bölməsini açın və yeni giriş yaradın:

1. Ad: aydın ad seçin, məsələn, girişdən istifadə edən tətbiqin adını. Beləliklə, sonradan hansı girişin nə üçün nəzərdə tutulduğunu asanlıqla müəyyən edə bilərsiniz.
2. Tokenin etibarlılıq müddəti: verilən tokenlərin qüvvədə qalacağı müddət: 5 dəqiqə, 15 dəqiqə, 1 saat, 8 saat, 24 saat, 1–5 il və ya müddətsiz. Müddəti məhdud girişlərdən istifadə etməyi tövsiyə edirik; müddətsiz seçim istisna olmalıdır.
3. İcazə verilən dairələr: nəqliyyat vasitələri, qruplar və coğrafi zonalar üçün vehicles:read, hadisələr (xəbərdarlıq cədvəli) və iş vaxtları üçün events:read. Yalnız tətbiqin həqiqətən ehtiyac duyduğu icazələri verin.

Giriş yaradıldıqdan sonra portal müştəri identifikatorunu və müştəri məxfi açarını göstərir. Məxfi açar yalnız bu bir dəfə göstərilir: onu dərhal parol və ya məxfi açar anbarınızda saxlayın. İtirsəniz, yenisini yaradın — lakin bu, indiyədək verilmiş bütün tokenləri etibarsız edəcək. Şəkildə sınaq girişi göstərilir; dəyərlər sərbəst yaradılıb və real əhəmiyyət daşımır.

Bölmə aktivləşdirildikdən sonra tərtibatçılar interfeysin təsvirini birbaşa portaldakı REST-API səhifəsində tapa bilərlər.

Addım 2: token alın (OAuth 2.0)

Tətbiqiniz müştəri identifikatorunu və məxfi açarı qısamüddətli giriş tokeninə dəyişir. Bu, standart Client Credentials axınıdır:

curl -s -X POST https://IHRE-DOMAIN/ortung/api/v1/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=IHRE_CLIENT_ID \
  -d client_secret=IHR_GEHEIMNIS

Cavabda access_token, token_type (Bearer), scope və müddəti məhdud girişlər üçün saniyə ilə expires_in verilir. Etibarlılıq müddəti müddətsiz olan girişlərdə expires_in olmur, tokenin müddəti bitmir. İstəyə görə scope parametri ilə tokenin hansı icazə dairələrini ehtiva edəcəyini məhdudlaşdırmaq olar.

Addım 3: məlumatları əldə edin

Tokenlə son nöqtələrə GET sorğuları göndərirsiniz. Token Authorization başlığında ötürülür:

curl -s -H "Authorization: Bearer TOKEN" \
  "https://IHRE-DOMAIN/ortung/api/v1/tracker"

Eyni əməliyyatın gecə işləyən sinxronlaşdırma tapşırığında istifadə oluna biləcək qısa Python nümunəsi:

import requests

BASIS = "https://IHRE-DOMAIN/ortung/api/v1"

antwort = requests.post(BASIS + "/oauth/token", data={
    "grant_type": "client_credentials",
    "client_id": "IHRE_CLIENT_ID",
    "client_secret": "IHR_GEHEIMNIS",
}, timeout=30)
antwort.raise_for_status()
token = antwort.json()["access_token"]

kopf = {"Authorization": "Bearer " + token}
fahrzeuge = requests.get(BASIS + "/tracker", headers=kopf, timeout=30).json()
for f in fahrzeuge["trackers"]:
    print(f["vehicle_id"], f["name"])

Son nöqtələrə ümumi baxış

Nümunələr: nəqliyyat vasitələri, qruplar, iş vaxtı, hadisələr

Nəqliyyat vasitələri və qruplar: /tracker və /groups

Bu iki son nöqtə avtoparkınızın əsas məlumatlarını təqdim edir. Hər nəqliyyat vasitəsinin vehicle_id və tracker_id identifikatoru var; qruplar isə üzvlərini vehicle_ids vasitəsilə göstərir. Beləliklə, strukturunuzu başqa sistemdə də əks etdirə bilərsiniz. owned sahəsi nəqliyyat vasitəsinin sizə məxsus olduğunu, yoxsa ona baxış icazəsinin sizə verildiyini göstərir. Baxış icazəsi verilmiş nəqliyyat vasitələrində IMEI kimi daxili sahələr göstərilmir.

Hər nəqliyyat vasitəsi və gün üzrə iş vaxtı: /workinghours

?date=JJJJ-MM-TT ilə baxış icazəniz olan hər nəqliyyat vasitəsi üçün günün iş vaxtı təhlilini əldə edirsiniz: qeydə alınmış iş qrafikindən planlaşdırılmış saatlar, işgüzar səfərlərdən faktiki saatlar, fərq, ilk başlanğıc və son bitmə, səfərlərin sayı və iş məqsədli yürüş. Bayramlar, məzuniyyət və istirahət günləri day_type ilə işarələnir. Şəxsi səfərlər nəzərə alınmır, şəxsi yürüş təqdim edilmir. vehicle_id ilə təhlili ayrı-ayrı nəqliyyat vasitələri ilə məhdudlaşdırmaq olar.

Hadisələr: /events

Bu son nöqtə nəqliyyat vasitələrinizin adları və bütün göstəriciləri (vaxt, xəbərdarlıq növü, 1–3-cü dəyərlər, ünvan, qeydlər, mövqe, sürət, istiqamət) ilə birlikdə xəbərdarlıq cədvəlini təqdim edir. Dövr from və to vasitəsilə təyin olunur (tarix və ya dəqiq vaxt, hər sorğuda ən çox 31 gün); vehicle_id və alert ilə nəqliyyat vasitələrinə və xəbərdarlıq növlərinə görə filtr tətbiq etmək, limit ilə isə hər nəqliyyat vasitəsi üzrə nəticələrin sayını məhdudlaşdırmaq olar. Cavabda əhatə olunan dövr göstərilir ki, proqramınız məlumatların tam olub-olmadığını müəyyən edə bilsin. Şəkildəki dəyərlər sərbəst seçilmiş nümunələrdir.

İstifadə ssenariləri: ERP, iş vaxtının uçotu, dispetçer idarəetməsi, BI, avtomatlaşdırma

İnterfeys məqsədli şəkildə ümumi istifadə üçün hazırlanıb. Onu veb sorğuları və JSON-u dəstəkləyən proqramların olduğu hər yerdə istifadə edə bilərsiniz:

• ERP və mühasibat uçotu: xərc mərkəzlərinin və nəqliyyat vasitələrinin adlarının uyğun gəlməsi üçün nəqliyyat vasitələrini və qrupları əsas məlumatlar kimi köçürün. Hər nəqliyyat vasitəsinin gündəlik iş məqsədli yürüşü xərclərin hesablanmasında nəzərə alınır.
• İş vaxtının uçotu və əməkhaqqının hesablanması: /workinghours hər gün üzrə planlaşdırılmış və faktiki saatları təqdim edir. İlk başlanğıc və son bitmə vaxtları (UTC ilə) əl ilə yenidən hesablamağa ehtiyacı aradan qaldırır.
• Dispetçer idarəetməsi və nəqliyyatın idarə olunması: qruplar və coğrafi zonalar marşrut və müştəri strukturunuzu əks etdirir; hadisələr yolda nə baş verdiyini göstərir.
• Hesabatlar və biznes analitikası: məlumatları müəyyən edilmiş vaxtlarda məlumat anbarlarına və təhlil sistemlərinə yükləmək olar. Sabit identifikatorlar onları digər mənbələrlə birləşdirməyi asanlaşdırır.
• Avtomatlaşdırma: skriptlər və iş axını platformaları hadisələri sorğulaya və onlara əsasən öz proseslərini başlada bilər, məsələn, sürət xəbərdarlığı zamanı daxili bildiriş göndərə bilər.
• Tərəfdaş və müştəri portalları: işgüzar tərəfdaşlarınızın sizə baxış icazəsi verdiyi nəqliyyat vasitələri də girişiniz vasitəsilə əldə edilə bilər — tərəfdaşın müəyyən etdiyi məhdudiyyətlər olduğu kimi tətbiq olunur.

İnterfeysin təsviri OpenAPI 3.1 formatında olduğundan tərtibatçılar onun əsasında əksər proqramlaşdırma dillərində hazır müştəri kitabxanaları yarada bilirlər. Bu, vaxta qənaət edir və sahə adlarındakı yazı səhvlərini azaldır.

Təhlükəsizlik və məlumatların qorunması

Mövqe məlumatlarına çıxış verən interfeys aydın qaydalar tələb edir. Bu qaydalar hər zaman qüvvədədir:

• Portaldakı ilə eyni görünürlük: girişiniz yalnız öz nəqliyyat vasitələrinizi və sizə baxış icazəsi verilənləri görür. Tərəfdaş müəyyən sahələri (məsələn, ünvan və ya sürət) sizdən gizlədibsə, onlar interfeysdə də göstərilmir.
• Şəxsi səfərlər məxfi qalır: şəxsi səfərlərin təyinat yerləri, qeydləri və koordinatları gizlədilir, şəxsi səfərlər iş vaxtına daxil edilmir.
• Daxili sahələr ötürülmür: icazələr və canlı məlumatlar təqdim edilmir. IMEI-ni yalnız öz nəqliyyat vasitələriniz üçün görə bilərsiniz.
• Minimum icazələr: vehicles:read və events:read icazə dairələri ayrıca verilə bilər; hər ikisi yalnız oxumaq üçündür.
• Məxfi açar yalnız bir dəfə göstərilir: yalnız onun heşi saxlanılır. Yeni məxfi açar əvvəlki bütün tokenləri etibarsız edir; deaktiv edilmiş girişdən istifadə dərhal dayandırılır.
• İmzalanmış tokenlər: tokenlər server tərəfindəki açarla imzalanır və icazə dairəsi ilə etibarlılıq müddətini ehtiva edir.
• Uğursuz cəhdlərdən qorunma: token son nöqtəsi hər mənbə ünvanından təkrarlanan yanlış giriş cəhdlərini məhdudlaşdırır.

Öz sisteminizdə məlumatların emalına görə məsuliyyət sizdə qalır, xüsusən də söhbət sürücü məlumatlarından gedirsə. Şəxslərlə əlaqələndirilən təhlillər qurmazdan əvvəl müəssisədaxili razılaşmanı və məlumatların hansı məqsədlə istifadə ediləcəyini dəqiqləşdirin.

Sorğu limiti və məqsədəuyğun sorğu intervalları

İnterfeysin bütün müştərilər üçün etibarlı işləməsi üçün hər girişə dəqiqədə 7 və saatda 30 sorğu limiti tətbiq olunur. Hər məlumat sorğusu bir sorğu sayılır; tokenin alınması sayılmır. Rədd edilmiş sorğular limiti azaltmır. Limit aşıldıqda interfeys HTTP 429 cavabı və gözləmə müddətini saniyə ilə göstərən Retry-After başlığını qaytarır.

Saatda 30 sorğu ilə işi rahat planlaşdırmaq olar. Limiti aşmayan bir nümunə:

Dərhal yenidən cəhd etmək əvəzinə Retry-After göstəricisini oxuyun və yalnız son uğurlu sorğudan sonrakı dövrü sorğulayın. Daha çox sorğu göndərmək lazımdırsa, başqa tətbiq üçün əlavə giriş yaradın — limit hər girişə ayrıca tətbiq olunur.

Xəta kodları və xətaların emalı

Xəta cavabları da xəta kodu (error) və anlaşılan təsvir (error_description) ilə JSON formatında verilir. Beləliklə, proqramınızda xətaları düzgün qeydə almaq olar.

Tez-tez verilən suallar

İzləmə sisteminin REST API-sini necə aktivləşdirə bilərəm?

Müştəri portalında İdarəetmə → REST-API bölməsində yeni giriş yaradın: ad verin, tokenin etibarlılıq müddətini seçin və icazə verilən dairələri müəyyən edin. Bundan sonra portal müştəri identifikatorunu və müştəri məxfi açarını göstərir. Məxfi açar yalnız bir dəfə göstərilir.

İnterfeys hansı autentifikasiya üsulundan istifadə edir?

Client Credentials icazə növü ilə OAuth 2.0. Tətbiq müştəri identifikatorunu və məxfi açarı imzalanmış JWT-yə dəyişir və onu Bearer tokeni kimi sorğu ilə birlikdə göndərir.

Token nə qədər müddətə etibarlıdır?

Bunu hər giriş üçün ayrıca təyin edirsiniz: 5 dəqiqə, 15 dəqiqə, 1 saat, 8 saat, 24 saat, 1–5 il və ya müddətsiz. Müddətsiz tokenlər məxfi açar yenilənənədək və ya giriş deaktiv edilənədək etibarlıdır.

Hansı məlumatları əldə edə bilərəm?

Nəqliyyat vasitələri (/vehicles, /tracker), qruplar (/groups), coğrafi zonalar (/geozones), hər nəqliyyat vasitəsi və gün üzrə iş vaxtları (/workinghours) və xəbərdarlıq cədvəlindəki hadisələr (/events). Öz nəqliyyat vasitələriniz və sizə baxış icazəsi verilənlər görünür.

İnterfeys vasitəsilə portaldakından daha çox məlumat görə bilərəmmi?

Xeyr. Görünürlük və sahələrə verilən icazələr portaldakı ilə eynidir. Şəxsi səfərlər gizlədilir.

Neçə sorğuya icazə verilir?

Hər giriş üçün dəqiqədə 7 və saatda 30 sorğu. Bu hədd aşıldıqda interfeys HTTP 429 cavabı verir və Retry-After vasitəsilə gözləmə müddətini bildirir.

İnterfeys məlumatları hansı formatda təqdim edir?

JSON formatında; vaxt göstəriciləri UTC saat qurşağında ISO-8601 formatındadır. İnterfeys OpenAPI 3.1 üzrə təsvir olunduğundan tərtibatçılar avtomatik olaraq müştəri proqramları yarada bilərlər.

Bir neçə tətbiq qoşa bilərəmmi?

Bəli. Hər tətbiq üçün ayrıca giriş yaradın; hər istifadəçi üçün ən çox beş giriş mümkündür. Hər girişin öz icazə dairələri, etibarlılıq müddəti və sorğu limiti var və hər birini ayrıca deaktiv etmək olar.

Biricon IT Services dəstəyi

Nəqliyyat vasitələrinizin məlumatlarını mövcud sistemlərə inteqrasiya etmək istəyirsiniz, amma haradan başlayacağınızı bilmirsiniz? Biz inteqrasiyanın planlaşdırılmasında, sinxronlaşdırma tapşırıqlarının hazırlanmasında və uyğun sorğu intervallarının seçilməsində sizə kömək edirik.

İndi əlaqə saxlayın

9 noyabr 2026 tarixinə olan məlumat. Funksiyalar və sorğu limiti dəyişə bilər; müştəri portalındakı təsvir əsas götürülür.