İTS REST API ve token: entegrasyona başlarken

Elle yapılan bildirim günde birkaç kutuda idare eder. Ama koli koli mal kabul eden bir depo, her gün yüzlerce kalem sarf yapan bir hastane ya da kendi yazılımını İTS'ye bağlamak isteyen bir üretici için yol web servislerinden geçer. Bu rehberde İTS'nin REST servislerine nasıl bağlanıldığını, token'ın nasıl alındığını ve entegrasyonda en sık takılan noktaları resmi kılavuzlara dayanarak anlatıyoruz.

SOAP'tan REST'e geçiş

İTS'nin eski SOAP servisleri its.saglik.gov.tr adresinde çalışıyordu ve 08.07.2022'de kapandı. 11.07.2022'den bu yana web servisleri REST mimarisiyle hizmet veriyor. SOAP'a göre yazılmış bir entegrasyon bugün çalışmaz; REST'e uyarlanmış olması gerekir.

İki ortam vardır:

• Canlı: https://its2.saglik.gov.tr
• Test: https://itstest2.saglik.gov.tr

Geliştirmeye her zaman test ortamında başlayın. Canlı ortamda gönderilen her bildirim gerçek bir stok hareketidir.

Bu yazıda dayandığımız resmi belgeler şunlar: REST servis kılavuzu (son okunan sürüm 31.05.2023), servis adres listesi (05.07.2022), token servis kılavuzu (28.03.2022) ve hata kodu listesi (12.09.2025).

Kimlik doğrulama ve GLN

İTS'de her paydaş GLN numarasıyla tanınır. Web servislerinde kimlik kullanıcı adı ve şifreyle doğrulanır. Burada bir kural var: Kullanıcı adının ilk 13 hanesi paydaşın GLN'si ile aynı olmalıdır. Uymazsa İTS 11039 "Kullanıcı adının ilk 13 hanesi GLN ile aynı olmalıdır" hatasını döner.

REST kılavuzundaki örnek kullanıcı adı 17 hanelidir: 86800010000110000. Bu örnekte ilk 13 hane, yani 8680001000011, paydaşın GLN'sidir.

GLN, bildirimlerin taraflarını da belirler. İTS yanlış satıcı GLN'si için 10301, yanlış alıcı GLN'si için 10302 kodunu döner; bildirilen GLN kayıtlarda yoksa 11003 gelir. Alıcı ya da satıcı deaktif durumdaysa 11904 ve 11905, işleme uygun paydaş türünde değilse 11906 ve 11907 kodları döner. Paydaş listesi referans servisini güncel tutmak bu hataları azaltır.

Token nasıl alınır ve yenilenir?

İTS REST servisleri Bearer token ile çalışır. Token servisi kılavuzunda üç uç nokta tanımlıdır:

• /token/app/token/ Kullanıcı adı ve şifreyle token alınır.
• /token/app/accesstoken/ Bir erişim token'ı ile bir yenileme (refresh) token'ı birlikte döner. Erişim token'ı 3600 saniye (1 saat), yenileme token'ı 86400 saniye (24 saat) geçerlidir.
• /token/app/refreshtoken/ Yenileme token'ıyla yeni bir erişim token'ı alınır.

Kılavuza göre yeni bir token aldığınızda eski token süresi dolana kadar geçerliliğini korur. Yani yeni token almak, elinizdeki eski token'ı hemen geçersiz kılmaz.

Pratikte izlenecek yol basittir: Token'ı alın, saklayın, süresi dolmadan yenileyin. Her istekten önce yeni token almak yerine elinizdeki token'ı süresi boyunca kullanmak hem daha düzenli hem de daha az istek demektir.

Token'ı güvenle saklamak

Token, sizin adınıza İTS'ye bildirim gönderebilen bir anahtardır. Birkaç basit kural işe yarar: Token'ı ve şifreyi uygulama kayıtlarına yazmayın, kullanıcıların tarayıcısına göndermeyin, şifreyi kaynak kodun içine gömmeyin. Kullanıcı ayrıldığında ya da şifre değiştiğinde eski bilgilerle çalışan bir süreç kalmadığından emin olun.

İstek ve cevap nasıl görünür?

