Entegrasyon

Harici API V1 Dokümantasyonu

Self servis API uygulaması ve incelemesi için teknik dokümantasyon paketi. Bu sayfa harici API sözleşmesini, erişim modelini ve entegrasyon sınırlarını özetler.

Genel görünüm

API multipart yüklemeleri kabul eder, JSON yanıtları döndürür ve standart HTTP durum kodları ile Bearer kimlik doğrulaması kullanır. Bir PDF fatura gönderin, eşzamansız işlemenin tamamlanmasını bekleyin ve ardından oluşturulan sonucu alın.

PDF faturayı tek bir endpoint’e gönderin; Invoice-Converter çıkarma, doğrulama ve çıktı üretimini yönetir. Sonuç endpoint’i oluşturulan dosyayı yalnızca doğrulama kapıları geçildikten sonra döndürür; aksi halde 422 VALIDATION_FAILED döner.

Durum: self servis

Temel yol: /api/v1. Son senkronizasyon 2026-05-22.

Temel yetenekler

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

PDF’den XML’e dönüşüm için tek uç nokta
Yapay zeka destekli fatura veri çıkarımı
Otomatik EN 16931 ve KoSIT doğrulaması
XRechnung, ZUGFeRD, UBL ve CII çıktı biçimleri
Sorgulamalı eşzamansız işleme, küçük faturalar yaklaşık 30 saniyede ve daha büyük faturalar 1-2 dakikaya kadar
Güvenli tekrar denemeler için idempotent yazma işlemleri

Teslimat çıktıları

Developer API için makine tarafından okunabilir entegrasyon çıktıları indirin.

OpenAPI JSON

Postman koleksiyonu

API Playground

Hızlı başlangıç

Üç API çağrısı bir dönüşümü tamamlar. Convert endpoint’i /api/v1 altında sunulur ve kimlik doğrulama gerektirir.

POST /api/v1/invoices:convert

Geliştirme aşamasında

PDF’yi yapılandırılmış e-faturaya dönüştür

GET /api/v1/tasks/{task_id}

Geliştirme aşamasında

Task durumunu sorgula

GET /api/v1/tasks/{task_id}/result

Geliştirme aşamasında

Dönüşüm sonucunu indir

Kapalı beta erişimi iste

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Bir hesap oluşturun ve profilinizi açın.
Ön ödemeli API kredileri satın alın veya dahil API erişimi olan bir Enterprise planı kullanın.
API erişimi bölümünden API anahtarı oluşturun.
İlk isteği sunucu tarafı kimlik bilgileriyle çalıştırın; ardından kullanımı izleyin ve anahtarları profilinizden döndürün.

Base URL ve API anahtarları

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Üretim temel URL’si: https://invoice-converter.com/api/v1.
Tüm pilot trafik için aynı üretim API hostunu kullanın: https://invoice-converter.com/api/v1.
Onboarding sırasında düşük hacimli fixture istekleri kullanın; kabul edilen dönüşüm istekleri API kredisi tüketir.
Anahtarları server-side secret olarak ele alın. Browser veya mobil istemcilere gömmeyin.

İlk başarılı istek

Bir API anahtarı oluşturduktan sonra bu akışı minimum başarılı yol olarak kullanın.

Yükleme: Authorization, Idempotency-Key, file=@invoice.pdf ve format=XRECHNUNG ile POST /api/v1/invoices:convert.
Her 2-5 saniyede sorgulayın: durum completed veya failed olana kadar GET /api/v1/tasks/{task_id}.
İndirme: GET /api/v1/tasks/{task_id}/result; varsa X-Correlation-ID ve X-Validation-Proof-Id değerlerini saklayın.
ZUGFeRD PDF çıktısı için format=ZUGFERD gönderin; result endpointi varsayılan olarak hibrit PDF döndürür.

Yaygın payload örnekleri

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

XRECHNUNG: format=XRECHNUNG gönderin; format yoksa varsayılan budur.
ZUGFERD: EN16931 ZUGFeRD/Factur-X hibrit PDF için format=ZUGFERD gönderin.
UBL: EN16931 UBL XML için format=UBL gönderin.
CII: EN16931 CII XML için format=CII gönderin.

Gerekli başlıklar

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Authorization: Bearer <api_key>

Kimlik doğrulama kuralları

API erişimi self servistir. Profilinizden API anahtarları oluşturun, Bearer token olarak kullanın ve dönüşüm otomasyonu için ön ödemeli API kredileri satın alın.

