Başlangıç

Kimlik Doğrulama

API anahtarı oluşturma, Authorization başlığı, kapsamlar ve ek korumalar.

Son güncelleme: 21 Eylül 2026 · Sözleşme sürümü 1.0.0

Talep ile aktarımda ve sonuç okuma uçlarında her istek bir API anahtarıyla doğrulanır. Anlık bağlantı yönteminde anahtar kullanılmaz; kimlik paylaşılan sır ve HMAC imzasıyla doğrulanır (bkz. Servis sözleşmesi).

Dikkat

API anahtarı firma verisine tam erişim sağlar. Anahtarı kaynak kodda, sürüm kontrolünde (GitHub, GitLab vb.) ya da günlüklerde tutmayın; ortam değişkeninde saklayın. Sızdığından şüpheleniyorsanız panelden anında iptal edin.

Anahtar oluşturma

Firma sahibi Profil → Entegrasyon → Yeni anahtar düğmesine basar.
Ad ve erişim düzeyi seçilir: Tam erişim (talep ile aktarım — teslimat rehbere/işe/taslağa yazar) ya da Salt okunur (yalnız sonuç okuma). İsteğe bağlı olarak son kullanma tarihi ve IP izin listesi girilir.
Anahtar bir kez gösterilir. Kopyalayıp BT ekibine güvenli bir kanaldan iletin; sonradan tekrar görüntülenemez.

Anahtar öneki ortamı belirtir: canlıda mai_live_, test ortamında mai_test_. Bir ortamın anahtarı diğerinde çalışmaz.

İstek başlığı

Anahtar yalnız Authorization: Bearer başlığında ve HTTPS üzerinden gönderilir; sorgu parametresinde kabul edilmez.

curl https://mutabakat.ai/api/v1/me \
  -H "Authorization: Bearer $MAI_API_KEY"

Başarılı yanıt firmayı, anahtarın kapsamlarını ve paket bilgisini döner. Hatalı ya da eksik anahtar 401 unauthenticated, iptal edilmiş anahtar 401 ve "API anahtarı iptal edilmiş." mesajı alır.

Kapsamlar

Kapsamlar erişim düzeyinden türer: Salt okunur anahtar yalnız *:read kapsamlarını, Tam erişim anahtarı hepsini taşır.

Kapsam	Ne yapar
`counterparties:read`	Cari rehberini okuma
`counterparties:write`	Cari listesi teslimatı (rehbere yazma)
`balance:read`	Bakiye mutabakatı kampanyalarını ve yanıtları okuma, Excel dışa aktarma
`balance:write`	Bakiye teslimatı (taslak kampanya açma)
`statements:read`	Ekstre dosyası/iş durumu ve sonuçları okuma, rapor indirme
`statements:write`	Ekstre teslimatı (sihirbazın "Şirketiniz ekstresi" kartına dosya)

Yetersiz kapsamla yapılan istek 403 insufficient_scope alır; yanıt mesajı gereken kapsamı belirtir.

Ek korumalar

IP izin listesi — anahtar bazında tanımlanabilir (tekil adres ya da CIDR). Liste dışından gelen istek 403 ip_not_allowed alır.
Yeni IP uyarısı — anahtar yeni bir IP adresinden ilk kez kullanıldığında firma sahiplerine e-posta gider.
İptal — panelden iptal edilen anahtar anında geçersiz olur; o anahtarın elindeki açık talepler serbest kalır.