API dokümantasyonu
Bir PDF, Word belgesi veya görsel gönderin, yapılandırılmış JSON alın.
Giriş
İstediğiniz verileri bir kategori olarak tanımlarsınız: panelde oluşturulan, fatura numarası, tarih veya kalemler gibi alanlardan oluşan bir liste. Parsevix belgeyi okur, bu alanları doldurur ve bunları okuduğu metinle ve her değerin bulunduğu konumla birlikte JSON olarak döndürür.
API, tek bir temel URL üzerinden HTTPS ile sunulur. İstekler ve yanıtlar JSON biçimindedir; yalnızca dosya yüklemeleri multipart/form-data olarak gönderilir.
https://parsevix.com/api/v1Her API anahtarı tek bir projeye aittir. Bir anahtar yalnızca o projenin belgelerini, kategorilerini ve webhook'larını görür ve değiştirir.
API çağrılarının yanı sıra sonuçları webhook'lar aracılığıyla alabilir, Zapier entegrasyonunu kurabilir veya belgeleri bir projenin e-posta adresine gönderebilirsiniz.
Kurallar
- API yanıtlarındaki alan adları camelCase, webhook ve callback (geri çağırma) gövdelerindeki alan adları ise snake_case biçimindedir.
- Zaman damgaları UTC ve ISO 8601 biçimindedir (
2026-10-25T10:12:06.791Z). - Hata mesajları,
Accept-Languagebaşlığına göre İngilizce, Almanca, Türkçe, Fransızca, İspanyolca, İtalyanca, Felemenkçe, Lehçe veya Portekizcedir.
Hızlı başlangıç
- 1
API anahtarı oluşturun
Panelde projenizi açın, API Anahtarları bölümüne gidin ve bir anahtar oluşturun. Anahtar yalnızca bir kez gösterilir; örneğin
PARSEVIX_API_KEYortam değişkeninde saklayın. Free planında bir anahtar bulunur, ücretli planlarda daha fazlası (bkz. Sınırlar ve krediler). - 2
Kategori tanımlayın
Kategoriler bölümünde belge türünüz için bir kategori oluşturun ve ihtiyacınız olan alanları ekleyin ya da yerleşik bir şablonla başlayın. Bu sayfadaki örnekler
Supplier invoiceadlı bir kategori kullanır. - 3
Belge gönderin
POST /extractdosyayı yükler ve sonucu bekler. Yanıt, doldurulan alanlarıextractedalanında içerir.
İstekleri açık tutmadan çok sayıda belge işlemek için asenkron yükleme yapın ve sonuçları webhook'lar aracılığıyla alın.
curl https://parsevix.com/api/v1/extract \
-H "X-API-Key: $PARSEVIX_API_KEY" \
-F file=@invoice.pdf \
-F category="Supplier invoice"{
"id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
"fileName": "invoice.pdf",
"status": "Completed",
"category": "Supplier invoice",
"processingMode": "specific",
"confidenceScore": 0.97,
"pageCount": 1,
"language": "en",
"retained": false,
"extracted": {
"invoice_number": "F-2026-88343",
"invoice_date": "2026-10-03",
"due_date": "2026-10-17",
"currency": "GBP",
"seller": {
"name": "Northgate Systems Ltd",
"vat_id": "GB566163740"
},
"line_items": [
{
"description": "LED panel light",
"quantity": 4,
"unit_price": 542.55,
"total": 2170.2
},
{
"description": "Office chair",
"quantity": 1,
"unit_price": 475.86,
"total": 475.86
}
],
"gross_total": 7848.88,
"_field_blocks": {
"invoice_number": [
{
"page": 1,
"x": 35.04,
"y": 378.24,
"width": 159.84,
"height": 11.04,
"text": "Invoice number: F-2026-88343"
}
],
"seller.name": [
{
"page": 1,
"x": 34.08,
"y": 558.24,
"width": 120.48,
"height": 12.96,
"text": "Northgate Systems Ltd"
}
]
}
}
}Eğitim videoları
Beş kısa video, paneldeki temel adımları ve ilk API isteğinizi gösterir. Her birinde dokuz dilde seslendirme ve altyazı vardır; oynatıcıdaki dişli simgesinden seçebilirsiniz.
Videolar YouTube'dan oynatılır (youtube-nocookie.com). Oynat'a tıklayana kadar YouTube'dan hiçbir şey yüklenmez; tıkladığınızda Google IP adresinizi alır ve çerez saklayabilir. Ayrıntılar için Gizlilik Politikası sayfasına bakın.
Kimlik doğrulama
API anahtarınızı her istekte X-API-Key başlığıyla gönderin.
X-API-Key: psvx_…Bir anahtar yalnızca /api/v1 altında çalışır; panele giriş için kullanılamaz. Anahtarlar projede API Anahtarları bölümünde oluşturulur ve iptal edilir. İptal edilen bir anahtar hemen geçersiz olur.
Anahtarları sunucunuzda saklayın. Anahtara sahip olan herkes belge yükleyebilir ve projenin sonuçlarını okuyabilir; bu yüklemeler de sizin kredilerinizi harcar.
Bir anahtar ne zaman reddedilir
| Durum | Kod | Anlamı |
|---|---|---|
| 401 | apikey.missing | X-API-Key başlığı gönderilmedi. |
| 401 | apikey.invalid | Anahtar mevcut değil veya iptal edilmiş. |
| 403 | apikey.plan_disabled | Hesabın planı API erişimi içermiyor. |
| 403 | apikey.paused_by_plan | Hesabın planı daha az anahtara veya projeye izin verdiği için anahtar ya da projesi duraklatıldı. |
| 403 | apikey.account_unavailable | Hesap kapatıldı veya silinmek üzere işaretlendi. |
| 403 | apikey.project_unavailable | Anahtarın projesi silindi. |
| 429 | apikey.too_many_invalid | Ağınızdan 10 dakika içinde 30'dan fazla geçersiz anahtar geldi. Retry-After saniye bekleyin; yakın zamanda çalışmış bir anahtar engellenmez. |
{
"error": {
"code": "apikey.invalid",
"message": "The API key is not valid. It may have been revoked; create a new one in the project under API Keys."
}
}İşleme modları
Her yükleme dört yoldan biriyle okunur.
- Otomatik kategori (
auto-classify). Parsevix projenin en uygun kategorisini seçer, ardından o kategorinin alanlarını çıkarır. Kategori göndermediğinizde veyacategory=autogönderdiğinizde kullanılır. - Yalnızca sınıflandırma (
classify-only). Parsevix en uygun kategoriyi seçer ve hiçbir veri çıkarmaz; belgeleri türe göre ayırmak içindir. İlk 3 sayfayı okur ve belge başına 1 kredi tutar. Alanlar daha sonra çıkarılabilir. Bkz. Belge sınıflandırma. - Belirli kategori (
specific). Kategoriyi siz belirtirsiniz; o kategorinin alanları çıkarılır. - Şemasız (
auto-entity). Kategori kullanılmaz. Parsevix bulduğu alanları, belgenin kendi etiketlerine göre adlandırarak döndürür. Bkz. Şemasız veri çıkarma.
Belgenin dili otomatik olarak algılanır. İsteğe bağlı language parametresi, yalnızca algılama için yeterli metin içermeyen belgeler için bir yedektir.
Belgeden veri çıkarma
/api/v1/extractBir belgeyi yükler ve işlenene kadar bekler. Yanıt, çıkarılan alanları içerir.
filefilezorunlu- Belge: PDF, DOCX, PNG, JPEG veya TIFF; en fazla 10 MB ve 30 sayfa.
categorystringisteğe bağlı- Projedeki bir kategorinin adı. Seçimi Parsevix'e bırakmak için boş bırakın veya
autogönderin. languagestringisteğe bağlıdegibi iki harfli ISO 639-1 kodu. Yalnızca dil algılanamazsa kullanılır.
Bekleme ve sınırlar
- İstek, sonuç hazır olana kadar en fazla 285 saniye açık kalır. HTTP istemcinizin zaman aşımını bunun üzerinde bir değere ayarlayın.
- İşleme daha uzun sürerse
document.sync_timeoutkodu vedocumentIddeğeriyle birlikte504alırsınız. İşleme devam eder; sonuç webhook'larınıza gönderilir. - İşleme başarısız olursa
document.sync_failedkoduyla422alırsınız. Nedenireasonalanında yer alır; bkz. hata nedenleri. - Her API anahtarının aynı anda en fazla 5 açık isteği olabilir. Fazlası
document.sync_concurrency_limitkoduyla429döndürür. Kapattığınız ya da zaman aşımına uğrayan bir istek, belgesi işlenene kadar yerini korur. Toplu yüklemeler için asenkron yüklemeyi kullanın.
Yanıt
idstring- Belge kimliği.
fileNamestring- Yüklenen dosyanın adı.
statusstringCompleted.categorystring | null- Kullanılan kategori; şemasız modda
null. processingModestringauto-classify,specificveyaauto-entity.confidenceScorenumber- 0 ile 1 arasında: veri çıkarmanın ne kadar kesin olduğu.
pageCountinteger- İşlenen sayfa sayısı; her sayfa bir kredi tutar.
languagestring- Algılanan dil, ISO 639-1.
retainedboolean- Parsevix'in dosyayı ve sonucu saklayıp saklamadığı. Bkz. Veri saklama.
extractedobject- Çıkarılan alanlar. Bkz. Sonuç.
curl https://parsevix.com/api/v1/extract \
-H "X-API-Key: $PARSEVIX_API_KEY" \
-F file=@invoice.pdf \
-F category="Supplier invoice"{
"id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
"fileName": "invoice.pdf",
"status": "Completed",
"category": "Supplier invoice",
"processingMode": "specific",
"confidenceScore": 0.97,
"pageCount": 1,
"language": "en",
"retained": false,
"extracted": {
"invoice_number": "F-2026-88343",
"invoice_date": "2026-10-03",
"due_date": "2026-10-17",
"currency": "GBP",
"seller": {
"name": "Northgate Systems Ltd",
"vat_id": "GB566163740"
},
"line_items": [
{
"description": "LED panel light",
"quantity": 4,
"unit_price": 542.55,
"total": 2170.2
},
{
"description": "Office chair",
"quantity": 1,
"unit_price": 475.86,
"total": 475.86
}
],
"gross_total": 7848.88,
"_field_blocks": {
"invoice_number": [
{
"page": 1,
"x": 35.04,
"y": 378.24,
"width": 159.84,
"height": 11.04,
"text": "Invoice number: F-2026-88343"
}
],
"seller.name": [
{
"page": 1,
"x": 34.08,
"y": 558.24,
"width": 120.48,
"height": 12.96,
"text": "Northgate Systems Ltd"
}
]
}
}
}{
"error": {
"code": "document.sync_failed",
"message": "The file is damaged or is not a valid PDF, Word document or image.",
"reason": "file_unreadable",
"documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
}
}{
"error": {
"code": "document.sync_timeout",
"message": "Extraction did not finish within 285 seconds. Large documents may need to be split.",
"documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
}
}Şemasız veri çıkarma
/api/v1/extract-autoPOST /extract gibidir ancak kategori kullanmaz: Parsevix belgede bulduğu tüm alanları döndürür.
filefilezorunlu- Belge: PDF, DOCX, PNG, JPEG veya TIFF; en fazla 10 MB ve 30 sayfa.
languagestringisteğe bağlı- İki harfli ISO 639-1 kodu. Yalnızca dil algılanamazsa kullanılır.
Çıktı belgenin dilinde kalır. Anahtarlar, belgenin kendi etiketlerinin snake_case biçimidir (Almanca bir fatura rechnungsnummer verir); değerler basıldığı gibi kopyalanır: tarihler belgenin biçiminde, tutarlar "2.430,09" gibi metin olarak.
Yeni bir belge türünü keşfetmek için kullanın. Otomatik olarak işlediğiniz veriler için bir kategori, sabit anahtarlar ve normalleştirilmiş değerler sağlar.
Yanıt, POST /extract ile aynı alanlara sahiptir; processingMode değeri auto-entity, category değeri null olur.
curl https://parsevix.com/api/v1/extract-auto \
-H "X-API-Key: $PARSEVIX_API_KEY" \
-F file=@invoice.pdfBelge sınıflandırma
/api/v1/classifyBir belgeyi yükler ve Parsevix projenin kategorilerinden birini seçene kadar bekler. Hiçbir alan çıkarılmaz. Belgeleri türe göre ayırmak veya yönlendirmek için kullanın.
Adaylar yerleşik şablonlar değil, projenin kendi kategorileridir. Parsevix ilk 3 sayfayı okur; bu nedenle bir sınıflandırma, belge ne kadar uzun olursa olsun 1 kredi tutar.
filefilezorunlu- Belge: PDF, DOCX, PNG, JPEG veya TIFF; en fazla 10 MB ve 30 sayfa.
languagestringisteğe bağlı- İki harfli ISO 639-1 kodu. Yalnızca dil algılanamazsa kullanılır.
Bekleme ve hatalar POST /extract ile aynıdır: en fazla 285 saniye; daha uzun sürerse document.sync_timeout koduyla 504, belge işlenemezse document.sync_failed koduyla 422. Anahtar başına 5 açık istek iki uç nokta arasında paylaşılır.
Yanıt
idstring- Belge kimliği.
fileNamestring- Yüklenen dosyanın adı.
statusstringCompleted.categorystring- Parsevix'in seçtiği kategori.
processingModestringclassify-only.pageCountinteger- Belgedeki sayfa sayısı. İlk 3 sayfa okundu.
languagestring- Algılanan dil, ISO 639-1.
retainedboolean- Parsevix'in dosyayı saklayıp saklamadığı. Yalnızca saklanan bir belgeden daha sonra veri çıkarılabilir.
Daha sonra veri çıkarma
POST /documents/{id}/extract, belgenin alanlarını atanan kategoriye veya sizin belirttiğiniz bir kategoriye göre çıkarır. Belgenin sayfa sayısından önceden ödenmiş 1 kredi düşülerek ücretlendirilir: 5 sayfalık bir belge 4 kredi daha, toplamda 5 kredi tutar.
Bunun için dosya gerekir; dolayısıyla projenin API yüklemelerini saklaması gerekir (bkz. Veri saklama). Panelden veya e-postayla gönderilen belgeler her zaman saklanır. Asenkron yüklemeler de sınıflandırılabilir: POST /documents isteğinde processingMode=classify-only gönderin.
curl https://parsevix.com/api/v1/classify \
-H "X-API-Key: $PARSEVIX_API_KEY" \
-F file=@invoice.pdf{
"id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
"fileName": "invoice.pdf",
"status": "Completed",
"category": "Supplier invoice",
"processingMode": "classify-only",
"pageCount": 1,
"language": "en",
"retained": true
}Asenkron yükleme
/api/v1/documentsBir belgeyi kuyruğa alır ve hemen 202 durum koduyla belge kaydını döndürür. Toplu yüklemeler ve Zapier gibi bir isteği açık tutamayan istemciler içindir.
filefilezorunlu- Belge: PDF, DOCX, PNG, JPEG veya TIFF; en fazla 10 MB ve 30 sayfa.
categorystringisteğe bağlı- Bir kategorinin adı. Seçimi Parsevix'e bırakmak için boş bırakın veya
autogönderin. processingModestringisteğe bağlıauto-classify,specific,auto-entityveyaclassify-only. İsteğe bağlı: varsayılan olarakcategorydeğerinden belirlenir.classify-onlybir kategoriyle birlikte kullanılamaz.languagestringisteğe bağlı- İki harfli ISO 639-1 kodu. Yalnızca dil algılanamazsa kullanılır.
callbackUrlstringisteğe bağlı- Herkese açık bir
httpsURL'si. Parsevix sonucu bu adrese bir kez, bir webhook olayıyla aynı gövdeye sahip birPOSTolarak gönderir.
Sonucu alma
- Projenin webhook'ları
extraction.completedveyaextraction.failedolayını alır.classify-onlyile yapılan bir yükleme,extraction.completedyerineclassification.completedgönderir. - callbackUrl verilmişse aynı olayı aynı yeniden denemelerle alır. Callback imzalı değildir; bu nedenle URL'ye gizli bir token ekleyin ve bunu doğrulayın.
GET /documents/{id}ile periyodik sorgulama durumu gösterir; sonucu ise yalnızca proje API yüklemelerini saklıyorsa gösterir (bkz. Veri saklama).
curl https://parsevix.com/api/v1/documents \
-H "X-API-Key: $PARSEVIX_API_KEY" \
-F file=@invoice.pdf \
-F category="Supplier invoice" \
-F callbackUrl="https://example.com/parsevix/callback?token=a-secret-only-you-know"{
"id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
"status": "Pending",
"categoryName": "Supplier invoice",
"processingMode": "specific",
"fileName": "invoice.pdf",
"fileSize": 22579,
"source": "api",
"discardFiles": true,
"createdAt": "2026-10-25T10:12:06.791Z",
"completedAt": null,
"reprocessCount": 0,
"lastReprocessedAt": null,
"approvalStatus": "Unapproved",
"isTrainingExample": false
}Sonuç
extracted
Kategorinin alan adlarını anahtar olarak kullanan bir nesne (kategori şemasındaki fieldName). Nesneler ve listeler şemayı izler.
Tarihler YYYY-MM-DD biçimindedir. Sayılar, para birimi simgesi veya binlik ayırıcı içermeyen JSON sayılarıdır. Belgede bulunmayan bir alan yanıtta yer almaz veya null olur.
Adlar ve IBAN'lar gibi kişisel veriler, belgede yazıldığı gibi döndürülür. Yalnızca yapay zekâ modeline giderken maskelenir ve size ulaşmadan önce geri yüklenir.
_field_blocks
Her değerin nerede bulunduğu. Anahtarlar seller.name veya line_items[0].total gibi alan yollarıdır; her girdi, metin satırlarını sayfa, kutu ve metinle birlikte listeler. Konumu belirlenemeyen bir değer burada yer almaz. Yalnızca verilere ihtiyacınız varsa _ ile başlayan anahtarları yok sayın.
Koordinatlar
- PDF ve DOCX: PDF noktası (1/72 inç). Başlangıç noktası sayfanın sol alt köşesidir;
ykutunun üst kenarıdır ve alttan ölçülür. - Görseller: piksel. Başlangıç noktası sol üst köşedir;
yüst kenardır ve üstten ölçülür.
{
"id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
"fileName": "invoice.pdf",
"status": "Completed",
"category": "Supplier invoice",
"processingMode": "specific",
"confidenceScore": 0.97,
"pageCount": 1,
"language": "en",
"retained": false,
"extracted": {
"invoice_number": "F-2026-88343",
"invoice_date": "2026-10-03",
"due_date": "2026-10-17",
"currency": "GBP",
"seller": {
"name": "Northgate Systems Ltd",
"vat_id": "GB566163740"
},
"line_items": [
{
"description": "LED panel light",
"quantity": 4,
"unit_price": 542.55,
"total": 2170.2
},
{
"description": "Office chair",
"quantity": 1,
"unit_price": 475.86,
"total": 475.86
}
],
"gross_total": 7848.88,
"_field_blocks": {
"invoice_number": [
{
"page": 1,
"x": 35.04,
"y": 378.24,
"width": 159.84,
"height": 11.04,
"text": "Invoice number: F-2026-88343"
}
],
"seller.name": [
{
"page": 1,
"x": 34.08,
"y": 558.24,
"width": 120.48,
"height": 12.96,
"text": "Northgate Systems Ltd"
}
]
}
}
}Belgeler
Projenin tüm kaynaklardan gelen belgeleri: panel, API ve e-posta.
Belgeleri listeleme
/api/v1/documentsEn yeniler önce gelir. Yalnızca saklanan belgeler listelenir: API yüklemeleri yalnızca proje bunları saklıyorsa görünür.
pageintegeristeğe bağlı- Sayfa numarası, 1'den başlar.
pageSizeintegeristeğe bağlı- 1 ile 100 arası; varsayılan 20.
statusstringisteğe bağlıPending,Processing,CompletedveyaFailed.categorystringisteğe bağlı- Kategori adı.
searchstringisteğe bağlı- Dosya adının bir kısmı.
fileTypestringisteğe bağlıpdf,docxveyaimage.sourcestringisteğe bağlıdashboard,apiveyaemail.processingModestringisteğe bağlıauto-classify,specific,auto-entityveyaclassify-only.
Belge getirme
/api/v1/documents/{id}Belge ve sonucu. outputDeanonymized çıkarılan verilerdir ve extracted ile aynı nesnedir. classify-only ile yüklenen bir belgenin kategorisi categoryName alanındadır ve outputDeanonymized alanı yoktur. Başarısız bir belgede errorCode ve errorMessage bulunur. Proje API yüklemelerini saklamıyorsa durum alınabilir ancak sonuç alınamaz.
Belgeyi yeniden işleme
/api/v1/documents/{id}/reprocessVeri çıkarmayı yeniden çalıştırır; örneğin kategorinin alanlarını değiştirdikten sonra. İsteğe bağlı JSON gövdesi: category (bir ad veya auto) ve processingMode. 202 ile yanıt verir; sonuç bir asenkron yüklemede olduğu gibi gelir. Krediler yeniden düşülür. classify-only ile yüklenen bir belge, kategori belirtmezseniz yeniden sınıflandırılır (1 kredi). Dosyaları saklanmayan API yüklemeleri için mümkün değildir (document.files_not_retained).
Sınıflandırılmış belgeden veri çıkarma
/api/v1/documents/{id}/extractclassify-only ile yüklenen bir belge için: alanlarını atanan kategoriye veya isteğe bağlı JSON gövdesindeki category değerine göre çıkarır. Belgenin sayfa sayısından sınıflandırmanın tuttuğu 1 kredi düşülerek ücretlendirilir. 202 ile yanıt verir; sonuç bir asenkron yüklemede olduğu gibi extraction.completed olarak gelir. Diğer belgeler için document.not_classify_only koduyla 400 döndürür; bunlar için yeniden işlemeyi kullanın.
Belge silme
/api/v1/documents/{id}Belgeyi, dosyasını ve sonuçlarını siler. 204 ile yanıt verir.
Anahtarın projesinde bulunmayan bir kimlik, document.not_found koduyla 404 döndürür.
curl "https://parsevix.com/api/v1/documents?status=Completed&pageSize=20" \
-H "X-API-Key: $PARSEVIX_API_KEY"{
"data": [
{
"id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
"status": "Completed",
"categoryName": "Supplier invoice",
"processingMode": "specific",
"fileName": "invoice.pdf",
"fileSize": 22579,
"source": "api",
"discardFiles": false,
"createdAt": "2026-10-25T10:12:06.791Z",
"completedAt": "2026-10-25T10:12:15.212Z",
"reprocessCount": 0,
"lastReprocessedAt": null,
"approvalStatus": "Unapproved",
"isTrainingExample": false
}
],
"totalCount": 1,
"page": 1,
"pageSize": 20
}curl https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581 \
-H "X-API-Key: $PARSEVIX_API_KEY"{
"id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
"status": "Completed",
"categoryName": "Supplier invoice",
"processingMode": "specific",
"fileName": "invoice.pdf",
"fileSize": 22579,
"source": "api",
"language": "en",
"confidenceScore": 0.97,
"pageCount": 1,
"outputDeanonymized": {
"invoice_number": "F-2026-88343",
"invoice_date": "2026-10-03",
"due_date": "2026-10-17",
"currency": "GBP",
"seller": {
"name": "Northgate Systems Ltd",
"vat_id": "GB566163740"
},
"line_items": [
{
"description": "LED panel light",
"quantity": 4,
"unit_price": 542.55,
"total": 2170.2
},
{
"description": "Office chair",
"quantity": 1,
"unit_price": 475.86,
"total": 475.86
}
],
"gross_total": 7848.88,
"_field_blocks": {
"invoice_number": [
{
"page": 1,
"x": 35.04,
"y": 378.24,
"width": 159.84,
"height": 11.04,
"text": "Invoice number: F-2026-88343"
}
],
"seller.name": [
{
"page": 1,
"x": 34.08,
"y": 558.24,
"width": 120.48,
"height": 12.96,
"text": "Northgate Systems Ltd"
}
]
}
},
"errorMessage": null,
"errorCode": null,
"createdAt": "2026-10-25T10:12:06.791Z",
"completedAt": "2026-10-25T10:12:15.212Z"
}curl https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581/reprocess \
-H "X-API-Key: $PARSEVIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"category": "auto"}'curl https://parsevix.com/api/v1/documents/01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27/extract \
-H "X-API-Key: $PARSEVIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'{
"id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
"status": "Pending",
"categoryName": "Supplier invoice",
"processingMode": "specific",
"fileName": "invoice.pdf",
"fileSize": 22579,
"source": "api",
"discardFiles": false,
"createdAt": "2026-10-25T10:12:06.791Z",
"completedAt": null,
"reprocessCount": 1,
"lastReprocessedAt": "2026-10-25T11:04:12.530Z",
"approvalStatus": "Unapproved",
"isTrainingExample": false
}curl -X DELETE https://parsevix.com/api/v1/documents/01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581 \
-H "X-API-Key: $PARSEVIX_API_KEY"Kategoriler
Yerleşik şablonlar (isGlobal: true) dahil projenin kategorileri. Kategoriler panelde oluşturulur ve düzenlenir.
Kategorileri listeleme
/api/v1/categoriesKategori şemasını getirme
/api/v1/categories/{name}Bir kategorinin çıkardığı alanlar. fieldName, extracted nesnesindeki anahtardır. fieldType değeri string, number, date, boolean, object veya array olur; nesnelerin ve dizilerin alanları children içindedir. Yoldaki ad büyük/küçük harfe duyarlı değildir.
curl https://parsevix.com/api/v1/categories \
-H "X-API-Key: $PARSEVIX_API_KEY"[
{
"id": 1,
"name": "Invoice",
"description": "Invoices and billing documents with seller/buyer info, line items, and totals",
"isGlobal": true,
"fieldCount": 48
},
{
"id": 54,
"name": "Supplier invoice",
"description": "Commercial invoice: seller, buyer, line items and totals.",
"isGlobal": false,
"fieldCount": 26
}
]curl "https://parsevix.com/api/v1/categories/Supplier%20invoice" \
-H "X-API-Key: $PARSEVIX_API_KEY"{
"id": 54,
"name": "Supplier invoice",
"description": "Commercial invoice: seller, buyer, line items and totals.",
"fields": [
{
"fieldName": "invoice_number",
"displayName": "Invoice number",
"fieldType": "string",
"description": null,
"children": []
},
{
"fieldName": "invoice_date",
"displayName": "Invoice date",
"fieldType": "date",
"description": null,
"children": []
},
{
"fieldName": "seller",
"displayName": "Seller",
"fieldType": "object",
"description": null,
"children": [
{
"fieldName": "name",
"displayName": "Name",
"fieldType": "string",
"description": null,
"children": []
},
{
"fieldName": "vat_id",
"displayName": "VAT / tax id",
"fieldType": "string",
"description": null,
"children": []
}
]
}
]
}Anahtar ve krediler
/api/v1/meAnahtarın projesi ve hesabın kredi bakiyesi. Krediler hesaba aittir ve hesabın tüm projeleri tarafından paylaşılır; resetsOn bir sonraki dönemin başlangıcıdır. Yıllık planda dönem fatura yılıdır ve monthlyLimit tüm yılın kredilerini içerir.
curl https://parsevix.com/api/v1/me \
-H "X-API-Key: $PARSEVIX_API_KEY"{
"projectId": "01a16af3-0b1f-7f2f-8282-b3824309d921",
"projectName": "Accounts payable",
"projectSlug": "accounts-payable",
"keyName": "ERP connector",
"keyPrefix": "psvx_nyskxlv",
"email": "you@example.com",
"credits": {
"period": "2026-10-04",
"resetsOn": "2026-11-04",
"monthlyLimit": 1000,
"used": 312,
"remaining": 688,
"planName": "Growth"
}
}Webhook yönetimi
Webhook'lar panelde (Webhook'lar) veya bu uç noktalar üzerinden yönetilebilir.
Webhook oluşturma
/api/v1/webhooksurlstringzorunlu- Herkese açık bir
httpsURL'si. Özel ağlardaki adresler reddedilir. eventsstring[]zorunluextraction.completed,extraction.failedveclassification.completedolaylarından bir veya birkaçı.filtersobjectisteğe bağlı- İsteğe bağlı.
sources(dashboard,api,email) vecategories(adlar), hangi belgelerin olay göndereceğini sınırlar.
Yanıt, imzalama için kullanılan secret değerini yalnızca bir kez içerir. İmzaları doğrulamak için saklayın.
Webhook'ları listeleme
/api/v1/webhooksWebhook silme
/api/v1/webhooks/{id}Örnek olaylar
/api/v1/webhooks/samplesAlıcınızı test etmek için projenin en son belgeleri, olay gövdeleri olarak. Sorgu parametreleri: event (zorunlu), limit (1–10, varsayılan 3), category. Henüz uygun bir belge yoksa kategori şemasından bir örnek oluşturulur.
curl https://parsevix.com/api/v1/webhooks \
-H "X-API-Key: $PARSEVIX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/parsevix/webhook",
"events": ["extraction.completed", "extraction.failed"],
"filters": { "sources": ["api", "email"] }
}'{
"secret": "d0726faeb5c655d349fc30ed226e93e531ac2499800aacde100e83554b48701c",
"id": "01a17295-c761-7b8f-b173-388bc754b1ba",
"url": "https://example.com/parsevix/webhook",
"events": [
"extraction.completed",
"extraction.failed"
],
"filters": {
"sources": [
"api",
"email"
],
"categories": null
},
"isActive": true,
"disabledAt": null,
"disabledReason": null,
"managedBy": null,
"createdAt": "2026-10-25T10:23:09.311Z"
}curl "https://parsevix.com/api/v1/webhooks/samples?event=extraction.completed&limit=1" \
-H "X-API-Key: $PARSEVIX_API_KEY"Webhook'lar
Bir belge tamamlandığında Parsevix, projenin her webhook'una JSON gövdeli bir POST gönderir. Webhook'lar tüm kaynaklardan gelen belgeleri alır: panel, API ve e-posta.
Olaylar
| Olay | Açıklama |
|---|---|
| extraction.completed | Bir belge işlendi. data çıkarılan alanları içerir. |
| classification.completed | classify-only ile yüklenen bir belge kategorisini aldı: kategori document.category, belgenin sayfa sayısı document.page_count alanındadır. data yoktur. |
| extraction.failed | Bir belge işlenemedi (classify-only belgeler dahil). error_code hata nedenlerinden biridir; error panelde gösterilen mesajdır. |
| test.ping | Paneldeki webhook sayfasında bulunan Test düğmesiyle gönderilir. |
Başlıklar
| Başlık | Açıklama |
|---|---|
| X-Webhook-Id | Olay kimliği. Her denemede aynıdır; yinelenen olayları yok saymak için kullanın. Gövdedeki id ile de aynıdır. |
| X-Webhook-Event | Olayın adı. |
| X-Webhook-Timestamp | Bu denemenin saniye cinsinden Unix zamanı. |
| X-Webhook-Signature | sha256= ve ardından, webhook'un secret değeri anahtar olarak kullanılarak {timestamp}.{raw body} üzerinden hesaplanan onaltılık HMAC-SHA256. |
| X-Webhook-Attempt | Deneme numarası, 1'den başlar. |
İmzayı doğrulama
HMAC değerini, ham istek gövdesi üzerinden, tam olarak alındığı haliyle ve ayrıştırmadan önce hesaplayın. Zaman damgası 5 dakikadan eski olan olayları reddedin.
Yanıt verme
- 10 saniye içinde
2xxdurum koduyla yanıt verin, ardından olayı işleyin. Diğer tüm yanıtlar başarısızlık sayılır. Yönlendirmeler izlenmez. - Başarısız teslimatlar 1 dakika, 5 dakika, 30 dakika, 2 saat, 6 saat ve 24 saat sonra yeniden denenir: yaklaşık 33 saatte 7 deneme.
410 Goneile yanıt vermek webhook'u hemen devre dışı bırakır. Üç olayın tüm denemeleri başarısız olduğunda ve 3 gün boyunca hiçbir teslimat başarılı olmadığında da devre dışı bırakılır. Sahibine bir e-posta gönderilir; webhook panelden yeniden etkinleştirilebilir. Aradaki olaylar yeniden gönderilmez.- Secret değeri panelden yenilenebilir. Eski secret hemen geçersiz olur.
{
"id": "01a172a0-3f1e-7d42-9b6c-8e2f5a7d1c90",
"event": "extraction.completed",
"timestamp": "2026-10-25T10:12:21.592Z",
"project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
"project_name": "Accounts payable",
"project_slug": "accounts-payable",
"document": {
"id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
"file_name": "invoice.pdf",
"category": "Supplier invoice",
"source": "api",
"processing_mode": "specific",
"language": "en",
"confidence_score": 0.97
},
"data": {
"invoice_number": "F-2026-88343",
"invoice_date": "2026-10-03",
"due_date": "2026-10-17",
"currency": "GBP",
"seller": {
"name": "Northgate Systems Ltd",
"vat_id": "GB566163740"
},
"line_items": [
{
"description": "LED panel light",
"quantity": 4,
"unit_price": 542.55,
"total": 2170.2
},
{
"description": "Office chair",
"quantity": 1,
"unit_price": 475.86,
"total": 475.86
}
],
"gross_total": 7848.88,
"_field_blocks": {
"invoice_number": [
{
"page": 1,
"x": 35.04,
"y": 378.24,
"width": 159.84,
"height": 11.04,
"text": "Invoice number: F-2026-88343"
}
],
"seller.name": [
{
"page": 1,
"x": 34.08,
"y": 558.24,
"width": 120.48,
"height": 12.96,
"text": "Northgate Systems Ltd"
}
]
}
}
}{
"id": "01a172b5-8e47-7a13-b2c9-4f6d0a8e3b51",
"event": "classification.completed",
"timestamp": "2026-10-25T10:14:02.334Z",
"project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
"project_name": "Accounts payable",
"project_slug": "accounts-payable",
"document": {
"id": "01a172b4-5d2e-7c61-8f0a-3b9d6e1c4a27",
"file_name": "invoice.pdf",
"category": "Supplier invoice",
"source": "api",
"processing_mode": "classify-only",
"language": "en",
"page_count": 1
}
}{
"id": "01a172a1-0c55-7e18-a3d4-6b9f2e8c1d07",
"event": "extraction.failed",
"timestamp": "2026-10-25T10:12:23.711Z",
"project_id": "01a16af3-0b1f-7f2f-8282-b3824309d921",
"project_name": "Accounts payable",
"project_slug": "accounts-payable",
"document": {
"id": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581",
"file_name": "invoice.pdf",
"category": "Supplier invoice",
"source": "api",
"processing_mode": "specific"
},
"error_code": "file_unreadable",
"error": "The file is damaged or is not a valid PDF, Word document or image."
}import hashlib
import hmac
import time
def verify(raw_body: bytes, headers, secret: str) -> bool:
timestamp = headers["X-Webhook-Timestamp"]
signature = headers["X-Webhook-Signature"] # "sha256=<hex>"
if abs(time.time() - int(timestamp)) > 300:
return False # 5 dakikadan eski: tekrar gönderilmiş olabilir
expected = hmac.new(
secret.encode(),
timestamp.encode() + b"." + raw_body,
hashlib.sha256,
).hexdigest()
return hmac.compare_digest(signature, "sha256=" + expected)Zapier
Parsevix'in Zapier uygulaması, bir projenin API anahtarıyla bağlanır. Uygulamayı paneldeki projenin Zapier sayfasında bulunan davet bağlantısıyla veya buradan ekleyin.
Tetikleyiciler
- Extraction Completed: bir belge işlendi. İsteğe bağlı olarak yalnızca tek bir kategori veya kaynak için.
- Extraction Failed: bir belge işlenemedi.
- Document Classified: yalnızca sınıflandırılmak üzere gönderilen bir belge kategorisini aldı; örneğin yalnızca sınıflandırma yapacak şekilde ayarlanmış bir e-posta adresinden gelen bir belge.
Eylemler
- Extract Document, önceki bir adımdaki dosyayı isteğe bağlı olarak bir kategoriyle gönderir ve çıkarılan alanları sonraki adımlara aktarır. Bir kategori seçildiğinde, o kategorinin alanları Zap'i oluştururken eşleştirilebilir.
- Classify Document, bir dosya gönderir ve Parsevix'in seçtiği kategoriyi, alan çıkarmadan sonraki adımlara aktarır. Belgeleri türe göre yönlendirmek için kullanın.
Etkinleştirdiğiniz Zap'ler projenin Zapier sayfasında ve Webhook'lar altında görünür.
E-posta ile belge alımı
Starter planından itibaren her projenin E-posta gelen kutusu altında bir e-posta adresi vardır. Bu adrese gönderilen bir e-postanın her eki bir belgeye dönüşür; sonuçlar panelde görünür ve email kaynağıyla webhook'larınıza gönderilir.
Adresler name+inbox@inbox.parsevix.com biçimindedir. Plana bağlı olarak bir projenin birden fazla adresi olabilir; örneğin her tedarikçi veya departman için bir tane.
Adres başına
- Ekler: her eki sabit bir kategoriye göre çıkarın; kategoriyi Parsevix'in seçmesine izin verip ardından çıkarın; ya da yalnızca kategoriyi seçin (
classify-only, belge başına 1 kredi) ve gerekirse alanları daha sonra çıkarın. - İzin verilen gönderenler: yalnızca bu alan adlarından gelen ve o alan adı için DKIM veya SPF doğrulamasından geçen e-postalar kabul edilir; böylece sahte bir gönderen reddedilir.
Neler işlenir
- İletilen e-postaların içindekiler dahil PDF, DOCX, PNG, JPEG ve TIFF ekleri. İmza logoları gibi e-posta gövdesinde gösterilen görseller atlanır.
- Bir e-posta en fazla 30 MB olabilir ve ilk 20 eki belgeye dönüşür. Bir adres 24 saatte en fazla 1.000 e-posta kabul eder ve en fazla 1.000 belge oluşturur; bunun ötesinde e-postalar reddedilir ve ekler içe aktarılmadı olarak listelenir. E-posta almak ücretsizdir; her belge diğer belgeler gibi kredi tutar.
- İki kez teslim edilen aynı e-posta (aynı Message-ID) yalnızca bir kez işlenir.
Hatalar
Hatalarda bir HTTP durum kodu ve sabit bir code ile okunabilir bir message içeren bir gövde bulunur. Kodunuzda code değerine göre karar verin; mesaj metinleri değişebilir.
Durum kodları
| Durum | Anlamı |
|---|---|
| 400 | İstek geçersiz: eksik veya hatalı bir parametre, desteklenmeyen bir dosya, yetersiz kredi. validation.failed, sorunları parametre bazında fields içinde listeler. |
| 401 | API anahtarı yok veya geçerli değil. |
| 403 | Anahtar geçerli ancak kullanılamıyor. Bkz. Kimlik doğrulama. |
| 404 | Belge, kategori, webhook veya uç nokta bu projede mevcut değil. |
| 413 | Yükleme, istek boyutu sınırından büyük. |
| 422 | POST /extract veya POST /classify çalıştı ancak belge işlenemedi. |
| 429 | İstek sınırına veya eşzamanlılık sınırına ulaşıldı. Retry-After başlığında belirtilen saniye kadar bekleyin. |
| 5xx | Sunucu hatası (destek ekibine iletebileceğiniz bir referans numarasıyla), bakım (503) veya zaman aşımı (504). |
Sık karşılaşılan kodlar
| Kod | Anlamı |
|---|---|
| validation.file_required | file gönderilmedi. |
| document.content_not_supported | Dosyanın içeriği, adı ne olursa olsun PDF, DOCX, PNG, JPEG veya TIFF değil. |
| credit.file_size_exceeds_plan | Dosya, planın izin verdiğinden büyük. |
| validation.language_invalid | language iki harfli bir kod değil. |
| document.callback_url_* | callbackUrl en fazla 2.000 karakterlik, herkese açık bir https URL'si değil. |
| credit.insufficient_credits | Bu dönem için yeterli kredi kalmadı. |
| document.refund_pending | Aboneliğin iadesi inceleniyor; iade sonuçlanana kadar hiçbir şey işlenmez. |
| category.not_found | Projede bu ada sahip bir kategori yok. |
| document.classify_only_category | classify-only bir kategoriyle birlikte gönderildi. Bu mod kategoriyi kendisi seçer. |
| document.not_classify_only | POST /documents/{id}/extract, classify-only ile yüklenmemiş bir belge için çağrıldı. |
| document.files_not_retained | API yüklemesinin dosyaları saklanmadığı için yeniden işlenemez. |
| webhook.url_* | Webhook URL'si herkese açık bir https URL'si değil. |
| *.limit_reached | Proje başına webhook sayısı gibi bir plan sınırına ulaşıldı. |
Hata nedenleri
Bir belgenin neden başarısız olduğu şu alanlarda yer alır: POST /extract veya POST /classify isteğinin 422 yanıtında reason, extraction.failed olayında error_code, belge kaydında errorCode.
| Kod | Anlamı |
|---|---|
| too_many_pages | 30'dan fazla sayfa. Dosyayı bölün. |
| sync_too_many_pages | POST /extract ve POST /classify uç noktalarının kabul ettiğinden fazla sayfa. |
| pdf_encrypted | PDF parola korumalı. |
| file_unreadable | Dosya bozuk veya geçerli bir belge değil. |
| no_text | Metin bulunamadı: belge boş veya tarama okunamıyor. |
| no_categories | Kategori otomatik seçilecekti ancak projede hiç kategori yok. |
| no_schema_fields | Kategoride hiç alan yok. |
| no_fields_found | Kategorinin alanlarından hiçbiri belgede bulunamadı; belge muhtemelen yanlış kategoride. Doğru kategoriyle yeniden işleyin. |
| no_data_found | Otomatik veri çıkarma belgede hiç veri bulamadı. |
| insufficient_credits | Belge, bu dönemde kalan krediden fazlasını gerektiriyor. Hiçbir kredi düşülmedi; plan yükseltmesinden veya dönem sıfırlandıktan sonra yeniden işleyin. |
| refund_pending | Aboneliğin iadesi inceleniyordu. İade reddedilirse belgeyi yeniden işleyin. |
| masking_failed | Kişisel veriler maskelenemediği için belge yapay zekâ modeline gönderilmedi. Yeniden deneyin. |
| worker_unavailable | İşleme geçici olarak kullanılamıyordu. Yeniden deneyin. |
| ai_failed | Yapay zekâ modeli geçici olarak başarısız oldu. Yeniden deneyin. |
| processing_failed | Dahili bir hata. Yeniden deneyin; tekrarlanırsa destek ekibiyle iletişime geçin. |
| processing_timeout | İşleme tamamlanmadan durdu (örneğin bir yeniden başlatma sırasında). Yeniden deneyin. |
Son beşi geçicidir: belgeyi yeniden işleyin veya tekrar gönderin. Başarısız çalıştırmalar için sayfa başına kredi düşülmez.
{
"error": {
"code": "validation.failed",
"message": "The file field is required.",
"fields": {
"file": [
"The file field is required."
]
}
}
}{
"error": {
"code": "document.sync_failed",
"message": "The file is damaged or is not a valid PDF, Word document or image.",
"reason": "file_unreadable",
"documentId": "01a1728b-cc26-7ba9-ad3c-dcf5e6d8e581"
}
}Sınırlar ve krediler
Dosyalar
- PDF, DOCX, PNG, JPEG ve TIFF (çok sayfalı olanlar dahil). Tür, dosyanın adından değil içeriğinden belirlenir.
- Belge başına en fazla 10 MB ve 30 sayfa.
Krediler
- İşlenen her sayfa 1 kredi tutar. Kategorinin otomatik seçilmesi ek kredi gerektirmez.
- Yalnızca sınıflandırma (
classify-only) belge başına 1 kredi tutar. Böyle bir belgeden daha sonra veri çıkarmak, sayfa sayısından bu kredi düşülerek ücretlendirilir; toplam yine sayfa başına 1 kredidir. - Başarısız bir çalıştırma için sayfa başına kredi düşülmez. Yeniden işleme yeniden kredi tutar. E-posta almak ücretsizdir.
- Bir dönemin kredileri tükendiğinde yüklemeler, bir sonraki döneme veya plan yükseltmesine kadar
credit.insufficient_creditskoduyla reddedilir. Bir belgenin kredileri, sayfaları sayıldığı anda ayrılır; krediler bu noktada artık yetmezse (örneğin çok sayıda paralel yüklemeden sonra) belgeinsufficient_creditskoduyla başarısız olur ve hiçbir kredi düşülmez.
İstek hızı
Her API anahtarı, plana bağlı olarak dakikada belirli sayıda istek yapabilir. Her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset (Unix zamanı) başlıklarını içerir. Sınır aşıldığında Retry-After başlığıyla birlikte 429 alırsınız.
Plana göre
| Plan | İstek / dakika | Kredi / ay | API anahtarı | Webhook / proje |
|---|---|---|---|---|
| Free | 10 | 20 | 1 | 1 |
| Starter | 30 | 500 | 2 | 2 |
| Growth | 60 | 2.000 | 3 | 5 |
| Pro | 120 | 6.000 | 10 | 10 |
| Business | 300 | 20.000 | sınırsız | 25 |
Ayrıca: POST /extract ve POST /classify en fazla 285 saniye bekler ve anahtar başına ikisi için toplam 5 açık isteğe izin verir.
{
"error": {
"code": "apikey.rate_limited",
"message": "Too many requests for this API key: the limit is 60 per minute. Retry in 18 s.",
"limit": 60,
"retryAfterSeconds": 18
}
}Veri saklama
Parsevix'in bir API yüklemesinden neleri sakladığı bir proje ayarıdır: Proje ayarları altındaki API yüklemeleri. Varsayılan İşlendikten sonra sil'dir; Panel yüklemeleri gibi sakla seçilirse saklanır.
- İşlendikten sonra sil: dosya işleme sona erdiğinde silinir ve sonuç saklanmaz. Tek kopya API yanıtı, webhook veya callback'tir. Bu belgeler listelenmez, yeniden işlenemez ve indirilemez;
retaineddeğerifalseolur. - Panel yüklemeleri gibi sakla: dosyalar ve sonuçlar, siz silene kadar panel yüklemeleri gibi saklanır.
Panel ve e-posta yüklemeleri her zaman saklanır. Kişisel veriler, herhangi bir metin yapay zekâ modeline ulaşmadan önce maskelenir; bkz. Güvenlik.
