API anahtarı yönetimi

Anahtarı üretmek#

Anahtar firma başına üretilir. Aynı yazılım adıyla birden çok anahtar açılabilir; firma başına ya da yazılım başına bir sınır yoktur.

Kim, nereden açar#

1. Firmanın kendisi, müşteri paneli. Ayarlar → Web Servis Tanımları ekranında Yazılım Adı listesinden yazılımınızı seçin (yoksa Diğer) ve Web Servis Tanımı Ekle düğmesine basın. Fatura iptaline izin ver kutusu işaretli gelir; yazılımınız fatura iptal etmeyecekse kaldırın. Ekranı firma sahibi görür; başka bir kullanıcı için dış API anahtar yönetimi yetkisi verilmelidir. Bu ekranda üretilen anahtarın kapsamı, üreten kullanıcının yetkilerinden geniş olamaz.
2. İş ortağı (bayi) paneli. Firma Bilgileri → Firma Tanımları’ndan firmayı açın ve Web Servis Tanımları sekmesine geçin. Sekmeyi bayi hesabının sahibi görür; başka bir bayi kullanıcısı için aynı yetki gerekir. Yalnız yönettiğiniz firmaların anahtarlarına erişirsiniz.
3. YouSoft ekibi. Yönetim panelinden de anahtar üretebilir, yenileyebilir ve açıp kapatabilir.

Üretimde verilen iki değer#

• X-Api-Key: gizli değildir, isteğin kimliğini söyler. Ekranda Anahtar alanında durur.
• Güvenlik anahtarı (secret): imzayı üretir ve hiçbir isteğe konmaz. Ekranda yalnız üretim anında ve her Güvenlik Anahtarını Yenile işleminden sonra bir kez gösterilir; kutuyu kapatınca ya da sayfayı yenileyince bir daha görüntülenemez, listede yalnız maskeli hâli kalır. Kaybolursa yenilenir.

Yazılım Adı yalnız bir etikettir: anahtarı panelde ve işlem geçmişinde adlandırır, yetkiyi değiştirmez.

Çok müşterili entegrasyon#

Bir yazılım evi ya da bayi birden çok firma adına çalışıyorsa her müşteri firma için ayrı anahtar kullanır. Bayi panelinde Firma Tanımları’ndan firmayı seçin, Web Servis Tanımları sekmesinde anahtarı üretin ve anahtar çiftini (X-Api-Key ile güvenlik anahtarı) firma kaydınızla birlikte saklayın. Bir anahtar yalnız kendi firmasına erişir; başka firmanın kaydı için 404 döner. Anahtarın hangi firmaya bağlı olduğunu GET /v1/me?include=firma ile doğrulayabilirsiniz (yanıtta firma_id ve firma gelir).

Bayi panelinde “müşteri” olarak listelenen şey firmadır. /v1/contacts o firmalar değil, anahtarın bağlı olduğu firmanın içindeki cari kartlardır (firmanın müşterileri ve tedarikçileri); yeni bir firmada hiç cari kart yoktur. Ayrım için Temel kavramlar.

Kapsamlar#

Kapsam, anahtarın taşıdığı yetki kodudur (örneğin EFatura.GidenKutusuIzleyebilir). Her ucun hangi kapsamı istediği Uç haritasında yazar. Anahtarın kapsamları kartta Yetki Kapsamı altında salt okunur görünür.

• Varsayılan küme. Kapsam listesi verilmeyen anahtar varsayılan kümeyi alır: fatura düzenleme, gönderim, giden ve gelen faturaları listeleme ve indirme ile fatura iptali dahil.
• Fatura iptali kutusu. Panel ekranının seçtirdiği tek kapsam budur: Fatura iptaline izin ver kutusu varsayılan olarak işaretlidir; kaldırılırsa anahtar EFatura.IptalEdebilir kapsamını taşımaz. İptal geri alınamaz, iptal etmeyecek yazılım için kutuyu kaldırın. Müşteri panelinde anahtarı üreten kullanıcının iptal yetkisi yoksa kutu işaretsiz ve kapalı gelir, anahtar iptal kapsamı almaz; kartta Yetki Kapsamı gerçeği gösterir.
• Önceden üretilmiş anahtarlar. Bu değişiklikten önce tam varsayılan kümeyi taşıyan anahtarlara fatura iptali kapsamı eklendi. Kapsamı daraltılarak üretilmiş anahtarlar (müşteri panelinde sınırlı yetkili kullanıcının ürettikleri dahil) değişmedi.
• Dar kapsam. Yalnız okuma gibi dar bir kapsam gerekiyorsa anahtarı panelin kendi arka ucundan üretin ve kapsamlar listesini açıkça verin (aşağıdaki örnek). Listede saymadığınız kod anahtara girmez; iptal isteniyorsa EFatura.IptalEdebilir listede yazılır. kapsamlar ile iptal_yetkisi aynı istekte gönderilirse 400 validation_failed döner.
• Sonradan değişmez. Bir anahtarın kapsamı panelden ya da API’den değiştirilemez; farklı kapsam gerekiyorsa yeni anahtar üretilir. Yukarıdaki iptal geçişi tek seferlik bir veri düzeltmesiydi.
• Eksik kapsam. Kapsamı olmayan uç 403 forbidden döner ve eksik kapsam kodunu yanıta yazmaz: yanıtı okuyan biri anahtarın yetki haritasını çıkaramasın diye.