REST servisleri JSON gövdeli HTTP POST istekleriyle çağrılır. Token, isteğin Authorization başlığında Bearer ön ekiyle gönderilir.

Başarılı bir bildirimde İTS iki şey döner:

• Bildirimin numarası (notificationId)
• Her ürün için ayrı bir cevap kodu (uc veya rc alanı)

Ürün bazındaki kod 00000 ise o ürün için işlem başarılıdır. Resmi listedeki karşılığı: "Ürün üzerinde gerçekleştirilen işlem başarılıdır." Başka bir kod, o kutu için bir sorun olduğunu gösterir.

İstek düzeyinde bir hata olduğunda cevapta fc ya da faultCode alanında 5 haneli bir hata kodu, fm alanında da açıklama yer alır. Kodların resmi anlamlarına hata kodları sayfasındaki arama aracından bakabilirsiniz.

Hata listesini okumak

Resmi hata listesi uzun, ama bazı aralıklar bir arada okunduğunda anlam kazanır. Örneğin 60001 ile 60008 arasındaki kodlar ürünün o anki durumunu söyler: üreticide, depoda, eczanede, sarf edilmiş ya da geri çekilmiş gibi. 60010 ile 60013 arasındaki kodlar ürünün iki paydaş arasında kalıp kalmadığını gösterir. 20009 ve 21003 ile 21016 arasındaki kodlar ise PTS paketleriyle ilgilidir. Bu kodları kullanıcıya ham hâliyle değil, anlaşılır bir açıklamayla göstermek destek yükünü azaltır.

Hangi servis ne işe yarar?

Servis adres listesi ve REST kılavuzunda tanımlı başlıca yollar şunlardır:

• Üretim ve ithalat: /product/app/supplynotification/
• Satış ve Satış İptal: /wholesale/app/dispatch/ ve /wholesale/app/dispatchcancel/
• Mal Kabul-Alım: /common/app/accept/
• Mal İade: /common/app/return/
• Mal Devir ve iptali: /common/app/transfer/ ve /common/app/transfercancel/
• İhracat ve iptali: /wholesale/app/export/ ve /wholesale/app/exportcancel/
• Deaktivasyon ve iptali: /common/app/deactivation/ ve /common/app/deactivationcancel/
• Eczane Satış ve iptali: /prescription/app/pharmacysale/ ve /prescription/app/pharmacysalecancel/
• Hastane Sarf: /consume/app/consume/
• Durum Sorgulama: /reference/app/check_status/
• Ürün Doğrulama: /reference/app/verification/
• PTS: /pts/app/SendPackage, /pts/app/GetPackage ve /pts/app/search

Bunların yanında İlaç, Paydaş, Ülke ve Cevap Kodu listelerini veren referans servisleri vardır. Bu listeleri düzenli çekmek, yanlış GTIN ya da yanlış GLN ile bildirim göndermenin önüne geçer.

PTS servislerinin kendi sınırları var: Paket en fazla 10 MB olabilir, yalnızca ZIP kabul edilir, tek seferde tek paket gönderilir, bir paket en fazla 100 kez alınabilir ve gönderici kendisine paket gönderemez. PTS ile paket göndermek Satış bildiriminin yerine geçmez.

dt alanı

Bazı servislerde bildirimin tipi dt alanıyla belirtilir. Kılavuzdaki örnekler: Üretim bildiriminde dt=M üretimi, dt=I ithalatı gösterir. İhracatta dt=X, ihracat iptalinde dt=C, deaktivasyonda dt=D, eczane satışında dt=S, ürün doğrulamada dt=V kullanılır. Eski işletme kılavuzuna göre SOAP servislerinde de M, I, S, D, X, F, V ve C gibi tip harfleri kullanılıyordu; bunların bir kısmı REST'te dt alanında sürüyor.

Adım adım: ilk entegrasyon

