ÜTS bildirimlerini ERP'nizden ya da bir entegrasyon yazılımından otomatik göndermek istiyorsanız ilk ihtiyacınız olan şey Sistem Token'dır. Token olmadan web servis çağrıları yetki hatasıyla reddedilir. İyi haber şu ki token almak, doğru kişi doğru ekrana ulaştığında birkaç dakikalık bir iştir. Bu rehberde süreci, test ortamı farkını ve token'ı güvenle yönetmenin yollarını anlatıyoruz.
Sistem Token nedir?
ÜTS'nin tüm takip ve izleme işlevleri standart REST servisleri olarak sunulur ve veri formatı JSON'dur. Bu servislerde kimlik doğrulama, kullanıcı adı ve şifre ile değil, Sistem Token ile yapılır. Token, firmanın imza yetkilisinin e-imza veya mobil imza ile ürettiği bir entegrasyon anahtarıdır.
Pratikte token, “bu yazılım şu firma adına ÜTS'ye bildirim yapabilir” anlamına gelir. Bu yüzden token ile gönderilen her bildirim, ÜTS açısından firmanızın kendi işlemidir. Token'ı bir şifre kadar, hatta daha dikkatli korumanız gerekir.
Token firma (kurum) bazındadır. Birden fazla ÜTS kurumunuz varsa (ör. farklı vergi numaralı şirketler) her biri için ayrı token alınır. UzmanUTS'de bu kurumları tek panelden, her biri kendi token'ıyla yönetebilirsiniz.
Token'ı kim alabilir?
Sistem Token'ı firmanın imza yetkilisi alır. İşlem e-imza veya mobil imza gerektirdiği için, imza yetkilisinin e-imzası ya da mobil imzası hazır ve geçerli olmalıdır.
Firmanın ÜTS'de kaydı henüz yoksa önce firma kaydının tamamlanması gerekir. Bunun için ÜTS firma kaydı nasıl yapılır rehberimize bakabilirsiniz.
Canlı ortamda Sistem Token alma adımları
- Giriş yapın: İmza yetkilisi, e-imza veya mobil imza ile utsuygulama.saglik.gov.tr adresinden ÜTS'ye giriş yapar.
- Doğru firmayı seçin: Birden fazla firmada yetkiniz varsa “Hesap Değiştir” ile token alınacak firmaya geçin. Yanlış hesapta alınan token, bildirimlerin başka bir kurum adına gitmesine ya da yetki hatalarına yol açar.
- Menüye gidin: Kullanıcı → Sistem Kullanıcısı Tanımlama İşlemleri → Sistem Tokeni Al. Eski dokümanlarda bu adım “Sistem Token'ı Üret” olarak geçer.
- İmzalayın: Ekranda gösterilen metni e-imza veya mobil imza ile imzalayın.
- Kopyalayın ve tanımlayın: Üretilen token'ı kopyalayıp entegrasyon yazılımınıza tanımlayın. Token'ı e-posta, mesajlaşma uygulaması veya ortak klasör üzerinden düz metin olarak paylaşmaktan kaçının.
Menü adları ÜTS sürümleriyle değişebilir. Yukarıdaki yol resmi web servis dokümanına ve sektör duyurularına dayanır; ekranda farklı bir adlandırma görürseniz “Sistem Kullanıcısı” veya “Token” ifadelerini arayın.
Test ortamında token alma
ÜTS'nin bir de test ortamı vardır: utstest.saglik.gov.tr. Sektör duyurularına göre test ortamı, üretim (canlı) ortamla aynı işlevlere sahiptir. Ancak iki ortam birbirinden bağımsızdır:
- Test ortamında ayrıca firma kaydı yapılması gerekir.
- Test ortamı için ayrı bir Sistem Token alınır; canlı ortam token'ı test ortamında, test token'ı canlı ortamda çalışmaz.
Test ortamı, yeni bir entegrasyonu canlıya almadan önce bildirim türlerini, hata senaryolarını ve iptal akışlarını denemek için idealdir. UzmanUTS kurulumunda da ilk bildirimler ÜTS test ortamında denenir; canlıya geçmeden önce kendi verinizle sonucu görürsünüz.
| Canlı ortam | Test ortamı | |
|---|---|---|
| Adres | utsuygulama.saglik.gov.tr | utstest.saglik.gov.tr |
| Firma kaydı | Gerçek firma kaydı | Ayrıca yapılır |
| Token | Canlı token | Ayrı test token'ı |
| Bildirimlerin etkisi | Gerçek stok ve hukuki kayıt | Deneme amaçlı, gerçek kaydı etkilemez |
Token nasıl kullanılır? utsToken başlığı
Token, ÜTS web servislerine yapılan her çağrının HTTP başlığına (header) utsToken etiketiyle eklenir. Başlık yoksa veya token geçersizse ÜTS yetki hatası döndürür. Gövdede ise bildirimin JSON alanları yer alır: UNO (ürün numarası), LNO (lot), SNO (seri), URT (üretim tarihi), SKT (son kullanma tarihi), ADT (adet) gibi.
Servis adresleri .../UTS/bildirim/verme/ekle, .../UTS/bildirim/alma/ekle gibi bir kalıp izler. Güncel host adı ve servis listesi için her zaman uts.saglik.gov.tr'de yayımlanan güncel “Takip ve İzleme Web Servis Tanımları Dokümanı”nı esas alın; doküman zaman zaman güncellenir ve bazı servis adresleri değişebilir. ÜTS web servisleri hakkında ayrıntılar ÜTS web servisleri sayfamızda.
Token ile neler yapılabilir?
Token tanımlandıktan sonra yazılımınız, ÜTS'nin web servisleri üzerinden kullanıcı ekranında yapabildiğiniz bildirim ve sorgu işlemlerinin büyük bölümünü otomatik yürütebilir:
- Giriş bildirimleri: üretim ve ithalat bildirimleri.
- El değiştirme: verme, alma, ÜTS'de tanımsız yere verme ve tanımsız yerden iade alma; paket ekleme, paket verme ve paket alma.
- Çıkış: ihracat, mahrecine iade, HEK/zayiat ve imha/bertaraf.
- Geri çekme: geri çekme verme, geri çekme alma ve ıslah bildirimleri.
- İptaller: ilgili bildirimlerin iptal servisleri.
- Bekleyen işlemler: “Kabul Edilecek Tekil Ürün Sorgula” ve “Kabul Edilecek Paket Sorgula” servisleriyle size yapılmış, henüz almadığınız vermeler.
Son madde özellikle önemlidir: Gelen vermeleri düzenli çekip alış belgelerinizle eşleştirmek, askıdaki ürün sorununun en etkili çözümüdür. Ayrıntı için askıdaki ürünler ve stok mutabakatı rehberine bakın.
Birden fazla firma veya şube için token yönetimi
Grup şirketlerinde, farklı vergi numaralı bayilerde veya ayrı ÜTS kurumu olarak kayıtlı şubelerde her kurum için ayrı token alınır. Burada iki noktaya dikkat edin:
- Kurum ile depo ayrımı: Aynı ÜTS kurumunun depoları arasındaki transfer için ÜTS bildirimi gerekmez. Firma kendisine verme yapamaz; denerseniz
UTS-H108hatası alırsınız. Farklı ÜTS kurumları arasındaki transfer ise verme ve alma bildirimiyle yapılır. - Token ile belge eşleşmesi: Her ERP belgesinin hangi kurumun token'ıyla gönderileceği net tanımlanmalıdır; aksi hâlde bildirim yanlış kurum adına gider.
UzmanUTS'de birden fazla ÜTS kurumunu tek panelden, her biri kendi token'ıyla yönetebilir; şube ve depo bazlı kullanıcı yetkisi tanımlayabilirsiniz.
Token güvenliği için öneriler
Token, firmanız adına bildirim yapma yetkisi taşıdığı için bir sızıntı; yanlış bildirimlere, stok tutarsızlıklarına ve denetimde açıklaması zor kayıtlara yol açabilir. Önerilerimiz:
- Şifreli saklayın: Token'ı kaynak kodun içine, düz metin yapılandırma dosyalarına veya paylaşılan tablolara yazmayın.
- Erişimi sınırlayın: Token'ı yalnızca entegrasyon sunucusu ve yetkili birkaç kişi görebilmeli.
- Kayıt tutun: Token ile hangi bildirimlerin, ne zaman ve hangi belgeden gönderildiğini değiştirilemez bir işlem günlüğünde tutun.
- Personel değişikliğinde gözden geçirin: İmza yetkilisi veya entegrasyondan sorumlu kişi değiştiğinde token'ın yenilenmesini değerlendirin.
- Ortamları ayırın: Test ve canlı token'larını karıştırmamak için ayrı yapılandırmalar kullanın.
UzmanUTS token'ları şifreli saklar, iletişimi TLS ile yapar, rol bazlı yetki ve silinemez işlem günlüğü sunar. Ayrıntılar güvenlik sayfamızda.
Token alma adımında takılırsanız yalnız değilsiniz: UzmanUTS kurulumunda token alma desteği ücretsiz hizmetin bir parçasıdır. Ekibimiz ekran paylaşımıyla imza yetkilinize eşlik eder ve token'ı güvenle sisteme tanımlar. Demo talep ederek süreci birlikte planlayabiliriz.
Sık karşılaşılan sorunlar ve çözümleri
| Sorun | Olası neden | Ne yapmalı? |
|---|---|---|
| Menüde “Sistem Tokeni Al” görünmüyor | Giriş yapan kişi imza yetkilisi değil veya yanlış firma hesabı seçili | İmza yetkilisiyle giriş yapın; “Hesap Değiştir” ile doğru firmaya geçin |
| Web servis yetki hatası veriyor | utsToken başlığı eksik, token yanlış kopyalanmış veya başka ortama ait | Başlık adını ve token'ı kontrol edin; test token'ını canlıda kullanmadığınızdan emin olun |
| Bildirimler beklenmeyen firma adına görünüyor | Token yanlış firma hesabında alınmış | Doğru firmada yeni token alıp yazılımı güncelleyin |
| Test ortamında token alınamıyor | Test ortamında firma kaydı yok | utstest.saglik.gov.tr üzerinde ayrıca firma kaydı yapın |
| E-imza imzalama adımında hata | E-imza sürücüsü, kart okuyucu veya imzalama aracı sorunu | E-imza sağlayıcınızın güncel sürücülerini kurun ya da mobil imzayı deneyin |
| Bildirim gönderildi ama sorguda görünmüyor | “Ayrıntılı Sorgula” ekranında son bir saatteki işlemler görünmez | Bir sonraki saatin başında tekrar kontrol edin; tekrar göndermeyin, mükerrer hata alırsınız |
Token geçerlilik süresi ve yenileme kuralları hakkında resmi metinlerde net bir bilgiye ulaşamadık. Token'ın çalışmayı bıraktığını fark ederseniz yeni token alıp yazılımınızı güncellemeniz en hızlı çözümdür. Web servislerden dönen hata kodlarının anlamı için ÜTS hata kodları sözlüğüne bakabilirsiniz.
Token'ı aldıktan sonra
Token hazır olduğunda sıradaki iş, ERP'nizdeki belgelerin ÜTS bildirimlerine doğru eşlenmesidir: hangi fatura verme, hangisi tanımsız yere verme, hangisi ihracat olacak; lot ve seri bilgisi hangi alandan gelecek? ÜTS entegrasyonu sayfamızda bu eşlemenin nasıl kurulduğunu, entegrasyonlar sayfasında desteklenen ERP'leri bulabilirsiniz. ÜTS'yi genel hatlarıyla tanımak isterseniz ÜTS nedir rehberi iyi bir başlangıçtır.
Sık sorulan sorular
ÜTS Sistem Token'ı kim alabilir?
Firmanın imza yetkilisi alır. İşlem e-imza veya mobil imza ile yapılır; birden fazla firmada yetkiliyseniz önce Hesap Değiştir ile doğru firmaya geçmelisiniz.
Sistem Token hangi menüden alınır?
utsuygulama.saglik.gov.tr'ye e-imza ile giriş yaptıktan sonra Kullanıcı → Sistem Kullanıcısı Tanımlama İşlemleri → Sistem Tokeni Al yolu izlenir ve ekrandaki metin imzalanır.
Test ortamı için ayrı token gerekir mi?
Evet. utstest.saglik.gov.tr test ortamında ayrıca firma kaydı yapılır ve ayrı bir Sistem Token alınır. Canlı ve test token'ları birbirinin yerine kullanılamaz.
Token web servis çağrısına nasıl eklenir?
Her çağrının HTTP başlığına utsToken etiketiyle eklenir. Başlık yoksa veya token geçersizse ÜTS yetki hatası döner.
Token'ın geçerlilik süresi ne kadar?
Resmi metinlerde token geçerlilik süresine dair net bir bilgiye ulaşamadık. Token çalışmayı bırakırsa yeni token alıp yazılımınıza tanımlamanız önerilir.
Kaynaklar
- TÜBİTAK BİLGEM – ÜTS Takip ve İzleme Web Servis Tanımları Dokümanı (Rev.30)
- Massiad – ÜTS Takip ve İzleme Web Servis Tanımları Dokümanı güncellendi
- TİTCK – Ürün Takip Sistemi (ÜTS) sayfası
Bu içerik bilgilendirme amaçlıdır; hukuki görüş değildir. Mevzuat değişebilir, işlem öncesinde güncel resmi metinleri kontrol edin.