ÜTS web servisleri nasıl çalışır?
ÜTS, TÜBİTAK BİLGEM tarafından geliştirilen ve TİTCK tarafından işletilen bir sistemdir. Firmaların kendi yazılımlarından bildirim yapabilmesi için "Takip ve İzleme Web Servis Tanımları Dokümanı" ile tanımlanan REST servisleri sunar. Bu doküman uts.saglik.gov.tr üzerinde güncellenerek yayınlanır.
- Mimari: Standart REST servisleri, JSON veri formatı.
- Kimlik doğrulama: Her isteğin HTTP başlığına
utsTokenetiketiyle Sistem Token eklenir. - Servis kalıbı: Bildirimler
…/UTS/bildirim/{tür}/eklebiçimindeki uç noktalarla yapılır (ör.uretim,ithalat,verme,alma,utsdeTanimsizYereVerme). İptal, paket ve "kabul edilecek tekil ürün sorgula" servisleri de vardır. - Ortamlar: Canlı ortam ve
utstest.saglik.gov.trtest ortamı. Test ortamında ayrı firma kaydı ve ayrı token gerekir.
Sistem Token
Sistem Token, firmanın imza yetkilisi tarafından e-imza veya mobil imza ile ÜTS uygulamasından alınan entegrasyon anahtarıdır. Menü yolu: Kullanıcı → Sistem Kullanıcısı Tanımlama İşlemleri → Sistem Tokeni Al. Ayrıntılar için ÜTS Sistem Token nasıl alınır? rehberine bakın.
Token, firmanız adına ÜTS'ye bildirim yapma yetkisi verir. E-posta ile paylaşmayın, kaynak koduna gömmeyin; UzmanUTS'de şifreli olarak saklanır ve arayüzde gösterilmez.
Temel JSON alan kodları
| Kod | Anlamı | Not |
|---|---|---|
UNO | Ürün numarası | Barkod numarası (GS1'de GTIN); en fazla 23 karakter |
LNO | Lot / batch numarası | En fazla 20 karakter |
SNO | Seri / sıra numarası | En fazla 20 karakter |
URT | Üretim tarihi | YYYY-AA-GG |
SKT | Son kullanma tarihi | Yalnızca biri verilirse diğeri raf ömründen hesaplanır |
ADT | Adet | Lot takipli ürünlerde |
BRK | Barkod kuruluşu | GS1, HIBCC veya UTS |
SIP | Alt ürün listesi | Sistem/işlem paketleri için |
UzmanUTS bu servisleri sizin yerinize kullanır
ÜTS web servislerine kendi yazılımınızdan bağlanmak; bildirim türü seçimi, ön doğrulama, kuyruk, yeniden deneme, hata kodlarının yorumlanması ve servis değişikliklerinin takibi gibi sürekli bakım gerektiren bir geliştirme işidir. UzmanUTS bu katmanı hazır sunar: ERP'nizdeki belgeleri yalnızca okuyarak doğru bildirimi oluşturur ve firmanızın Sistem Token'ı ile ÜTS'ye gönderir. Sizin tarafınızda kod yazmanız gerekmez.
Kendi geliştirmeniz mi, UzmanUTS mi?
| İş | Kendi yazılımınızla doğrudan ÜTS | UzmanUTS |
|---|---|---|
| Bildirim türü seçimi | Sizin kodunuz | Otomatik |
| Ön doğrulama (kayıt, stok, SKT) | Sizin kodunuz | Hazır |
| Kuyruk ve yeniden deneme | Sizin kodunuz | Hazır |
| Hata kodlarının yorumlanması | Sizin kodunuz | Türkçe açıklama |
| Gelen verme takibi | Ayrı geliştirme | Gelen Kutusu ile hazır |
| Servis değişikliklerine uyum | Sizin bakımınız | Bizim bakımımız |
Sık sorulan sorular
ÜTS web servisleri hangi teknolojiyle çalışır?
ÜTS'nin takip ve izleme servisleri standart REST servisleridir; veri formatı JSON'dur. Kimlik doğrulama, her isteğin HTTP başlığına eklenen utsToken değeriyle yapılır.
ÜTS test ortamı var mı?
Evet, utstest.saglik.gov.tr. Test ortamı canlı ortamla aynı işlevlere sahiptir; ancak orada da ayrıca firma kaydı yapılması ve ayrı bir Sistem Token alınması gerekir.
Kendi yazılımımızı doğrudan ÜTS'ye bağlamak yerine neden UzmanUTS?
Doğrudan entegrasyonda bildirim türü seçimi, ön doğrulama, hata kodu yorumlama, kuyruk, yeniden deneme, gelen verme takibi ve mevzuat kaynaklı servis değişikliklerini sizin yönetmeniz gerekir. UzmanUTS bunları hazır sunar; ERP'nizi yalnızca okuyarak bildirimleri kendisi oluşturur, sizin kod yazmanız gerekmez.
Sistem Token süresi dolarsa ne olur?
ÜTS yetki hatası döndürür. UzmanUTS bu durumu tespit eder, bildirimleri kuyrukta bekletir ve sizi uyarır; yeni token tanımlandığında gönderim kaldığı yerden devam eder.