Erişim için gerekenler
API erişimi tanımlanmış etkin bir firma ve geçerli API kimlik bilgileri gerekir. Anahtar kimliğiapiUserId, gizli değer secretKey olarak adlandırılır. Erişim bilgilerinizi yetkili hesap yönetiminden edinin.
Kimlik doğrulama
İsteklerde HTTP Basic kullanılır: kullanıcı adıapiUserId, parola secretKey değeridir. /health çağrısı kimlik doğrulaması gerektirmez.
apiUserId 24 karakterli onaltılık kayıt kimliğidir. Bozuk Base64, eksik ayraç/parola ve geçersiz kimlik 401 üretir. Bu cevapta WWW-Authenticate: Basic realm="Muhasip API", charset="UTF-8" başlığı bulunur. API anahtarını veya GİB/entegrasyon parolasını sorgu parametresine koymayın.
Örneklerdeki ortam değişkenleri
Örneklerde bu ortam değişkenleri okunur. Gerçek değerleri uygulama sunucunuzdaki ortam değişkenlerinden veya sır yöneticinizden sağlayın; kaynak kontrolüne eklemeyin.
Firma kapsamı
Firma kimlik bilgilerinden belirlenir.companyId, companiesId veya özel başlıkla başka firma seçilemez. Fatura, cari, banka hesabı, proje ve diğer ilişkili kimlikler aynı firma kapsamında olmalıdır. API anahtarının geçerli olması bir banka veya e-belge bağlantısının hazır olduğunu göstermez.
Modül izinleri
İzin listesi (scope) tanımlanmışsa ilgili muhasip:<modül>:read veya muhasip:<modül>:write izni gerekir. İzin adını işlem sayfasında bulabilirsiniz. Okuma ve yazma izinlerini ayrı tanımlayın; write izni tek başına read sağlamaz. scope boş veya tanımlanmamışsa anahtarın erişim yetkileri geçerlidir.
Fatura ve e-Arşiv ortak işlem uçlarında izin gövdedeki
type veya func değerine göre değişir. API yöneticisi modül iznini geçebilir; firma, ürün, IP veya kayıt sahipliğini geçemez.
IP kısıtı ve hatalar
IP listesi boşsa ek IP sınırı yoktur. Dolu listede normalize IPv4/IPv6 adresi birebir eşleşmelidir; CIDR/aralık desteklenmez. İsteği uygulama sunucunuzdan gönderirken onun çıkış IP’sini dikkate alın.401 kimlik, erişim süresi veya firma sorunu; 403 ürün, modül, IP veya kaynak sınırı sorunudur. Anahtar değiştirerek veya başka firma kimliği deneyerek bu sınırları aşmayın. Ortak kurallar · Hata yönetimi