Araç Takip API Entegrasyonunda Geç ve Tekrar Gelen Kayıtlar

Bir dağıtım aracının bağlantısı geri geldiğinde geçmiş hareketlerin peş peşe gelmesi, aracın o anda bütün bu noktalardan geçtiğini göstermez. Benzer biçimde iki sorguda aynı satırın görülmesi, iki ayrı saha olayı yaşandığı anlamına gelmeyebilir. Sorun çoğu zaman “API çalışıyor mu?” sorusundan daha ayrıntılıdır: Veriyi alan şirket yazılımı hangi zamanı esas alıyor ve tekrar okuduğu kaydı nasıl tanıyor?

Bu yazı, ERP, TMS ve BI ekipleri için bir kayıt inceleme ve yeniden işleme dosyasıdır. Genel araç takip API entegrasyonu rehberini tamamlar. Aşağıdaki zaman çizelgesi ve testler varsayımsaldır; gerçek müşteri sonucu veya ARVETRAK'ta hazır bir “otomatik mükerrer temizleme” modülü vaadi değildir.

ARAÇ TAKİP API VERİSİNDE OLAY ZAMANI VE ALINMA ZAMANI NEDEN AYRILIR?

Olay zamanı, cihazın olayı hangi anda kaydettiğini; alınma zamanı, sunucunun kaydı ne zaman aldığını anlatır. Şirketinizin entegrasyon yazılımının veriyi okuduğu üçüncü bir zaman da bulunabilir. Bu üç anı tek “tarih” sütununda birleştirmek gecikmenin hangi aşamada oluştuğunu gizler.

ARVETRAK'ın kamuya açık API veri sözlüğünde recorded_at cihaz olay zamanı, received_at sunucu alış zamanı olarak açıklanır. Bununla birlikte her uç noktanın örnek yanıtı aynı alanları içermez. Örneğin konum geçmişi örneğinde recorded_at görülür; received_at bütün yanıtlarda varmış gibi bir eşleştirme kurulmaz. Projede gerçekten dönen alanlar ayrıca doğrulanır.

Bu örnekte olaydan sunucuya fark 15 dakika, sunucudan ERP okumasına fark 2 dakika, toplam fark ise 17 dakikadır. Bu bir hizmet hedefi değildir. Negatif zaman farkı görülürse “çok hızlı aktarım” sonucu çıkarılmaz; saat, saat dilimi ve alan tanımı kontrol edilir.

UTC ZAMAN DAMGASIYLA YEREL SAAT NASIL KARŞILAŞTIRILIR?

API dokümanı zamanları UTC / ISO 8601 olarak tanımlar. UTC değeri ile ekrandaki Türkiye saatini doğrudan çıkarmadan önce ikisini aynı zaman temeline çevirin. Ham zaman damgasını koruyun; kullanıcıya gösterilecek yerel saat ayrı bir gösterim olsun. İşletmenin gece yarısı vardiyası ile UTC takvim günü aynı aralığı temsil etmeyebilir.

ALINMA ZAMANI YANITTA YOKSA NE YAPILIR?

Olmayan alanı üretmeyin. Kendi sorgulama zamanınızı “entegrasyonun okuma zamanı” olarak kaydedebilirsiniz; bunu sunucunun ilk alış zamanı diye adlandıramazsınız. Gecikmenin hangi aşamada oluştuğu kanıtlanamıyorsa inceleme dosyasında bu sınırı açık bırakın.

GEÇ GELEN, TEKRAR GELEN VE DÜZELTİLEN KAYIT NASIL AYRILIR?

Aynı araç için gelen benzer satırları hemen silmek de hepsini yeni olay saymak da hatalı sonuç üretebilir. Önce kaydın temsil ettiği şeyi belirleyin: ham konum örneği mi, kontak olayı mı, hesaplanmış seyahat mi, yoksa şirketinizde oluşturulacak bir iş emri mi?

Aşağıdaki tablo bir entegrasyon tasarım örneğidir. Dar ekranda yatay kaydırılabilir.

ARAÇ TAKİP API ENTEGRASYONUNDA MÜKERRER İŞLEM NASIL ÖNLENİR?

“Aynı veri yeniden alınsa da aynı iş etkisinin tekrar oluşmaması” teknik olarak idempotent işleme diye anılır. Operasyon karşılığı nettir: aynı kontak kaydı ikinci kez okunduğunda ikinci bakım işi, ikinci teslimat bildirimi veya ikinci maliyet satırı açılmaması.

Bunun için her kaynakta kullanılabilecek tek bir evrensel anahtar yoktur. Belgelendirilmiş sabit olay kimliği varsa kapsamı ve benzersizliği doğrulanır. Kamu API örneğinde bir event_id alanı gösterilmiyorsa varmış gibi davranılmaz. Teknik ekip, veri türüne uygun eşleştirme ve çakışma kuralını proje içinde tasarlar ve test eder. Yalnız araç + saniye ikilisi, aynı saniyede farklı olaylar olabileceği için her durumda yeterli değildir.

