Paraşüt API Entegrasyonu: Yetkilendirme, Test Ortamı ve İstek Sınırı

Paraşüt API belgeleri nerede ve erişim için ne gerekir?

Paraşüt API belgeleri, devhub.parasut.com adresindeki Geliştirici Portalı'nda yayımlanır ve erişim de bu portaldan yapılan başvuruyla açılır. Eski belge adresi (apidocs) artık bu portala yönleniyor. "Paraşüt API docs" aramasıyla eski sayfalara ya da yıllar önce yazılmış örneklere ulaşırsanız, güncel olanın portal olduğunu bilin.

Portalın "Yardımcı Kaynaklar" bölümünde OpenAPI 3 tanımı, Postman koleksiyonu, staging ve canlı ortam için TypeScript örnek uygulaması ve geliştirme asistanları için bir kural dosyası var. OpenAPI tanımının başlığı "Paraşüt - API V4", sürümü 4.1.0. Tanımın değişiklik kaydında 23 Ekim 2026 tarihli kapsamlı bir güncelleme yer alıyor: webhook, çek ve senet, açılış bakiyesi, fiyat listesi, depo transferi gibi yeni kaynaklar ve yeni kimlik doğrulama kuralları bu güncellemeyle eklenmiş.

Erişim için gerekenleri şöyle özetleyebiliriz:

İki satır özellikle önemli. Geri dönüş adresi sonradan değiştirilemediği için yazılımın nerede çalışacağı netleşmeden başvurulmamalı. Jeton da onayı veren kullanıcının o firmadaki rolüyle sınırlıdır; entegrasyon izni olmayan bir kullanıcıyla kurulan bağlantı 403 alır.

Başvuruyu firmanın kendisi yapar. Mersin merkezli yazılım ekibi olarak biz hiçbir yazılım üreticisinin bayisi ya da iş ortağı değiliz; Paraşüt entegrasyonu yazarken de başvuru firmanın kendi hesabından yürür, biz hangi bilgilerin isteneceğini önceden söyleriz.

Kimlik doğrulama adım adım: OAuth 2.0 ve PKCE

Paraşüt API'de kimlik doğrulama, OAuth 2.0 Authorization Code akışıyla ve PKCE adı verilen ek bir doğrulamayla yapılır; belgeye göre PKCE tüm istemcilerde zorunludur ve yalnızca S256 yöntemi kabul edilir. Akış altı adımda ilerler:

1. Yetkilendirme adresine yönlendirme. Uygulamanız kullanıcıyı Paraşüt'ün kimlik sunucusuna yönlendirir. Adreste istemci kimliği, geri dönüş adresi, rastgele bir durum değeri ve PKCE özeti bulunur.
2. Paraşüt'e giriş. Kullanıcı Paraşüt giriş ekranında e-posta ve şifresini girer. Şifre sizin uygulamanıza hiç gelmez.
3. Onay ekranı. Kullanıcı, uygulamanın hangi verilere erişeceğini gösteren ekranı onaylar.
4. Kodun dönmesi. Tarayıcı geri dönüş adresinize bir yetkilendirme koduyla döner. Durum değeri oturumdakiyle eşleşmiyorsa istek reddedilir.
5. Kodun jetona çevrilmesi. Sunucunuz kodu, gizli anahtarı ve PKCE doğrulayıcısını kimlik sunucusuna gönderip erişim ve yenileme jetonlarını alır.
6. API çağrısı. Erişim jetonu her isteğin yetkilendirme başlığında taşınır.

Kısa bir örnek; tüm değerler yer tutucudur.

# 5. adım: yetkilendirme kodunu jetona çevir (yalnızca sunucuda çalışır)
curl -X POST "https://id.parasut.com/realms/parasut/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "client_id=CLIENT_ID" \
  -d "client_secret=CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=REDIRECT_URI" \
  -d "code_verifier=CODE_VERIFIER"

# 6. adım: vergi numarasıyla cari ara
curl -G "https://api.parasut.com/v4/COMPANY_ID/contacts" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Accept: application/json" \
  --data-urlencode "filter[tax_number]=VERGI_NO" \
  --data-urlencode "page[size]=25"

Belgedeki örnek yanıtta erişim jetonunun süresi 7.200 saniye, yani iki saat; yenileme jetonunun süresi ise 2.592.000 saniye, yani otuz gün. Belge bu değerlerin yanıttaki alanlardan okunmasını ve süre dolmadan yenileme yapılmasını söylüyor; bu yüzden süreyi koda sabit yazmayın. Yenilemede genellikle yeni bir yenileme jetonu da döner ve sonraki seferde dönen son jeton kullanılmalıdır. Bu ayrıntı atlanırsa bağlantı bir süre sonra sessizce kopar.