Anahtarlar tenant kapsamlıdır ve icp_ önekini kullanır.
External API erişimi etkinleştirildiğinde API anahtarlarını profilinizden oluşturun, döndürün ve iptal edin. Düz metin anahtarlar yalnızca bir kez gösterildiği için yeni anahtarları hemen kopyalayın.
Eksik veya geçersiz anahtar 401 döndürür.
/api/v1 çağrıları, eksikse otomatik olarak X-Correlation-ID alır.
Yazma çağrıları Idempotency-Key gerektirir; bu değeri tekrar denemelerde sabit tutun.
Backend’inizden server-to-server entegrasyon kullanın. Browser-origin erişimi production’da kısıtlıdır.

İdempotency sözleşmesi

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Her yazma çağrısında Idempotency-Key gönderin.
Idempotency key’leri [A-Za-z0-9._:-]+ ile eşleşmeli ve en fazla 200 karakter olmalıdır.
Kendi key’inizi sağlarsanız aynı key + aynı payload önbellekteki cevabı döndürür.
Aynı key + farklı payload 409 IDEMPOTENCY_CONFLICT döndürür.
Idempotency key’leri 24 hours sonra sona erer.

Uç nokta referansı

Tüm endpoint’ler /api/v1 altında kullanılabilir. Timeout’lar 504, diğer geçici bağlantı hataları 502 olarak görünür; korelasyon ID’leri support ekibinin istekleri uçtan uca izlemesine yardımcı olur.

POST /api/v1/invoices:convert

Geliştirme aşamasında

PDF fatura yükleyin ve asenkron dönüşümü başlatın. Polling için task_id döndürür. İstek: multipart/form-data. Yanıt: 202 Accepted.

GET /api/v1/tasks/{task_id}

Geliştirme aşamasında

Bir dönüşüm task’ının mevcut durumunu sorgulayın. pending, processing, completed veya failed döndürür. failed olduğunda cevap, hata nedenini içeren bir error alanı içerir. İstek: yok (GET). Yanıt: 200 OK.

GET /api/v1/tasks/{task_id}/result

Geliştirme aşamasında

Oluşturulan dosyayı indirin. ZUGFERD taskları varsayılan olarak EN16931 ZUGFeRD/Factur-X hibrit PDF döndürür; diğer formatlar varsayılan olarak XML döndürür. Tekrarlı indirmeler önbelleğe alınmış artefaktlardan sunulabilir. Engelleyici doğrulama sorunları kalırsa endpoint dosya gövdesi olmadan 422 VALIDATION_FAILED döndürür. İstek: yok (GET). Yanıt: 200 OK.

Çıktı biçimi matrisi

Biçim	Söz dizimi	Sürüm / Profil	Content-Type	Uzantı
XRECHNUNG	UBL 2.1 XML	XRechnung 3.0.2	application/xml	.xml
ZUGFERD	Varsayılan EN16931 hibrit PDF/A-3; download=xml ile CII XML	ZUGFeRD 2.4 / Factur-X 1.08	application/pdf veya application/xml	.pdf / .xml
EN16931	UBL 2.1 XML	EN 16931	application/xml	.xml
UBL	UBL 2.1 XML	OASIS UBL 2.1	application/xml	.xml
CII	UN/CEFACT CII XML	D16B	application/xml	.xml

Değişiklik günlüğü

Dışa açık son API değişiklikleri.

2026-05-08

Enterprise olmayan tenant’lar için ön ödemeli External API kredileri eklendi. Enterprise faturalandırması veya ön ödemeli kredisi olmayan tenant’lar için 402 INSUFFICIENT_API_CREDITS belgelendi. İdempotent replay’lerin ek API kredisi tüketmediği doğrulandı. Dönüştürme istekleri dosya artı format olarak sadeleştirildi; çıkarma ayarları sunucu tarafında yönetilir.

2026-03-06

Task-result indirmeleri CII ve ZUGFERD çıktıları için formata sadık hale getirildi. Aynı task’ın tekrarlı XML/PDF indirmeleri için önbelleğe alınmış sonuç artefaktlarının yeniden kullanımı eklendi. Polling kotaları endpoint kapsamlı ağırlıklı rate-limit bucket’ları ile hizalandı.

2026-02-23

Tüm endpoint’lerde daha açık ve tutarlı API hata cevapları eklendi. Convert seçenekleri genişletildi ve task sonuçları için XML/PDF indirme davranışı belgelendi. Daha sıkı idempotency gereksinimleri ve doğrulama ile retry güvenliği iyileştirildi. OpenAPI/Postman artefaktları güncel API davranışıyla hizalandı.

