API ve webhook'lar
Belge yükleme ve okuma işlemleri REST API üzerinden mevcuttur. Hesap, klasörler, etiketler ve bağlantıların yönetimi uygulama içinde kalır.
Anahtar
Ayarlar → Geliştiriciler sekmesinde oluşturulur. Anahtar bir kez görüntülenir, kurulum sırasında — daha sonra artık görünmez, çünkü sadece izi saklanır. Kaybolan anahtar geri yüklenmez, yeni bir anahtar oluşturulur ve eski silinir. Beş anahtar oluşturulabilir, her birinin isteğe bağlı geçerlilik süresi iki yıla kadar uzatılabilir.
Anahtar, X-API-Key başlığı ile gönderilir.
API'nin Yetenekleri
| İşlem | Açıklama |
|---|---|
POST /api/upload | Dosya yüklemesi seçeneklerle: format, yön, tür, para birimi, şema, klasör, webhook |
POST /api/upload/url | Aynısı halka açık bir adresten; dosyayı kendimiz indireceğiz |
GET /api/jobs | Filtreler ve sayfalama ile belge listesi |
GET /api/jobs/{id} | Durum, okunan veriler, bulgular ve hedef formatta sonuç |
GET /api/jobs/{id}/original | Yüklenen dosya |
DELETE /api/jobs/{id} | Çöp kutusuna gönderme |
Excel ve PDF sonuçları Base64 olarak gelir. Sonucu gerekmeyen, includeResult=false gönderir, böylece sunucuda dönüşümü atlar.
OpenAPI formatındaki arabirim tanımı /api/docs adresindedir; bağlantı anahtarlar ayarlarında bulunur. Tanım, çalışan koddan üretilir, bu nedenle API'nin ne yaptığını yansıtır.
API'den Gelen Belgelerin Kontrolü
Gönderim öncesi kontrol, varsayılan durumda anahtarla yüklenen belgeler için de geçerlidir: belge uygulamada onay bekler ve webhook yalnızca onaylandıktan sonra gönderilir. Ekranın başında hiç kimsenin olmadığı bir entegrasyon kuranlar, Ayarlar → Gönderim Öncesi Kontrol sekmesinden API kanalını kaldırabilir veya kontrolü kapatabilir.
MCP
AI ajanları için /api/mcp adresinde aynı anahtar ile MCP sunucusu bulunmaktadır. Belge okuma ve arama işlemlerini yapabilir, yükleme işlemini gerçekleştiremez; yükleme, ajanın kendisinin çalıştıracağı bir komut olarak döner.
Webhook'lar
Durumu sorgulamak yerine, sonuç hazır olduğunda alın. Adres, Hesap Ayarları → Geliştiriciler bölümünde ya da belirli bir yükleme için targetWebhookUrl parametresi ile ayarlanır. Ayarlarında bulunan buton test mesajı gönderir.
POST ile JSON gönderilecek: belge kimliği, dosya adı, format ve hedef formatta sonuç. Belge kontrolü geçerse veya yeniden işlenirse, webhook tekrar gelir ve düzeltme bayrağı (IsCorrection) taşır.
Mesaj imzalanmaz. Göndereni doğrulamak için adresinize kendi gizli belirtecinizi koyun. Özel ağlara ait adresler reddedilir.
Başarısız teslimatlar artan gecikme ile tekrarlanır, yaklaşık dört buçuk saat içinde on bir deneme yapılır. Her deneme, yanıtınızla birlikte aktivitede kaydedilir; belge listesinde teslimat sonucunu gösteren bir simge vardır.
Limitler
API'nin dakikada yapılacak çağrı sayısı için kendi üst sınırı yoktur; yükleme, kredilerle, dosya boyutu tarifeyle ve belge başına yirmi sayfa ile sınırlıdır. Reddetme, nedenini belirten bir kod ile birlikte 400 hatası olarak gelir. MCP sunucusu, saniyede on sorgu ile sınırlıdır.