Gizli anahtar konusunda belge nettir. Yeni istemciler varsayılan olarak gizli anahtarlı (confidential) oluşturulur; anahtar portalın "API Bilgilerim" sayfasında görünür, e-postayla gönderilmez ve yalnızca sunucuda saklanır. "Secret'ı Yenile" ile yeni anahtar üretildiği anda eski anahtar hemen geçersiz olur, geçiş süresi yoktur. Arka ucu olmayan masaüstü ya da mobil uygulamalar başvuruda gizli anahtarsız (public) istemci talep edebilir.

Eski bir not: geçmişte yazılmış rehberlerde ve topluluk kütüphanelerinde, kullanıcı adı ve şifreyle doğrudan jeton alan örnekler görülür. Paraşüt'ün 2026 itibarıyla yayımladığı belgede yeni istemciler için anlatılan yol bu değil. Eski yöntemle kurulmuş bir bağlantının çalışmaya devam edip etmeyeceğini belgede bulamadık; böyle bir bağlantınız varsa bunu Paraşüt'ten teyit edin.

Paraşüt sandbox var mı? Test ortamı nasıl isteniyor?

Evet, Paraşüt'ün belgelediği bir test ortamı var; Paraşüt buna "sandbox" değil "staging" diyor. Belgeye göre staging istemcisi, sizin için oluşturulan bir Paraşüt staging şirketine bağlıdır. Bu şirket henüz oluşturulmadıysa "API Bilgilerim" sayfasından oluşturulabilir ve altı ay sonra kendiliğinden silinir. Staging için kimlik sunucusu da ayrıdır: canlıdaki id.parasut.com yerine id-staging.parasut.com kullanılır.

Burada iki belirsizlik var ve bunları saklamıyoruz:

• Pakete bağlılık. Portalın ücretlendirme sayfası "Staging ortamı erişimi"ni Plus paketinin ek özelliği olarak listeliyor ve Plus paketi Kasım 2026 itibarıyla "yakında" olarak görünüyor. Başvuruya açık Temel pakette staging'e erişip erişemeyeceğinizi belgeden kesin çıkaramadık; başvuru sonrası "API Bilgilerim" sayfasında ya da Paraşüt'e sorarak teyit edilir.
• Staging API adresi. Belge staging için kimlik sunucusu adresini veriyor, ancak staging'de API isteklerinin hangi temel adrese gideceğini açıkça yazmıyor. Bu da kurulumda teyit edilir.

Staging erişimi yoksa test nasıl yapılır? Bizim önerdiğimiz sıra şu: önce canlı firmada yalnızca okuma yapan bir pilot kurulur; cari, ürün ve fatura listeleri doğru okunuyor mu bakılır. Yazma testleri için mali müşavirinizle birlikte ayrılmış bir test carisi kullanılır. Test faturaları hiçbir koşulda e-Fatura ya da e-Arşiv olarak resmileştirilmez, çünkü resmileşen belge artık bir test kaydı değildir. API'de faturayı iptal eden ve silen uçlar bulunuyor; yine de canlı firmada açılan her test faturası gerçek bir muhasebe kaydıdır ve mali müşavirinizin defterine dokunur. Bu yüzden canlıda yazma testi az, planlı ve mali müşavirinizin bilgisiyle yapılır.

İstek sınırı: 10 saniyede 10 istek ve aylık kota ne demek?

Paraşüt API'nin istek sınırı başvurulan pakete göre değişir; Kasım 2026 itibarıyla başvuruya açık olan Temel pakette sınır 10 saniyede 10 istek, aylık kota ise 25.000 istektir. Belge, paketin üç şeyi belirlediğini söylüyor: 10 saniyede kaç istek yapılabileceği, bir ayda toplam kaç istek yapılabileceği ve hangi firmalar için işlem yapılabileceği.

Ücretlendirme sayfasındaki tablo şöyle:

Sınır dolduğunda API, belgeye göre HTTP 429 döner ve yanıtta ne zaman yeniden denenebileceğine dair süre bilgisi bulunur; bu bilginin hangi başlıkta ya da alanda geldiği ise belgede yazmıyor. Bu yüzden entegrasyon önce yanıttaki süreyi okumayı dener, okuyamazsa kademeli artan ve rastgele dağıtılan bir bekleme uygular.