POST /api/firma-api-anahtarlari
{"yazilim_evi": "DIGER", "kapsamlar": ["EFatura.GidenKutusuIzleyebilir"]}

Bu uç /v1 ailesinden değil panelin kendi arka ucudur: anahtar ve imza değil, firma kullanıcısının panel oturumu ister. Bayi panelindeki karşılığı POST /api/firmalar/{firma_id}/api-anahtarlari ucudur. yazilim_evi sabit bir listedendir: LOGO, MIKRO, NETSIS, ETA, ZIRVE, NEBIM, AKINSOFT, LUCA, DIGER. Liste dışı değer ya da taşınamayan bir kapsam kodu 400 validation_failed alır. kapsamlar verilmezse varsayılan küme yazılır; "iptal_yetkisi": false ondan yalnız fatura iptalini çıkarır (verilmezse true sayılır).

Güvenlik anahtarını yenileme#

Yenileme, anahtar kartındaki Güvenlik Anahtarını Yenile düğmesiyle yapılır; müşteri, bayi ve YouSoft ekranlarında aynıdır. X-Api-Key aynı kalır, yeni bir güvenlik anahtarı üretilir ve ekranda bir kez gösterilir. Anahtarın kapsamı, durumu ve iptal nedenleri değişmez.

Eski güvenlik anahtarı 24 saat daha geçerlidir#

Eski değer yenileme anından itibaren 24 saat daha kabul edilir; süre, yenileme isteği sunucuya ulaştığında başlar. Bu pencere, yeni değeri entegrasyonunuza yerleştirene kadar kesintiyi önler: sürenin içinde iki değerle de imzalanan istek aynı yetkiyle çalışır ve eski değer süre dolunca kendiliğinden geçersiz olur.

Aynı anda en çok iki değer geçerlidir: güncel olan ve bir önceki. 24 saat dolmadan ikinci kez yenilerseniz ilk yenilemeden önceki değer hemen geçersiz olur; ilk yenilemede verilen değer ise yeni bir 24 saat boyunca bir önceki olarak kalır. Anahtar kapalıyken iki değer de reddedilir.

Anahtar sızdıysa#

Güvenlik anahtarının ele geçirildiğinden şüpheleniyorsanız bu sırayı izleyin. Yalnız X-Api-Key sızdıysa acil bir işlem gerekmez: güvenlik anahtarı olmadan imza üretilemez.

1. Anahtarı hemen kapatın. Anahtar kartında iptal nedeni alanını doldurun (müşteri ekranında Müşteri İptal Nedeni), sonra Servis aktif seçeneğini kapatın. Kapatma bir sonraki istekten itibaren etkilidir; kapalı anahtar 401 alır.
2. Sızan değeri geçersiz kılın. Tek bir yenileme yetmez, çünkü eski değer 24 saat daha geçerli kalır. İki yol var: Güvenlik Anahtarını Yenile düğmesine art arda iki kez basıp yalnız ikinci seferde gösterilen değeri kullanın (ikinci yenileme sızan değeri bir önceki konumundan da düşürür); ya da yeni bir anahtar açın ve eskisini kapalı bırakın. Panelden açılan yeni anahtar varsayılan kapsamı alır; eski anahtar özel kapsamla açıldıysa yenisini de aynı kapsamlar listesiyle üretin.
3. Yeni değeri yerleştirin. Yeni güvenlik anahtarını gizli deponuza yazın (saklama önerileri), entegrasyonunuzu güncelleyin ve GET /v1/me ile doğrulayın. Eski anahtarı yeniden açacaksanız önce ikinci yenilemeyi yaptığınızdan ya da 24 saatin geçtiğinden emin olun: pencere anahtar kapalıyken de işler ve açıldığında hâlâ sürüyorsa önceki değer yeniden kabul edilir.
4. Kullanımı inceleyin. Kartta Son kullanım zamanına bakın: kendi entegrasyonunuzun son başarılı isteğinden sonraki bir zaman görünüyorsa anahtar başkası tarafından kullanılmıştır (kapalı anahtarın reddedilen istekleri bu zamanı değiştirmez). Giden belge, gelen belge ve taslak ayrıntı panellerindeki işlem geçmişinde anahtarla yapılan işlemler Yazılım Adı (dış API) biçiminde görünür (örneğin Diğer (dış API)); şüpheli işlemleri oradan bulun.

