Overview 6 Min. okuma süresi

Geliştiriciler için PaperOffice API'si: Kapsamlı kılavuz

Spesifikasyonun bulunduğu yer

Uç nokta spesifikasyonu, API kataloğundan canlı olarak oluşturulur. Makalelerden uç nokta listelerini kopyalamak yerine şu dosyaları kullanın:

  • AI istemcileri için kompakt indeks: https://api.paperoffice.ai/latest/docs/llms.txt
  • Tam referans: https://api.paperoffice.ai/latest/docs/llms-full.txt
  • OpenAPI 3.1: https://api.paperoffice.ai/latest/docs/openapi.json
  • Ajan becerisi: https://api.paperoffice.ai/latest/docs/skill.md
  • Postman koleksiyonu: https://api.paperoffice.ai/latest/docs/postman

Dokümantasyon yolları herkese açıktır ve token gerektirmez. Postman URL'sini Postman, VS Code veya Bruno'ya içe aktarın ve dokümantasyon sürümü değiştiğinde tekrar indirin. Üretim ortamının temel adresi https://api.paperoffice.ai/latest'tir; yalnızca geliştirme için /dev kullanın.

Bir AI kodlama asistanı ile hızlı başlangıç: llms-full.txt'nin adresini ona verin ve örneğin bir resim gönderen ve tanınan metni döndüren bir fonksiyon gibi ihtiyacınız olan fonksiyonu tanımlayın.

Kimlik doğrulama ve token türleri

Çoğu ürün uç noktası, Authorization başlığında bir bearer token gerektirir. Tokenları PaperOffice uygulamasında Hesap → API altında oluşturursunuz.

  • Sistem anahtarı (po_sk_): tam API erişimi ile sunucu-sunucu entegrasyonu. Tarayıcıda asla kullanmayın.
  • Kullanıcı tokeni (po_ut_): tek bir kullanıcının kapsamı, örneğin MCP için. Haklar kullanıcıya ve lisansa bağlıdır.
  • Grup tokeni (po_gt_): bir kullanıcı grubunun haklarını ve çalışma alanı beyaz listesini devralır.
  • Yayınlanabilir anahtar (po_pk_): tarayıcıda kullanım içindir. Her istek, anahtar sahibinin girdiği bir köken (origin) gerektirir; anahtarın toplam bütçesi tüketimi sınırlar ve silme, hesap yönetimi, anahtar yönetimi ve ödeme değişiklikleri engellenir. MCP için izin verilmez.

Token olmadan yalnızca spesifikasyon, sağlık kontrolü ve bağlantı testi gibi altyapı uç noktalarına erişilebilir. Token içermeyen bir ürün isteği, HTTP 401 yerine HTTP 403 ve TIER_RESTRICTED kodu ile yanıtlanır.

İşler: bekleme, anlık sorgulama ve sonuçlar

İşleme işler olarak çalışır. İş yolları handler___command deseni kullanır (üç alt çizgi ile), örneğin metin tanıma için POST /job/add/paperoffice_aiocr___generate. Nokta gösterimi JOB_CONFIG_INVALID ile reddedilir.

  • Varsayılan olarak, istek bağlantıyı bir süre tutar. İş zamanında tamamlanırsa sonucu doğrudan alırsınız. Aksi takdirde, bir iş kimliği ve bir anlık sorgulama adresi ile birlikte HTTP 202 alırsınız ve iş çalışmaya devam eder.
  • HTTP 202 bir hata değil, başarılı bir durumdur. Durum tamamlanana kadar her 5 ila 10 saniyede bir GET /job/get/{job_id} adresini anlık sorgulayın. Sonuç ardından job_result içinde bulunur.
  • client_wait=false ile iş kimliğini hemen alırsınız ve başlangıçtan itibaren anlık sorgulama yaparsınız.
  • Tüm yanıtlar JSON formatındadır. İstemciler yerelleştirilmiş mesaj metni yerine kararlı kod alanını okumalıdır.

