KolayBi için iki ayar bloğu vardır: Sandbox ve Canlı. Her blok kendi api anahtarını, kanal bilgisini ve isteğe bağlı adresini taşır. Test Ortamı işareti bloğu bir bütün olarak seçer; boş blokta diğerine düşülmez. Bağlantı kontrolü bir oturum alınabildiğini sınar ve belge göndermez.
Hangi alanlar girilir?
Ayar ekranında alanlar ortama göre iki gruba, bir de ortak gruba ayrılır. Hesabı KolayBi'den almak sizin ile sağlayıcı arasındaki iştir; aşağıdaki tablo kantar tarafında doldurulacak alanları gösterir.
| Alan | Ne işe yarar? | Zorunlu mu? |
|---|---|---|
| Test Ortamı (Sandbox) işareti | Hangi bloğun kullanılacağını seçer. | Hayır |
| Sandbox ve Canlı API anahtarı | Ortam başına ayrı, gizli alan. | Seçili ortam için evet |
| Sandbox ve Canlı kanal | Ortam başına ayrı kanal bilgisi. | Seçili ortam için evet |
| Sandbox ve Canlı API adresi | Boşsa ortamın varsayılan adresi kullanılır. | Hayır |
| Belge Ön Eki | İsteğe bağlı üç harf; boşsa şirket varsayılanı. | Hayır |
| Para Birimi | Belgeye yazılır; boş bırakılamaz. | Evet |
| Zaman Aşımı ve Yeniden Deneme Sayısı | İstek bekleme süresi ve okuma sorgularının tekrar hakkı. | Hayır |
Api anahtarı şifre türünde, gizli bir alandır. Yeniden deneme sayısı yalnızca salt okuma sorgularına uygulanır; belge gönderen çağrılar bu ayardan bağımsız olarak bir kez denenir.
Sandbox ve Canlı: blok birlikte seçilir
KolayBi'de her ortamın api anahtarı ve kanalı ayrıdır. Yanlış eşleşme, yanlış ortama belge basmak demektir. Bu yüzden kantar tek bir kimlik çifti tutmaz: Test Ortamı işareti anahtarı, kanalı ve adresi birlikte seçer. İşaret açıksa Sandbox bloğu, kapalıysa Canlı bloğu kullanılır. Seçili blokta api anahtarı ya da kanal boşsa, para birimi boşsa gönderim başlamaz ve eksik alan söylenir. Boş bloktan diğer bloğa düşülmez, çünkü sessiz bir geri düşüş belgeyi başka ortamın kimliğiyle keserdi. Bağlantı kontrolü, önizleme ve gönderim aynı bloğu kullanır; yani kontrolün hangi ortamı sınadığını işaret belirler.
Adres alanı ne kabul eder?
Adres alanları isteğe bağlıdır; boşsa ortamın hazır adresi kullanılır. Doldurursanız dört kural işler: adres https olmalı, sağlayıcının kendi alan adı altında olmalı, localhost ya da IP adresi olamaz ve seçili ortamla uyuşmalıdır. Test işaretliyken canlı adres ya da işaret kapalıyken sandbox adresi girilmişse sürücü kurulamaz ve ağa hiçbir istek çıkmaz.
Oturum ve bağlantı kontrolü
Gönderimden önce api anahtarıyla bir oturum alınır. Oturum bilgisi yalnız bellekte tutulur, diske yazılmaz. Okuma sorgularında oturum düşerse bir kez yeniden giriş yapılır ve sorgu bir kez tekrarlanır; ikinci reddedilişte işlem durur. Gönderim çağrılarında yeniden giriş yapılmaz.
Bağlantı kontrolü önce ayar eksiğine bakar, eksik yoksa bir oturum almayı dener ve boş olmayan bir oturum alınabildiğini görür. Başka hiçbir şey yapmaz: belge göndermez, eşleştirme sorgusu çalıştırmaz. Bu nedenle başarılı bir kontrol, gönderimin de geçeceği anlamına gelmez. Gönderimin geçtiği adımlar ana rehberdeki sırada ve eşleştirme kuralları eşleştirme yazısında anlatılıyor.
Önizleme ile ayarı sınamak
Önizleme, ayar bütünlüğünden sonra durur. Yani eksik bir api anahtarı, boş bir kanal ya da boş para birimi önizlemede de yakalanır; bunun için KolayBi'ye hiçbir istek gitmez. Önizleme belge göndermez ve kayıt açmaz. KolayBi belgeyi kendisi ürettiği için ekranda yerel bir önizleme XML'i çıkmaz; önizleme alan eşlemesinin taslağını ve belgeye taşınamayacak dolu alanların adlarını gösterir. Cari ve ürün kimlikleri gönderim anında çözüldüğü için önizlemede henüz gerçek kimlik yoktur.
Ayar sırasında sık yapılan hatalar
- Anahtarı yanlış bloğa yazmak. Sandbox anahtarı Canlı bloğuna girilirse işaret kapalıyken gönderim bu anahtarla denenir. Her anahtarı kendi bloğuna yazın.
- Kanalı boş bırakmak. Kanal zorunludur ve api anahtarı gibi ortam başına ayrıdır; boşsa gönderim başlamaz.
- İşareti açık unutmak. Canlıya geçerken Test Ortamı işareti kapatılmazsa Sandbox bloğu kullanılmaya devam eder.
- Adresi gereksiz yazmak. Adres alanı boşken ortamın hazır adresi kullanılır; yalnız sağlayıcı farklı bir adres bildirdiyse doldurun.
- Zaman aşımını çok düşük tutmak. Yanıt beklenirken süre dolarsa istek kesilir; gönderim çağrısında bu durum kaydın açılıp açılmadığının bilinmemesi sonucunu doğurur.
Kimlik reddedilirse
Bağlantı kontrolünde oturum alınamazsa kontrol başarısız sayılır. Bu durumda önce seçili bloğun anahtarını ve kanalını, ardından Test Ortamı işaretini kontrol edin.
Kurulum sırası önerisi
Önce Sandbox bloğunu doldurup Test Ortamı işaretini açın ve bağlantı kontrolünü çalıştırın. Sonra Canlı bloğunu doldurun ve işareti kapatın. Ön ek ayarının nasıl çalıştığı için numara ve ön ek yazısına bakın. Kantarda entegratör ayarının genel yeri için e-İrsaliye kantar entegrasyonu yazısı, seçenekleri karşılaştırmak için Kantar e-İrsaliye entegratörleri yazısı var.
Ortam işareti tek bir seçimdir ama üç alanı birlikte seçer: api anahtarı, kanal ve adres.
Sık sorulan sorular
Test Ortamı işareti ne yapar?
İşaret, hangi ayar bloğunun kullanılacağını seçer. İşaretliyse Sandbox bloğunun api anahtarı, kanalı ve adresi birlikte kullanılır; işaretli değilse Canlı bloğu kullanılır. Seçili blok eksikse diğer bloğa düşülmez ve gönderim başlamaz.
API adresini kendim yazabilir miyim?
Adres alanı isteğe bağlıdır ve boş bırakılırsa ortamın varsayılan adresi kullanılır. Yazarsanız adres https ile başlamalı ve sağlayıcının kendi alan adı altında olmalıdır; localhost ve IP adresi kabul edilmez. Ortam işaretiyle uyuşmayan bir adres gönderimi başlatmaz.
Bağlantı kontrolü başarılı ama gönderim hata verirse ne yapmalıyım?
Bağlantı kontrolü yalnızca bir oturum alınabildiğini sınar, belge göndermez. Gönderim sırasında eşleştirme, numara ya da alan eşleme adımları ayrıca çalışır; hata iletisi hangi adımın takıldığını söyler. Kayıt bulunamadı iletileri için eşleştirme yazısına bakın.
Seçili bloğun kanal bilgisi boşsa ne olur?
Gönderim ağa çıkmadan durur ve eksik ayar operatöre bildirilir. Api anahtarı da kanal bilgisi de seçili ortam için dolu olmalıdır; diğer ortamın değerleri bu eksiği kapatmaz.
STEQAR, KolayBi'nin yanı sıra başka e-İrsaliye entegratörleriyle de çalışır; EDM Bilişim, Turkcell e-Şirket, Orkestra e-Faturacım, Veriban, e-Logo, QNB eSolutions, eKüpSoft, Digital Planet, Nilvera ve VBT bu seçenekler arasındadır. Farkları Kantar e-İrsaliye entegratörleri yazımızda karşılaştırdık.