API ve webhooklar
Belge yükleme ve okuma işlemleri REST API üzerinden mevcuttur. Hesap, klasör, etiket ve bağlantı yönetimi uygulamada kalır.
Anahtar
Ayarlar → Geliştiriciler sekmesinde oluşturulur. Anahtar, yalnızca oluşturma sırasında bir kere gösterilir — sonrasında artık gösterilmez, çünkü yalnızca parmak izi saklanır. Kayıp anahtar geri alınamaz, yeni bir tane oluşturulur ve eski silinir. Maksimum beş anahtar oluşturulabilir, her biri iki yıla kadar isteğe bağlı geçerlilik süresine sahip olabilir.
Her yeni anahtar için, hesap sahibine bir e-posta gönderilir; anahtar süresi dolmadan iki hafta önce de bildirim gönderilir. BKZ. E-posta ile Bildirim.
Anahtar, X-API-Key başlığında gönderilir.
API'nin Yeteneği
| İşlem | Açıklama |
|---|---|
POST /api/upload | Dosya yükleme işlemi seçenekleri: format, yön, tür, para birimi, şema, klasör, webhook |
POST /api/upload/url | Genel adres üzerinden aynı işlem; dosyayı kendimiz indiririz |
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 silme işlemi |
Excel ve PDF, sonuçta Base64 olarak gelir. Sonucu istemeyenler, includeResult=false gönderir, bu da sunucuda dönüşümü tasarruf ettirir.
OpenAPI formatındaki arayüz tanımı /api/docs adresindedir; anahtar ayarlarında bulabilirsiniz. Tanım, çalışan koddan üretilmektedir, bu nedenle API'nin ne yaptığına karşılık gelir.
API'den Gelen Belgelerde Kontrol
Gönderim öncesi kontrol, varsayılan olarak anahtar ile yüklenen belgeler için de geçerlidir: belge, uygulamada onay bekler ve webhook ancak onaydan sonra gönderilir. Ekranın önünde kimsenin bulunmadığı bir entegrasyon kuruyorsanız, Ayarlar → Gönderim Öncesi Kontrol'den API kanalı kaldırılabilir ya da kontrol devre dışı bırakılabilir.
MCP
AI ajanları için /api/mcp adresinde, aynı anahtar ile MCP sunucusu bulunmaktadır. Belgeleri okuyup arama yapabilir, yükleyemez; yükleme, ajanın kendisinin çalıştıracağı hazır bir komut döndürür.
Webhooklar
Durumu sorgulamak yerine, işlem tamamlandığında sonucu almak üzere bir adres belirleyin. Adres, Hesap genelinde Ayarlar → Geliştiriciler sekmesinde veya belirli bir yükleme için targetWebhookUrl parametresi ile ayarlanır. Ayarlardaki buton, test mesajı gönderir.
POST ile JSON gönderilir: belge tanımlayıcısı, dosya adı, format ve hedef formatta sonuç. Belge kontrolü geçerse veya tekrar işlenirse, ikinci bir webhook, düzeltme bayrağı (IsCorrection) ile gelir.
Mesaj imzalanmaz. Göndereni, adresinize kendi özel token'ınızı ekleyerek doğrulayın. Özel ağlara ait adresler reddedilir.
Webhook, tüm denemelere rağmen dört buçuk saat içinde ulaşmazsa, bir e-posta gelir. Tek bir kesinti sırasında yalnızca bir kez; sonraki başarısızlıklar aktivite kaydında yer alır. Webhook adresinde herhangi bir değişiklik olursa, bu değişikliği yapan kişi sizden farklıysa yine e-posta alırsınız.
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, sizin tarafınızdaki yanıta ek olarak aktivitede görünür; belge listesinde teslimat sonucuna dair bir simge bulunur.
Limitler
API'nin dakikada yapılan çağrılar için kendi tavanı yoktur; yükleme işlemleri kredi ile, dosya boyutu tarife göre ve belgede yirmi sayfa ile sınırlıdır. Reddedilme, nedenini belirten bir hata kodu ile 400 hatası olarak gelir. MCP sunucusu, saniyede on sorguyla sınırlıdır.