# FormPilot uygulama entegrasyonu v1 Durum: geliştirme sürümü; üretime dağıtılmadı. API uygulamadan bağımsızdır. ERP, pazaryeri, yapay zekâ uygulaması ve muhasebe sistemleri aşağıdaki ortak sözleşmeye veri gönderebilir. GİB, SGK veya Trendyol için hazır, canlı test edilmiş bağlayıcı bulunmaz. Bir resmî beyanı onaylama/gönderme işlemi bu API'nin parçası değildir. ## Kurulum ve erişim PostgreSQL + sunucuda bağımsız `FORMPILOT_JOB_ENCRYPTION_KEY` (32 rastgele baytın base64 karşılığı) gerekir. Anahtar sabit kalmalıdır; kaybolursa eski kuyruk içeriği çözülemez. Kod anahtar yokken entegrasyon yollarını açmaz. Her replika aynı anahtarı kullanmalıdır. Yedekleme/anahtar saklama politikası operatöre aittir. Worker uygulamayla birlikte başlar. Proxy yükleme sınırı 100 MB multipart dosyayı kabul edecek biçimde ayarlanmalıdır. Üretimde kuyruk büyüklüğü/disk ve OCR maliyetini izleyin. Eklenti > Uygulama bağlantıları > API anahtarı yönetimi bölümünde anahtar oluşturulabilir/iptal edilebilir. API'de `X-API-Key` başlığını kullanın. Anahtarı yalnızca uygulamanızın sunucusunda saklayın. Anahtar 30 gün sonra sona erer. Anahtar üretmek/iptal etmek, `Authorization: Bearer ` gerektirir; uygulama anahtarı başka anahtar üretemez. `POST /keys` gövdesinde yetkiler seçilir: `imports:write`, `documents:write`, `matches:write`, `jobs:read`, `jobs:delete`. Varsayılan yalnızca imports:write/jobs:read. `DELETE /keys/{id}` iptal eder. Anahtarlar aynı hesabın işlerine erişir; bir hesap içinde uygulama bazında ayrı veri alanları henüz yoktur. Ayrı müşteriler ayrı FormPilot hesapları kullanmalıdır. ## Yollar — /api/integrations/v1 | Yöntem / yol | İşlem | |---|---| | POST /imports | Yapılandırılmış alanları ve tabloları kuyruğa alır | | POST /documents | multipart `file` dosyasını kuyruğa alır | | POST /matches | `{fields:[{key,label}],documents:[{name,text}]}` için bölümlü eşleştirme işi | | GET /jobs/{id} | Durum, ilerleme ve tamamlandıysa `result` | | DELETE /jobs/{id} | İş ve sonucunu siler; çalışan işi bir sonraki kontrol noktasında durdurur | Yazma yolları `Idempotency-Key` ister (8–100 harf/rakam/altçizgi/tire). İşlemi göndermeden önce bu kimliği uygulamanızda kaydedin. Ağ hatasında aynı anahtar ve aynı gövde ile tekrar gönderin: aynı iş döner. Aynı anahtarla farklı gövde 409 verir. Tekilleştirme işin 24 saatlik saklama süresi boyunca geçerlidir. Uygulamalar arası teslimat için kendi kalıcı kayıt/iş durumunuzu tutun; API nihai hedefe teslim edildiğini iddia etmez. Başarılı oluşturma: `202 {"id":"UUID","state":"pending"}`. Durumlar pending/running/completed/failed. En az 3 saniye aralıkla sorgulayın. Başarısız işler otomatik yeniden denenmez. OCR sağlayıcısına giden çağrılar maliyet oluşturmuş olabilir. İptal, başlamış bir sağlayıcı çağrısını geri alamaz. 45 dakika ilerleme vermeyen çalışan iş failed/WORKER_INTERRUPTED olur; temiz kuyruktaki bekleyen işler sunucu yeniden açılınca devam eder. ## İki yönlü akış 1. Kaynak uygulama alan/tablo veya dosyayı API'ye gönderir. 2. Eklentide iş kimliğiyle veri yüklenir. Kullanıcı hedef formu ve sütunları seçer, önizlemeyi onaylar. 3. Ters yönde eklentide `Açık web formunu API’ye aktar` seçilir. Görünür, hassas kontrol filtrelerini geçen dolu alanlar açık onayla kuyruğa gönderilir. Kaynak uygulama iş kimliğiyle `GET /jobs/{id}` çağırır ve JSON'u kendi alanlarına eşler. Web dışa aktarımı şu an standart form alanlarıyla sınırlıdır; tüm sayfayı veya satır tablosunu dışa aktarmaz. 4. Sonuç işlem bitince silinebilir; 24 saat sonra API erişimi kapanır ve etkin worker temizler. ```json { "version": 1, "name": "ERP sipariş kaydı", "fields": [ {"label": "Firma", "value": "Örnek Ticaret AŞ"}, {"label": "Sipariş No", "value": "SIP-2026-0001"} ], "tables": [{ "headers": ["Ürün", "Miktar", "Birim Fiyat"], "rows": [["A4 Kâğıt", "10", "120,00"]] }] } ``` Para, tarih, stok kodu ve kimlik değerleri string olarak taşınır; API bunları tahmin etmez veya vergi hesabı yapmaz. Kaynaktaki mükellef/şirket/dönem ilişkisini kaynak uygulama ve kullanıcı doğrular. Belge içeriği talimat olarak yürütülmez. Kullanıcı gövdesinden hedef URL çağrılmaz; dış sisteme otomatik POST yoktur. ## Kaynak bütçesi ve maliyet 8 belge sınırı kaldırıldı. Çalışma alanı toplam 2 milyon çıkarılmış karakter; metadata koruması en fazla 2.000 kaynak. Dosya başına 100 MB, PDF başına 1.000 sayfa. PDF'ler 10 sayfalık bölümlerle işlenir; çok yoğun bölümler daha küçüğe ayrılır. Tek sayfa sağlayıcı sınırını aşıyorsa iş açık hatayla durur. Görsel OCR 10 MB, Office arşivlerinin açılmış boyut ve işlem süresi korumaları devam eder. Eski DOC/XLS/PPT yolu halen 60.000 karakter sınırındadır. Bütün biçimlerin aynı büyük dosya kapasitesine sahip olduğu iddia edilmez. Eşleştirme 24.000 karakterlik kaynak parçalarını en fazla 48.000 karakterlik isteklerde birleştirir; tüm parçaları inceler, çelişki bulursa alanı boş bırakır. Her ayrıştırma/eşleştirme bölümü mevcut işlem kotasından düşer (form kotasının 3 katı). Büyük iş çok sayıda bölüm tüketebilir; sınırsız veya ücretsiz OCR değildir. İş yarıda kota nedeniyle durursa kısmi cevap tamamlanmış sonuç gibi verilmez. Başarılı bölümlerin kullanım sayacı geri alınmaz. Standart HTML tablolarda kaynak başına 10.000 satır / 100 sütun; her aktarım bölümü 20 satırdır. Önizleme 100 satırlık sayfalara ayrılır. Bölüm sonunda durdurulabilir; aynı açık panel/sekmede, 5 dakikalık devam tokenı geçerliyken devam edilebilir. Hedef değişirse durur. Panel kapanması, sekme değişimi veya kısmi hata sonrasında otomatik kaldığı yerden devam edilmez; önce hedef kayıtlar incelenmelidir. Özel canvas/grid ve masaüstü tabloları için ayrıca bağlayıcı gerekir. Test edilen sentetik aktarım 45 satırdır; 10.000 satır kapasitesi gerçek ERP'de henüz yük testinden geçmedi. Kuyruk hesap başına en fazla 20 iş / yaklaşık 256 MB şifreli veri tutar. API 60 istek/dakika, dosya yükleme 20/saat sınırındadır. Bu sınırlamalar kaynak korumasıdır; müşteriye göre üretim kapasitesi ayrıca planlanır. ## GİB / SGK GİB resmî e-Beyan kılavuzu entegrasyon başvurusu, tanımlı IP ve Bearer API anahtarı gerektirir: https://ebeyan.gib.gov.tr/entegrator/files/e-Beyan%20Entegrasyon%20K%C4%B1lavuzu.pdf . Beyanname türü ve sürümü belirlendikten sonra resmî şemaya özel bağlayıcı/test ortamı gerekir. SGK için belirli hizmet/API erişimi henüz araştırılmadı veya bağlanmadı. Genel API'ye bu kurumlara ait veri yüklenmesi, kuruma gönderim yapıldığı anlamına gelmez. Node istemcisi: `sdk/formpilot-client.mjs`. Gerçek uygulama anahtarlarını istemci tarafı JavaScript'e veya kaynak kontrolüne koymayın.