1. Hesabınızı hazırlayın. TİTCK'nın 15.11.2024 tarihli duyurusuna göre İTS kullanıcı hesabı işlemleri valilikler üzerinden dijital olarak yürüyor. Portal girişinde e-Devlet ile çok faktörlü doğrulama 21.12.2023'ten beri zorunlu.
2. Test ortamında token alın. https://itstest2.saglik.gov.tr üzerinde token servisini çağırın ve token'ı güvenli bir yerde saklayın.
3. Referans listelerini çekin. İlaç ve paydaş listeleriyle GTIN ve GLN kontrollerinizi kendi tarafınızda yapın.
4. Küçük bir bildirimle deneyin. Tek ürünlük bir bildirim gönderin; notificationId'yi ve ürün bazındaki cevap kodunu kaydedin.
5. Hata yönetimini kurun. Her ürünün cevap kodunu saklayın. 00000 dışındaki kodları gruplayıp kullanıcıya anlaşılır bir mesajla gösterin.
6. Token yenilemeyi otomatikleştirin. Erişim token'ı 1 saatte, yenileme token'ı 24 saatte dolar. Süre dolmadan yenileme yapın.
7. Canlıya geçin. Test senaryolarınız tamamlandığında aynı akışı https://its2.saglik.gov.tr adresine yönlendirin.

Performans ve kota

• Toplu çalışın. Kılavuz, kontrollerin toplu yapılmasını önerir.
• Transferden önce ayrıca doğrulama çağırmayın. Satış, mal alım gibi transfer servisleri ürünleri kendi içinde doğrular. Her transferden önce Ürün Doğrulama servisini çağırmak gereksiz yük oluşturur.
• Kotayı aşmayın. Fazla istekte İTS 30001 "Kota Değeri Aşılmıştır" kodunu döner.
• PTS sorgularında aralığı dar tutun. PTS arama servisinde tarih aralığı en fazla 31 gün olabilir.

Erişim kısıtları ve e-sertifika

Eczaneler İTS'ye yalnızca kayıtlı sabit IP adresinden erişebilir; aksi hâlde 11218 hatası alınır. Bu kısıtın eczane dışındaki paydaşlarda hangi kapsamda uygulandığını resmi kaynaklarda doğrulayamadık. Ayrıntılar için eczaneler için sabit IP rehberine bakın.

Nitelikli elektronik sertifika konusu da netleşmiş değil. 2009 tarihli eski işletme kılavuzu "gerektiğinde" nitelikli elektronik sertifika kullanılacağından söz ediyordu. Güncel REST kılavuzlarında ise yalnızca kullanıcı adı, şifre ve token anlatılıyor. Bugün herhangi bir işlemde e-sertifika istenip istenmediğini doğrulayamadık; entegrasyon öncesinde İTS'den teyit edin.

Sık yapılan hatalar

• Kullanıcı adı ile GLN'nin uyuşmaması. İlk 13 hane GLN değilse 11039 hatası gelir.
• Token süresini takip etmemek. Erişim token'ı 1 saat geçerlidir. Süresi dolmuş token'la gönderilen istekler işlenmez.
• Yalnızca bildirim numarasına bakmak. notificationId almak, her ürünün başarılı olduğu anlamına gelmez. Ürün bazındaki kodu kontrol edin.
• Sıra ve parti numarasını değiştirmek. Bildirimdeki değerler karekoddakiyle birebir aynı olmalı; dolgu karakteri eklenmemeli.
• PTS gönderimini bildirim sanmak. SendPackage karekod listesini taşır ama Satış bildirimi değildir. Bkz. PTS rehberi.
• Test ve canlı ortamı karıştırmak. Test ortamında gönderilen bildirim canlı stoğu etkilemez; canlıya geçince işlemi orada yapmanız gerekir.

Takıldığınız bir konuda İTS destek hattına ulaşabilirsiniz: its@saglik.gov.tr, 444 46 80.

Tracey ile entegrasyon yazmadan çalışmak

Kendi entegrasyonunuzu yazmak istemiyorsanız Tracey'yi değerlendirebilirsiniz. Tracey, İTS web servisleriyle entegre çalışan bulut bir İTS programıdır; üretim, ithalat, mal alım, satış, ihracat, iade, alış iade, sarf, deaktivasyon ve PTS işlemlerini tarayıcıdan yaparsınız. XML ve PTS desteği, güncel paydaş ve ilaç listeleri, karekod okuyucuyla koli ve palet okutma ile geçmiş bildirim raporları da buna dahildir. ERP ya da muhasebe programınızla entegrasyon arıyorsanız DataStil kurumsal çözümlerine https://datastil.com adresinden bakabilirsiniz; Tracey'yi görmek için demo talep edebilirsiniz.