# 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 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. 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-23. ## Temel yetenekler - 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](/developer-api/v1/openapi.json) - [Postman koleksiyonu](/developer-api/v1/postman.json) - [API Playground](/developer-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 - 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ı - Ü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 - `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 - Authorization: Bearer ## 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 - 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 - 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 - 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 - 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 - 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](mailto:contact@invoice-converter.com?subject=Harici%20API%20V1%20teknik%20inceleme%20geri%20bildirimi&body=Merhaba%20Invoice-Converter%20ekibi%2C%0D%0A%0D%0AHarici%20API%20V1%20dok%C3%BCmantasyonunu%20inceledik%20ve%20a%C5%9Fa%C4%9F%C4%B1daki%20geri%20bildirimlerimiz%20var%3A%0D%0A%0D%0A1)%2520%0D%0A2)%2520%0D%0A3)%2520%0D%0A%0D%0ASayg%C4%B1lar%C4%B1m%C4%B1zla%2C) ## Postman ve OpenAPI kullanımı - 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.