Aylık kota, hızdan daha sinsi bir sınırdır. Örnek senaryo üzerinden bakalım. Diyelim ki ayda 600 satış faturası API ile açılıyor ve her fatura için cari arama, fatura oluşturma, gelen kutusu sorgusu, resmileştirme, iki iş durumu sorgusu ve bir PDF isteği gerekiyor. Bu, fatura başına yedi istek, ayda 4.200 istek eder. Buna değişiklikleri yakalamak için her beş dakikada bir yapılan tek bir liste sorgusunu ekleyin: günde 288, otuz günde 8.640 istek. Toplam kotanın içinde kalır. Ama aynı sorgu her dakikaya çekilirse yalnız o sorgu ayda 43.200 istek eder ve Temel paketin kotasını tek başına aşar.

Yoklama sıklığı iş ihtiyacına göre seçilir. Webhook bu sorunu hafifletir ama belgeye göre webhook uçları yalnızca paketi webhook içeren istemcilerle kullanılabilir; ücretlendirme sayfasında webhook Pro paketinde görünüyor. Webhook olsa bile belge, her değişiklik için bildirim gönderileceğini ve bildirimlerin sırayla geleceğini taahhüt etmiyor; eksiksiz bir kopya tutmak için düzenli eşitleme yine gerekiyor.

Paraşüt API ile hangi kayıtlar okunur, hangileri yazılır?

Paraşüt API ile cari, ürün, satış ve alış faturası, tahsilat, irsaliye ve e-belge işlemlerinin büyük kısmı hem okunur hem yazılır. Aşağıdaki tablo, işletmelerin en sık sorduğu kayıtları özetliyor.

Birkaç teknik kural da belgede yazılı. İstekler JSON:API biçimindedir; tüm yollar firma numarasıyla başlar. Listelerin çoğunda sayfa başına en fazla 25 kayıt alınır. Para birimi kodu "TRY" değil "TRL" olarak gönderilir. e-Fatura ve e-Arşiv isteği hemen belge üretmez: yanıt bir iş kimliği döner ve iş tamamlanana kadar durum sorgulanır. PDF henüz hazır değilse ilgili uç içerik dönmez; biraz sonra tekrar istenir.

Fatura ve cari ekstre otomasyonu da bu kayıt türlerinin üstüne kurulur; toplu fatura kesme ve ekstre gönderimini ayrı yazılarda anlattık.

Sık yapılan hatalar: tekrar gönderim, yuvarlama, KDV satırı, cari eşleştirme

Paraşüt API entegrasyonlarında hataların çoğu bağlantıda değil, kaydın içeriğinde çıkar; dört başlık öne çıkıyor.

Tekrar gönderim ve mükerrer fatura

Fatura isteği gönderilmiş, bağlantı kopmuş, yanıt alınamamışsa faturanın oluşup oluşmadığı bilinmez. Körlemesine tekrar denemek ikinci faturayı açar. Paraşüt bunun için satış faturasında bir tekrar önleme anahtarı tanımlıyor: her fatura için bir UUID üretilir, istekten önce kendi tarafınızda saklanır ve yeniden denemede aynı anahtar gönderilir. Anahtar daha önce kullanıldıysa belgeye göre ikinci fatura açılmaz, 422 döner ve hata içinde mevcut faturanın kimliği gelir.

"external_reference_key": {
  "data": {
    "type": "external_reference_keys",
    "attributes": { "key": "UUID_YER_TUTUCU" }
  }
}

Yuvarlama ve toplamlar

Faturanın toplamları Paraşüt tarafında kalemlerden hesaplanır; genel toplam, ara toplam ve toplam KDV alanları salt okunurdur, dışarıdan gönderilemez. Paraşüt'ün belgesinde kalem ve fatura düzeyinde yuvarlama kuralını anlatan bir bölüm bulamadık. Kendi sisteminiz KDV'yi fatura toplamı üzerinden, Paraşüt kalem bazında hesaplıyorsa kuruş farkı çıkabilir. Bu yüzden fatura oluşturulduktan sonra dönen toplam kendi toplamınızla karşılaştırılır; fark varsa kayıt bir kontrol listesine düşer, sessizce geçilmez. Bir de isim tuzağı var: tanımda "net_total" alanı genel toplamı, "gross_total" alanı ara toplamı ifade ediyor. Alan adından anlam çıkarmayın, açıklamasını okuyun.

KDV satırı ve vergi kodları

Her fatura kaleminde KDV oranı zorunlu alandır. Ürün kartındaki oranla kaleme gönderilen oran farklıysa hangisinin geçerli olacağı sizin kodunuzda bilinçli bir karar olmalı. Tevkifat oranı için kalemde, KDV istisnası gerekçe kodu için e-belge isteğinde ayrı alanlar var; hangi kodun kullanılacağı ise teknik değil muhasebe kararıdır ve mali müşavirinizle belirlenir.

