> ## Documentation Index > Fetch the complete documentation index at: https://docs.muhasip.pro/llms.txt > Use this file to discover all available pages before exploring further. # Ortak API kuralları > Kimlik, firma, IP, modül izinleri, cevaplar ve ortak sınırlar. ## İstekleri hazırlama İşlem sayfalarındaki istek örneklerini kullanın. API anahtarınızı hazırlamak, erişim koşullarını ve kayıt ilişkilerini öğrenmek için [kimlik ve izinler](/baslangic/kimlik-ve-izinler) rehberini izleyin. ## API izinleri ve IP kısıtı İzin listesi (`scope`) tanımlanmışsa en az bir geçerli `muhasip::read` veya `muhasip::write` izni gerekir. Liste boş veya tanımlanmamışsa anahtarın erişim yetkileri geçerlidir. Ayrıntılar [kimlik ve izinler](/baslangic/kimlik-ve-izinler) rehberindedir. | Modül değeri | Kaynak | | - | - | | `apps` | Firma uygulama listesi | | `invoice` | Fatura bağlantısı, belge ve eşitleme | | `bank` | Banka ve belgelenmiş çalışma alanı alt kaynakları | | `pos` | POS hesapları ve tahsilat | | `earsiv` | GİB e-Arşiv | | `marketplace` | Pazaryeri bağlantı ve siparişleri | | `oim` | Online işlem ayarları | | `todo` | Proje, görev, etiket ve durum | | `agenda` | Ajanda ve etiketleri | | `calendar` | Takvim | `read` ve `write` ayrı izinlerdir; yazma izni kendiliğinden okuma izni vermez. API yöneticisi modül işlemi izinlerini geçebilir; firma, ürün erişimi, kayıt sahipliği veya IP denetimini geçemez. İşlem durumunu okumak için işlemin ait olduğu modülde `read` **veya** `write` yeterlidir. İzin kontrolü yalnız HTTP yöntemine dayanmaz. Banka yenileme, fatura kontrol/aktarım ve eşitleme, otomasyon çalıştırma, pazaryeri özet/sipariş sorgusu `GET` olsa da **write** ister. Fatura işlem ucunda `type=invoiceInfo`; e-Arşiv işlem ucunda `func=getUserData|query|html|download` okuma izniyle kullanılabilir. Diğer belgelenmiş varyantlar yazma izni ister. Yan etkili GET işlemleri `HEAD` ile çalıştırılmaz; `405` döner. IP listesi boşsa adres kısıtı uygulanmaz. Dolu listede doğrulanmış istemci adresi, normalize edilmiş IPv4/IPv6 adreslerinden biriyle birebir eşleşmelidir. CIDR/aralık tanımı desteklenmez. Geçersiz liste, belirlenemeyen istemci adresi veya eşleşmeyen IP `403 API_IP_FORBIDDEN` üretir. API yöneticileri de bu denetime tabidir. ## Cevaplar ve kimlikler İşlemler çoğunlukla HTTP 200 döndürür; oluşturma için genel bir 201 standardı yoktur. `result`, `resultData`, `total`, `paginate`, `createData` gibi üst alanlar kaynak bazında farklıdır. İç içe hizmet durumu ile dış `status` aynı anlamı taşımaz. Kimlikler de kaynak bazında `id`, `_id`, `UUID`, `paymentId` veya `operationId` olabilir; birbirinin yerine kullanılmaz. ```json theme={null} { "status": true, "result": [] } ``` ```json theme={null} { "status": false, "code": "API_SCOPE_FORBIDDEN", "message": "API anahtarı bu işlem için yetkili değildir." } ``` Belgelenen hassas bağlantı cevaplarında parolalar ve gizli anahtarlar açık döndürülmez. GİB belge içeriği, cari/ödeme bilgileri gibi iş verilerini ayrıca koruyun; ham istek/cevapları genel uygulama loglarına yazmayın. Bu belgelerdeki bütün kimlikler, kişi alanları ve sır yer tutucuları temsilîdir. ## Hatalar | HTTP | Anlamı | | - | - | | 400 | Geçersiz alan, filtre, tarih veya zorunlu Idempotency-Key eksikliği | | 401 | API kimliği/parolası, erişim süresi veya firma erişimi uygun değil | | 403 | Erişim izni, IP kısıtı veya kayıt sahipliği isteğe izin vermiyor | | 404 | Firma kapsamında hedef kayıt bulunamadı | | 405 | İzin verilmeyen yöntem; yan etkili işlemlerin HEAD çağrısı dahil | | 406 | GİB bağlantısı veya oturumu kurulamadı | | 407 | Ortak erişim/alan adı kontrolü isteği reddetti | | 409 | İşlem devam ediyor, hedef kilitli veya aynı işlem anahtarı farklı içerikle kullanıldı | | 411 / 412 | Bazı mevcut iş koşulu veya hizmet hataları; kaynak rehberini okuyun | | 413 | Gövde boyutu sınırı; JSON cevap garanti değildir | | 422 | İş kuralı veya sağlayıcının kesin reddi | | 429 | Ortak hız sınırı; `status` alanı bu cevapta sayısaldır | | 502 | Mali sonucun belirsizliği; `retryable:false` ise otomatik tekrar yapılmaz | | 503 | İşlem kaydı veya hizmet kullanılamıyor; mali sonucu durum ucundan kontrol edin | Bazı alan doğrulama cevapları `result:[{type,joiType,path,label}]`, diğerleri `code/message` içerir. Bütün hatalarda aynı alanları beklemeyin. Bağlantı kopması veya JSON olmayan hata, mali işlemin hiç yapılmadığını kanıtlamaz. [İşlem takibi](/rehberler/islem-takibi) belgesindeki durumları değerlendirin. ## Sayfalama ve filtreler | Kaynak | İstek / varsayılan | Cevap | | - | - | - | | Görev/proje listesi | `page=1`, `limit=50`; en fazla 250 | `result`, `total` | | Görev/proje geçmişi | `page=1`, `pageSize=25`; en fazla 250 | `result.histories`, `result.historiesTotal`, `total` | | Ajanda | `page=1`, `limit=50`; en fazla 250 | `result`, `total` | | Diğer kaynaklar | İlgili referans | Sayfalamasız veya kaynağa özel | Her işlemin kendi sayfalama, sıralama ve filtre alanlarını kullanın. Belgelenmemiş bir parametre `400` ile reddedilebilir. Kimlik filtreleri metin olarak gönderilse de sunucu firma kapsamını ve kimlik türünü doğrular. Tarih-saat için açık saat dilimi olan ISO 8601, gün filtreleri için `YYYY-MM-DD` kullanın. ## Hız ve gövde sınırları İstek sınırı istemci IP’si başına **6 saniyede 100 istektir**. Sınır aşıldığında `429` döner; varsa `Retry-After` başlığına göre bekleyin. ```json theme={null} { "status": 429, "error": "Too Many Requests", "message": "Rate limit exceeded. Please try again later." } ``` `Retry-After` varsa değerlendirin. Finansal çağrıyı yalnız 429 veya zaman aşımı nedeniyle kendiliğinden yeniden göndermeyin. JSON/form istek gövdesi sınırı 10 MiB’dir; belge işlemleri daha dar sınırlar uygulayabilir. ## Mali işlemler ve tekrar çağrı Korunan mali işlemlerde kalıcı işlem kimliği, hedef kilidi ve gerektiğinde **Idempotency-Key** kullanılır. Bu başlık bütün CRUD isteklerinde genel bir zorunluluk değildir; ilgili kaynak ve [işlem takibi](/rehberler/islem-takibi) hangi çağrılarda gerektiğini açıklar. Tekrar cevapları güvenli makbuz ve sonuç kimlikleriyle sınırlıdır; ilk HTML/PDF veya bütün mali yanıtın birebir tekrarı vaat edilmez. Mali işlemin sonucunu işlem kimliğiyle takip edin; sonucu belirsiz bir isteği otomatik tekrarlamayın. Tutar, vergi ve kayıt ilişkileri için [muhasebesel işlem rehberini](/rehberler/muhasebe-akislari) okuyun. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.