2026-02-20

Durum cevapları durum odaklı çıktıya sadeleştirildi. IndexNow gönderim doğrulaması ve kimlik doğrulama kontrolleri güçlendirildi. Production’da API erişim kontrolleri ve istek sınırlama davranışı sertleştirildi.

Hata sözleşmesi

Kod	HTTP	Tekrar denenebilir	Notlar
AUTHENTICATION_REQUIRED	401	Hayır	Bearer token eksik/boş
INVALID_API_KEY	401	Hayır	API anahtarı bulunamadı, iptal edildi veya süresi doldu
INSUFFICIENT_API_CREDITS	402	Hayır	En az 10 ön ödemeli API kredisi satın alın veya Enterprise faturalandırmasını kullanın
IDEMPOTENCY_KEY_REQUIRED	400	Hayır	Yazma endpoint’i Idempotency-Key olmadan çağrıldı
INVALID_IDEMPOTENCY_KEY	400	Hayır	Idempotency key formatı geçersiz
IDEMPOTENCY_CONFLICT	409	Hayır	Aynı key farklı istek hash’i ile kullanıldı
IDEMPOTENCY_IN_PROGRESS	409	Evet	Aynı key/payload ile daha sonra güvenli biçimde yeniden denenebilir
AUTH_SERVICE_UNAVAILABLE	503	Evet	Auth backend kullanılamıyor
RATE_LIMIT_SERVICE_UNAVAILABLE	503	Evet	Rate-limit backend kullanılamıyor
RATE_LIMITED	429	Evet	Retry-After ve kota header’larına uyun
BAD_REQUEST	400	Hayır	Geçersiz JSON veya geçersiz UUID path parametresi
PAYLOAD_TOO_LARGE	413	Hayır	Yükleme boyutu limitini aşıyor
INVALID_UPLOAD	400	Hayır	Yükleme okunamadı/ayrıştırılamadı
UPLOAD_FAILED	4xx/5xx	Koşullu	Geçersiz istek seçeneklerini düzeltin; yalnızca geçici 5xx durumlarında yeniden deneyin
TASK_NOT_READY	202	Evet	Asenkron tamamlama için tekrar poll edin
TASK_STATUS_FAILED	4xx/5xx	Koşullu	Geçici servis koşulu varsa yeniden deneyin
TASK_RESULT_FAILED	4xx/5xx	Koşullu	Geçici servis koşulu varsa yeniden deneyin
XML_GENERATION_FAILED	500	Evet	Geçici XML üretim hatası veya zaman aşımı
PDF_GENERATION_FAILED	500	Evet	Geçici PDF üretim hatası veya zaman aşımı
PROFILE_MISMATCH	422	Hayır	Invoice CustomizationID conflicts with the selected public format
PROXY_ERROR	502/504	Evet	Geçici bağlantı hatası (timeout için 504)

Yaygın hatalar ve yapılacaklar

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Backoff ile tekrar deneyin: 429, 500, 502, 503, 504.
İstek veya kaynak veriyi düzeltin: 400, 409, 413, 422.
Erişim veya kimlik bilgilerini düzeltin: 401, 403.
Daha sonra polling yapmaya devam edin: 202 TASK_NOT_READY.
422 VALIDATION_FAILED için alanı, kural ID’sini ve düzeltme önerisini insan inceleyiciye gösterin; düzeltilmiş fatura verisiyle sonra tekrar deneyin.

Hız ve yük limitleri

Anahtar bazlı rate limit’ler ve payload boyutu sınırları tüm API çağrıları için uygulanır. Reddedilen istekler kotayı tüketmez.

Endpoint’e duyarlı kotalar maliyet ağırlıklıdır. Convert temel plan kotasını kullanır (varsayılan 30/min ve 500/hour), polling endpoint’leri daha düşük ağırlıklı kota kullanır.
Etkili limitleri cevaplarda X-RateLimit-Limit-Minute ve X-RateLimit-Limit-Hour üzerinden okuyun.
Maksimum PDF yükleme boyutu: 20 MB
Maksimum JSON payload boyutu: 1 MB
Rate-limit cevapları Retry-After, X-RateLimit-Limit-Minute ve X-RateLimit-Limit-Hour içerir.