Güvenlik anahtarını saklama#

• Ortam değişkeninde ya da gizli deposunda (secret manager) tutun; kaynak koda, sürüm kontrolüne, mobil ya da tarayıcı istemcisine koymayın (neden).
• Günlüğe yazmayın. İstek başlıklarını olduğu gibi kaydeden araçlarda (vekil sunucu, izleme araçları) X-Api-Signature değerini maskeleyin: imza 5 dakika boyunca aynen yeniden gönderilebilir.
• E-posta ya da sohbetle düz metin olarak paylaşmayın; ortam başına (üretim, deneme) ayrı anahtar kullanın.
• Güvenlik anahtarı 43 karakterlik bir metindir ve imzada olduğu gibi kullanılır: HMAC anahtarı, bu metnin UTF-8 baytlarıdır. Base64 olarak çözmeyin.

Anahtarı kapatmak ve yeniden açmak#

Anahtarlar Web Servis Tanımları ekranında kart olarak listelenir. Her kartta Yazılım Adı, Aktif ya da Pasif rozeti, Güvenlik Anahtarını Yenile düğmesi, Anahtar, maskeli Güvenlik Anahtarı, Yetki Kapsamı, iki iptal nedeni alanı, Servis aktif seçeneği ve Son kullanım zamanı bulunur. Ekranda anahtarı silen bir düğme yoktur; kapatılan anahtar listede Pasif olarak kalır.

Kapatma#

Kapatma, kartın alt kısmındaki Servis aktif seçeneğiyle yapılır. Seçenek değiştirildiği anda kaydedildiği için önce neden alanını doldurun: neden boşsa işlem reddedilir. İki neden alanı iki ayrı özneye aittir:

• Müşteri İptal Nedeni: müşteri talebiyle kapatma. Her ekranda düzenlenir; müşteri ekranında kapatmak için bu alan zorunludur.
• Servis İptal Nedeni: hizmeti verenin (bayi ya da YouSoft ekibi) gerekçesi. Bayi ve YouSoft ekranlarında düzenlenir ve kapatmak için iki alandan en az biri yeterlidir; müşteri ekranında Servis İptal Nedeni (servis sağlayıcınız) olarak salt okunur görünür.

Yeniden açma#

Müşteri kendi kapattığı anahtarı kendisi açar. Servis İptal Nedeni dolu bir anahtarı, yani servis sağlayıcının kapattığı anahtarı müşteri açamaz: istek 403 forbidden alır ve hata iletisi bayiye başvurulmasını söyler. Bayi ve YouSoft ekibi kendi ekranlarından anahtarı açıp kapatabilir.

Sınırlar ve izleme#

• Tek firma. Her anahtar tek bir firmaya bağlıdır ve başka bir firmanın kaydına erişemez (çok müşterili entegrasyon).
• Deneme ortamı yok. Ayrı bir sandbox yoktur; her istek anahtarın firmasının gerçek verisine gider. Kapsam seçmeden açılan anahtar fatura düzenleyip gönderebilir. Denemelerde önce yalnız okuma kapsamlı bir anahtar kullanın ve yazma ya da gönderim yetkisini ancak o uçları denemeye hazır olduğunuzda verin.
• Süre. Anahtarın son_gecerlilik alanı vardır (süresizse null) ve dolu olan bir anahtar o tarihten sonra 401 alır; ancak bugün bu alanı belirleyen bir ekran ya da uç yoktur ve her anahtar süresizdir. Düzenli yenileme (24 saatlik örtüşmeyle) sizin tarafınızdaki bir pratiktir, sistem onu zorlamaz.
• Son kullanım. Kartta Son kullanım olarak görünür ve en çok dakikada bir güncellenir; dakikanın altında bir çözünürlük beklemeyin.
• Panel listesi. En yeni 100 anahtarı gösterir.
• IP kısıtı. Anahtarı belirli IP adreslerine bağlayan bir ayar yoktur.
• Hız. Anahtar başına dakikada 120 istek (anlık en çok 60), firmanın bütün anahtarlarının toplamı dakikada 300; XML ve PDF indirme uçlarında ayrıca daha dar bir kota ve firma başına aynı anda 4 indirme sınırı vardır. Ayrıntı Sorgu sözleşmesinde.