Cari eşleştirme

Cariyi adla aramak en yaygın hatadır. Aynı unvan iki farklı yazımla kayıtlıysa ya da iki cari aynı adı taşıyorsa fatura yanlış kişiye gider. Belge, cari listesinde vergi numarasıyla filtrelemeye izin veriyor; eşleştirme bu numarayla yapılmalı ve sizin sisteminizdeki cari kodunun Paraşüt'teki karşılığı ayrı bir eşleme tablosunda tutulmalı. Vergi numarası boş olan şahıs müşterileri için hangi alanın anahtar olacağı keşifte kararlaştırılır.

Son bir uyarı: belgeye göre olağandışı sayıda 401 ya da 403 yanıtı alan istemciler engellenebilir ve devre dışı bırakılabilir. 401'de jeton bir kez yenilenip istek bir kez tekrarlanır; yetki hatası olan 403 ise hiç tekrar denenmez, kullanıcıya gösterilir.

Sıkça Sorulan Sorular

Paraşüt API ücretli mi?

Paraşüt'ün ücretlendirme sayfası bireysel kullanım için Temel, Plus ve Pro paketlerini, birden çok firmaya hizmet verenler için ise özel iş ortaklığı planını listeliyor. Kasım 2026 itibarıyla başvuruya açık olan Temel pakettir ve sayfadaki ücret satırında "Ücretsiz" yazıyor; Plus ve Pro "yakında" görünüyor, iş ortaklığı planı ise özel olarak belirleniyor. Bu, Paraşüt aboneliğinizden ayrı olarak API erişim paketine ait bir bilgidir; güncel koşulları başvurmadan önce portalın ücretlendirme sayfasından kontrol edin.

Paraşüt sandbox hesabı nasıl açılır?

Paraşüt test ortamına "staging" diyor. Belgeye göre staging istemcisi sizin için oluşturulan bir staging şirketine bağlıdır, bu şirket "API Bilgilerim" sayfasından oluşturulabilir ve altı ay sonra silinir. Ücretlendirme sayfası staging erişimini Plus paketinde gösterdiği için Temel pakette kullanılabilirliği başvuru sonrası teyit edilir.

Kullanıcı adı ve şifreyle jeton alan eski kodum çalışır mı?

Güncel belge yeni istemciler için yalnızca Authorization Code ve PKCE akışını anlatıyor; eski yöntemle kurulmuş bağlantıların durumunu yazmıyor. Geçiş planını Paraşüt'ten teyit ederek yapın.

Paraşüt değişiklikleri webhook ile bildirir mi?

OpenAPI tanımına 23 Ekim 2026 tarihli güncellemeyle webhook kaynakları eklendi; cari, ürün, satış faturası, irsaliye ve gelen e-Fatura gibi kayıtlar için olaylar tanımlı. Ancak webhook yalnızca paketi webhook içeren istemcilerle kullanılabiliyor ve belge, her değişikliğin bildirileceğini taahhüt etmiyor. Bu yüzden düzenli eşitleme yine gerekir.

Birden çok firmanın Paraşüt hesabına tek uygulamayla bağlanabilir miyim?

Bireysel paketler tek firma, yani başvuran firmanın kendisi içindir. Birden çok müşterinin Paraşüt verisine erişecek ticari bir ürün geliştiriyorsanız portal sizi iş ortaklığı başvurusuna yönlendiriyor. Tek bir firmanın kendi işi için yaptırdığı entegrasyonda ise başvuruyu o firma yapar.

Paraşüt entegrasyonunuzu planlamak için sonraki adım

Başlamadan önce üç soruyu cevaplayın: hazır bir uygulama işinizi görüyor mu, başvuruyu hangi kullanıcı ve hangi geri dönüş adresiyle yapacaksınız, ayda kaç kayıt API'den geçecek? Bu üç cevap, Paraşüt entegrasyonunun kapsamını ve paket ihtiyacını büyük ölçüde belirler.

Hazır uygulama yetmiyorsa Mersin merkezli yazılım ekibimiz olarak sipariş, fatura, tahsilat ve cari akışlarını Paraşüt'ün resmî API'si üzerinden, programınızı değiştirmeden yazıyoruz. Ücretsiz online keşif görüşmesi için iletişime geçin ya da WhatsApp'tan yazın; en geç 24 saat içinde dönüş yaparız. Kapsam ve fiyat sözleşmede yazılır, teslim sonrası 15 gün ücretsiz hata düzeltme uygulanır.