Yeniden deneme rehberi

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Jitter ile üstel backoff kullanın.
Yalnızca geçici sınıfları (429, 500, 502, 503, 504) ve mümkünse aynı payload ile idempotency key kullanarak yeniden deneyin.
Doğrulama veya sözleşme hatalarını (400, 401, 403, 409, 413) körlemesine yeniden denemeyin.

Görev yaşam döngüsü ve saklama

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Tamamlanan ve başarısız task’lar terminal duruma ulaştıktan sonra 10 minutes kullanılabilir kalır.
İşleme 5 minutes sonra zaman aşımına uğrar; takılı task’lar otomatik olarak failed işaretlenir.
Idempotency key’leri 24 hours sonra sona erer.
Rate-limit sayaçları kayan pencereye göre sıfırlanır.

Destek modeli

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Mesai saatlerinde destek.
Hedef ilk cevap süresi: 1 iş günü.

Teknik geri bildirim gönderin

Uygulama sorularınızı, riskleri ve gerekli sözleşme değişikliklerini ekibimizle paylaşın.

Teknik geri bildirim e-postası gönder

Postman ve OpenAPI kullanımı

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Postman koleksiyonunu içe aktarın ve baseUrl, apiKey, yeni bir idempotencyKey değişkeni ayarlayın.
Koleksiyonu sırayla çalıştırın: convert, durum sorgulama, ardından sonucu alma.
OpenAPI JSON ile typed client üretin; dosya yükleme, polling ve binary result işleme için entegrasyon testleri tutun.
Support’un istekleri uçtan uca izleyebilmesi için X-Correlation-ID değerini loglarda saklayın.

Entegrasyon

Markdown dışa aktar

Harici API V1 Dokümantasyonu

Self servis API uygulaması ve incelemesi için teknik dokümantasyon paketi. Bu sayfa harici API sözleşmesini, erişim modelini ve entegrasyon sınırlarını özetler.

Genel görünüm

Durum: self servis

Temel yol: /api/v1. Son senkronizasyon 2026-05-22.

Temel yetenekler

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

PDF’den XML’e dönüşüm için tek uç nokta
Yapay zeka destekli fatura veri çıkarımı
Otomatik EN 16931 ve KoSIT doğrulaması
XRechnung, ZUGFeRD, UBL ve CII çıktı biçimleri
Sorgulamalı eşzamansız işleme, küçük faturalar yaklaşık 30 saniyede ve daha büyük faturalar 1-2 dakikaya kadar
Güvenli tekrar denemeler için idempotent yazma işlemleri

Teslimat çıktıları

Developer API için makine tarafından okunabilir entegrasyon çıktıları indirin.

OpenAPI JSON

Postman koleksiyonu

API Playground

Hızlı başlangıç

Üç API çağrısı bir dönüşümü tamamlar. Convert endpoint’i /api/v1 altında sunulur ve kimlik doğrulama gerektirir.

POST /api/v1/invoices:convert

Geliştirme aşamasında

PDF’yi yapılandırılmış e-faturaya dönüştür

GET /api/v1/tasks/{task_id}

Geliştirme aşamasında

Task durumunu sorgula

GET /api/v1/tasks/{task_id}/result

Geliştirme aşamasında

Dönüşüm sonucunu indir

Kapalı beta erişimi iste

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Bir hesap oluşturun ve profilinizi açın.
Ön ödemeli API kredileri satın alın veya dahil API erişimi olan bir Enterprise planı kullanın.
API erişimi bölümünden API anahtarı oluşturun.
İlk isteği sunucu tarafı kimlik bilgileriyle çalıştırın; ardından kullanımı izleyin ve anahtarları profilinizden döndürün.

Base URL ve API anahtarları

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Üretim temel URL’si: https://invoice-converter.com/api/v1.
Tüm pilot trafik için aynı üretim API hostunu kullanın: https://invoice-converter.com/api/v1.
Onboarding sırasında düşük hacimli fixture istekleri kullanın; kabul edilen dönüşüm istekleri API kredisi tüketir.
Anahtarları server-side secret olarak ele alın. Browser veya mobil istemcilere gömmeyin.

İlk başarılı istek

Bir API anahtarı oluşturduktan sonra bu akışı minimum başarılı yol olarak kullanın.

Yükleme: Authorization, Idempotency-Key, file=@invoice.pdf ve format=XRECHNUNG ile POST /api/v1/invoices:convert.
Her 2-5 saniyede sorgulayın: durum completed veya failed olana kadar GET /api/v1/tasks/{task_id}.
İndirme: GET /api/v1/tasks/{task_id}/result; varsa X-Correlation-ID ve X-Validation-Proof-Id değerlerini saklayın.
ZUGFeRD PDF çıktısı için format=ZUGFERD gönderin; result endpointi varsayılan olarak hibrit PDF döndürür.