Hesap → API → İş kuyruğu altında sıraya alınmış, çalışan ve tamamlanmış API işlerini görürsünüz. Tüm hata kodlarının tam listesi spesifikasyonda bulunur; tipik durumlar eksik veya geçersiz parametreler (400), eksik veya geçersiz token (401), yetersiz Credits (402), yasaklanmış eylem (403) ve çok fazla istek (429, Retry-After'a saygı gösterin) şeklindedir.

Başlangıç SLA: Bir iş ne zaman başlar

İsteğe bağlı processing_lane alanı, bir işin kuyrukta ne zaman başlayacağını kontrol eder, ne zaman biteceğini değil. client_wait, bağlantının sonucu bekleyip beklemeyeceğini kontrol eder; bu iki alan bağımsızdır.

processing_lane olmadan, çalışma alanının varsayılanı uygulanır; aksi takdirde en iyi çaba (best effort) kullanılır. Her plan, ek ücret olmadan en iyi çabayı içerir. Daha hızlı başlangıç şeritleri isteğe bağlıdır ve daha pahalıdır. Mevcut şeritler ve fiyatları API fiyat listesinden canlı olarak mevcuttur; detaylar API dokümantasyonundadır.

Webhooks

Webhook uç noktaları iş ve hesap olaylarını, örneğin job.completed, job.failed, job.progress ve belgeler, çalışma alanları ile görevler için olayları alır. Boş cüzdan veya iptal edilmiş anahtar gibi hesap bildirimleri webhook olayları değildir.

  • Payload'lar, X-Paperoffice-Signature başlığında HMAC-SHA256 ile imzalanır. İmza, webhook gizli anahtarınızla ham istek gövdesi üzerinden hesaplanır ve eşleşmezse istek reddedilir.
  • Webhook'lar API aracılığıyla kaydedilir, listelenir, güncellenir, test edilir ve silinir.

Faturalandırma ve kullanım

API çağrıları, uygulamayla aynı olan kuruluşun paylaşılan havuzundan Credits tüketir. Bazı durum ve sağlık sorgulamaları ücretlendirilmez; detaylar API dokümantasyonunda yer almaktadır. Geçersiz girdi nedeniyle reddedilen çağrılar da ücretlendirilir; hız sınırı uygulanan çağrılar ise ücretlendirilmez.

API ve Geliştirici → API Kullanımı altında çağrıları Credits ile birlikte görürsünüz: canlı günlük her isteği gösterir, geçmiş kullanımı tarihe, işleyiciye ve eyleme göre gösterir. Credits tükendiğinde, bakiye doldurulana veya otomatik yenileme devreye girene kadar çağrılar reddedilir. Hız sınırları planınıza bağlıdır; mevcut sınırlar ve yanıt başlıkları API dokümantasyonunda açıklanmıştır. Credits hakkında daha fazla bilgi: PaperOffice AI'de Faturalandırma ve Credits.

MCP: Yapay zeka asistanlarını bağlayın

MCP, Claude, ChatGPT, Grok ve Cursor gibi yapay zeka asistanlarını doğrudan PaperOffice'e bağlar. Kimlik doğrulama OAuth 2.1 veya bir kullanıcı/grup belirteci ile yapılır; sistem anahtarları ve yayımlanabilir anahtarlar MCP için engellenmiştir. Üretim sunucusu https://mcp.paperoffice.ai'dur ve /claude, /chatgpt, /grok, /cursor ve /dms gibi profilleri içerir. Kurulum, izinler ve veri akışı: Claude, ChatGPT, Grok ve Cursor ile PaperOffice kullanımı.

Sıkça sorulan sorular

  • Tüm uç noktaları nerede bulabilirim? llms.txt, llms-full.txt ve OpenAPI dosyasında. Bunlar canlı olarak oluşturulur.
  • Sunucum hangi belirteci kullanmalı? Bir sistem anahtarı, asla bir tarayıcıda değil. Bir tarayıcı için, bir köken ve bütçe ile birlikte bir yayımlanabilir anahtar kullanın.
  • HTTP 202 bir hata mıdır? Hayır. İşlem hala devam ediyor; sonucu almak için sorgulama yapın.
  • Daha hızlı başlatma yolları daha fazla maliyetli mi? Evet. En iyi çaba (best effort) için ek ücret yoktur; mevcut fiyatlar API fiyat listesinde yer almaktadır.
  • Reddedilen çağrılar ücretlendirilir mi? Geçersiz girdi nedeniyle reddedilen çağrılar ücretlendirilir; hız sınırı uygulanan çağrılar ise ücretlendirilmez.