Ham kaydın alınması, işlenmesi ve şirket yazılımında aksiyon oluşturulması ayrı durumlar olarak izlenmelidir. Bir bağlantı hatası tam kayıt tamamlanırken oluşmuşsa yeniden deneme öncesinde işlemin gerçekleşip gerçekleşmediği kontrol edilir. Tekrar satırını görünmez biçimde silmek yerine kaynak ilişkisi, işlem sonucu ve varsa inceleme notu saklanır.

KONUM GEÇMİŞİ SORGUSUNDA SINIRLAR VE SAYFALAMA NEDEN ÖNEMLİDİR?

Konum geçmişi dokümanında başlangıç ve bitiş zamanları dâhil olarak tanımlanır. Bir sorguyu 08.00–09.00, sonrakini 09.00–10.00 kurduğunuzda sınırdaki 09.00 kaydı iki sorguda da görülebilir. Bu, tek başına cihazın iki kayıt gönderdiğini göstermez. Örtüşme, eksik veri riskini azaltmak için bilinçli seçilebilir; alıcı sistem bu tekrar okumayı yönetmelidir.

Aynı dokümana göre seçilen aralıktaki en yeni konum noktaları kendi içinde artan zaman sırasıyla döner; has_more doğruysa daha eski aralık sorgulanır. Dolayısıyla “artan sıralı geldi, bütün geçmişi aldık” sonucu çıkarılmaz. Rapor uç noktalarının page/per_page yapısı ile konum geçmişinin zaman aralığı davranışı birbirine karıştırılmaz. Güncel istemci sınırları kontrol edilir; dokümandaki örnek rakam bütün müşterilere sabit taahhüt sayılmaz.

HTTP 429 GELDİĞİNDE VERİ EKSİK Mİ SAYILIR?

429 hız sınırına ulaşıldığını anlatır; boş sonuçla veya “olay yok” cevabıyla aynı değildir. Bekleme ve yeniden deneme planı uygulanır, tamamlanmayan aralık açık iş olarak tutulur. 401/403 yetki sorunları ve lisans dönemi sınırları da ayrı nedenlerdir. Yeni anahtar veya IP ile sınırı aşmak yerine yetkili proje sorumlusuyla kapsam netleştirilir.

ERP ENTEGRASYONUNDA YENİDEN İŞLEME NASIL TEST EDİLİR?

Önce test ortamında küçük, kişisel veri içermeyen bir örnek küme kullanın. Gerçek araçta bağlantıyı kesmek, anahtarı değiştirmek veya üretim işlerini tetiklemek bu rehberin testi değildir. Entegrasyonu teslim eden ve kullanan ekip aşağıdaki sonuçları birlikte değerlendirebilir:

1. Normal akış: Sıralı üç örnek kayıt için beklenen üç iş sonucu oluşur.
2. Tekrar okuma: Aynı örnek küme yeniden işlendiğinde yeni iş sonucu sayısı artmaz; tekrar okuma izi görünür.
3. Geç olay: Eski zamanlı bir örnek sonradan eklendiğinde geçmiş değerlendirilir; güncel durum geriye gitmez.
4. Kesilen işlem: Bir adım yarıda kaldığında hangi kayıtların tamamlandığı anlaşılır; yeniden deneme çift etki üretmez.
5. Sınır kontrolü: İki sorgunun ortak bitiş/başlangıç kaydı, ayrı bir yeni olay sayılmaz.

Bu maddeler gerçekleşmiş test sonucu değildir. Kabul dosyasında kullanılan veri kümesi, zaman aralığı, beklenen sonuç, görülen sonuç, sorumlu ve açık hata bulunmalıdır. Genel kurum/tedarik kapsamı için araç takip teknik şartname rehberi başlangıç noktasıdır; buradaki odak yalnız geç ve tekrar kayıtların iş etkisidir.

GEÇ VE TEKRAR GELEN ARAÇ TAKİP VERİSİ HAKKINDA MERAK EDİLENLER

ARAÇ TAKİP ENTEGRASYON PROJESİNİN KAPSAMI NASIL NETLEŞTİRİLİR?

ARVETRAK; cihaz, yazılım, SIM, montaj, bayi ve destek bileşenlerini birlikte ele alan araç takip ve filo operasyon platformudur. Entegrasyon görüşmesine “API istiyoruz” cümlesinin yanında hangi kurumsal aksiyonun üretileceğini ve yanlış tekrarın işletmeye neye mal olabileceğini ekleyin. Cihaz verisiyle ERP işlem kaydının sorumluları baştan belli olsun.

Araç takip sistemi fiyatları karşılaştırılırken cihaz ve yazılım bedelinin yanında API erişimi, geliştirme, test, izleme ve sonradan değişecek iş kurallarının kapsamı görüşülür. Daha çok veri almak yerine doğru kaydın doğru iş etkisini üretmesi hedeflenir.