Yaygın payload örnekleri

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

XRECHNUNG: format=XRECHNUNG gönderin; format yoksa varsayılan budur.
ZUGFERD: EN16931 ZUGFeRD/Factur-X hibrit PDF için format=ZUGFERD gönderin.
UBL: EN16931 UBL XML için format=UBL gönderin.
CII: EN16931 CII XML için format=CII gönderin.

Gerekli başlıklar

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Authorization: Bearer <api_key>

Kimlik doğrulama kuralları

API erişimi self servistir. Profilinizden API anahtarları oluşturun, Bearer token olarak kullanın ve dönüşüm otomasyonu için ön ödemeli API kredileri satın alın.

Anahtarlar tenant kapsamlıdır ve icp_ önekini kullanır.
External API erişimi etkinleştirildiğinde API anahtarlarını profilinizden oluşturun, döndürün ve iptal edin. Düz metin anahtarlar yalnızca bir kez gösterildiği için yeni anahtarları hemen kopyalayın.
Eksik veya geçersiz anahtar 401 döndürür.
/api/v1 çağrıları, eksikse otomatik olarak X-Correlation-ID alır.
Yazma çağrıları Idempotency-Key gerektirir; bu değeri tekrar denemelerde sabit tutun.
Backend’inizden server-to-server entegrasyon kullanın. Browser-origin erişimi production’da kısıtlıdır.

İdempotency sözleşmesi

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Her yazma çağrısında Idempotency-Key gönderin.
Idempotency key’leri [A-Za-z0-9._:-]+ ile eşleşmeli ve en fazla 200 karakter olmalıdır.
Kendi key’inizi sağlarsanız aynı key + aynı payload önbellekteki cevabı döndürür.
Aynı key + farklı payload 409 IDEMPOTENCY_CONFLICT döndürür.
Idempotency key’leri 24 hours sonra sona erer.

Uç nokta referansı

POST /api/v1/invoices:convert

Geliştirme aşamasında

PDF fatura yükleyin ve asenkron dönüşümü başlatın. Polling için task_id döndürür. İstek: multipart/form-data. Yanıt: 202 Accepted.

GET /api/v1/tasks/{task_id}

Geliştirme aşamasında

GET /api/v1/tasks/{task_id}/result

Geliştirme aşamasında

Çıktı biçimi matrisi

Biçim	Söz dizimi	Sürüm / Profil	Content-Type	Uzantı
XRECHNUNG	UBL 2.1 XML	XRechnung 3.0.2	application/xml	.xml
ZUGFERD	Varsayılan EN16931 hibrit PDF/A-3; download=xml ile CII XML	ZUGFeRD 2.4 / Factur-X 1.08	application/pdf veya application/xml	.pdf / .xml
EN16931	UBL 2.1 XML	EN 16931	application/xml	.xml
UBL	UBL 2.1 XML	OASIS UBL 2.1	application/xml	.xml
CII	UN/CEFACT CII XML	D16B	application/xml	.xml

Değişiklik günlüğü

Dışa açık son API değişiklikleri.

2026-05-08

2026-03-06

2026-02-23

2026-02-20

Hata sözleşmesi

Kod	HTTP	Tekrar denenebilir	Notlar
AUTHENTICATION_REQUIRED	401	Hayır	Bearer token eksik/boş
INVALID_API_KEY	401	Hayır	API anahtarı bulunamadı, iptal edildi veya süresi doldu
INSUFFICIENT_API_CREDITS	402	Hayır	En az 10 ön ödemeli API kredisi satın alın veya Enterprise faturalandırmasını kullanın
IDEMPOTENCY_KEY_REQUIRED	400	Hayır	Yazma endpoint’i Idempotency-Key olmadan çağrıldı
INVALID_IDEMPOTENCY_KEY	400	Hayır	Idempotency key formatı geçersiz
IDEMPOTENCY_CONFLICT	409	Hayır	Aynı key farklı istek hash’i ile kullanıldı
IDEMPOTENCY_IN_PROGRESS	409	Evet	Aynı key/payload ile daha sonra güvenli biçimde yeniden denenebilir
AUTH_SERVICE_UNAVAILABLE	503	Evet	Auth backend kullanılamıyor
RATE_LIMIT_SERVICE_UNAVAILABLE	503	Evet	Rate-limit backend kullanılamıyor
RATE_LIMITED	429	Evet	Retry-After ve kota header’larına uyun
BAD_REQUEST	400	Hayır	Geçersiz JSON veya geçersiz UUID path parametresi
PAYLOAD_TOO_LARGE	413	Hayır	Yükleme boyutu limitini aşıyor
INVALID_UPLOAD	400	Hayır	Yükleme okunamadı/ayrıştırılamadı
UPLOAD_FAILED	4xx/5xx	Koşullu	Geçersiz istek seçeneklerini düzeltin; yalnızca geçici 5xx durumlarında yeniden deneyin
TASK_NOT_READY	202	Evet	Asenkron tamamlama için tekrar poll edin
TASK_STATUS_FAILED	4xx/5xx	Koşullu	Geçici servis koşulu varsa yeniden deneyin
TASK_RESULT_FAILED	4xx/5xx	Koşullu	Geçici servis koşulu varsa yeniden deneyin
XML_GENERATION_FAILED	500	Evet	Geçici XML üretim hatası veya zaman aşımı
PDF_GENERATION_FAILED	500	Evet	Geçici PDF üretim hatası veya zaman aşımı
PROFILE_MISMATCH	422	Hayır	Invoice CustomizationID conflicts with the selected public format
PROXY_ERROR	502/504	Evet	Geçici bağlantı hatası (timeout için 504)

Yaygın hatalar ve yapılacaklar

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Backoff ile tekrar deneyin: 429, 500, 502, 503, 504.
İstek veya kaynak veriyi düzeltin: 400, 409, 413, 422.
Erişim veya kimlik bilgilerini düzeltin: 401, 403.
Daha sonra polling yapmaya devam edin: 202 TASK_NOT_READY.
422 VALIDATION_FAILED için alanı, kural ID’sini ve düzeltme önerisini insan inceleyiciye gösterin; düzeltilmiş fatura verisiyle sonra tekrar deneyin.

Hız ve yük limitleri

Anahtar bazlı rate limit’ler ve payload boyutu sınırları tüm API çağrıları için uygulanır. Reddedilen istekler kotayı tüketmez.

Endpoint’e duyarlı kotalar maliyet ağırlıklıdır. Convert temel plan kotasını kullanır (varsayılan 30/min ve 500/hour), polling endpoint’leri daha düşük ağırlıklı kota kullanır.
Etkili limitleri cevaplarda X-RateLimit-Limit-Minute ve X-RateLimit-Limit-Hour üzerinden okuyun.
Maksimum PDF yükleme boyutu: 20 MB
Maksimum JSON payload boyutu: 1 MB
Rate-limit cevapları Retry-After, X-RateLimit-Limit-Minute ve X-RateLimit-Limit-Hour içerir.

Yeniden deneme rehberi

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Jitter ile üstel backoff kullanın.
Yalnızca geçici sınıfları (429, 500, 502, 503, 504) ve mümkünse aynı payload ile idempotency key kullanarak yeniden deneyin.
Doğrulama veya sözleşme hatalarını (400, 401, 403, 409, 413) körlemesine yeniden denemeyin.

Görev yaşam döngüsü ve saklama

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Tamamlanan ve başarısız task’lar terminal duruma ulaştıktan sonra 10 minutes kullanılabilir kalır.
İşleme 5 minutes sonra zaman aşımına uğrar; takılı task’lar otomatik olarak failed işaretlenir.
Idempotency key’leri 24 hours sonra sona erer.
Rate-limit sayaçları kayan pencereye göre sıfırlanır.

Destek modeli

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Mesai saatlerinde destek.
Hedef ilk cevap süresi: 1 iş günü.

Teknik geri bildirim gönderin

Uygulama sorularınızı, riskleri ve gerekli sözleşme değişikliklerini ekibimizle paylaşın.

Teknik geri bildirim e-postası gönder

Postman ve OpenAPI kullanımı

Bu noktaları bu bölüm için pratik kontrol adımları olarak kullanın.

Postman koleksiyonunu içe aktarın ve baseUrl, apiKey, yeni bir idempotencyKey değişkeni ayarlayın.
Koleksiyonu sırayla çalıştırın: convert, durum sorgulama, ardından sonucu alma.
OpenAPI JSON ile typed client üretin; dosya yükleme, polling ve binary result işleme için entegrasyon testleri tutun.
Support’un istekleri uçtan uca izleyebilmesi için X-Correlation-ID değerini loglarda saklayın.