Paraşüt API Örnek Uygulaması

DevHub'da başvurudan Paraşüt'te resmileşmiş bir satış faturasına kadar adım adım. Köşeli ifadeler (böyle) ekranlarda gördüğünüz buton ve başlıklardır.

1 · DevHub'da API başvurusu

1. devhub.parasut.com › API Başvuru sayfasını açın ve başvuru türünü seçin:
   • Paraşüt Kullanıcısıyım: kendi şirketiniz için. Paraşüt ile Giriş Yap ile Paraşüt hesabınızla girin.
   • İş Ortağı Olmak İstiyorum: ticari bir uygulama ya da birden fazla şirket için. Giriş Yap / Kayıt Ol ile girin.
2. 1. Adım — Başvuru Bilgileri:
   • Redirect URL (production): https:// ile başlayan, gerçek bir alan adı; en fazla 3 adet. Sonradan değiştirilemez. Prod testleri için uygulamanızın işlemediği ayrı bir yol eklemeniz önerilir, ör. https://app.sirketim.com/parasut-test/callback (bkz. 8).
   • Paraşüt bağlantısı nereden yapılacak? sorusunda uygulamanızın bir sunucusu varsa seçili gelen Bir sunucudan: client secret sunucuda güvenle saklanabilir (web uygulaması ya da backend servisi; confidential client, önerilen) seçeneğini bırakın (confidential client: secret ile çalışır; bu örnek de öyle).
   • API entegrasyon sürecinde kullanmak amacıyla Staging/Test ortamı istiyorum sorusu çıkarsa Evet deyin ve Staging/Test Ortamı Redirect URL'leri alanına http://localhost:4747/callback ekleyin. Staging URL'leri sonradan API Bilgilerim'den değiştirilebilir.
3. 2. Adım — Firma & Yetkili Bilgileri: alanları doldurun, onay kutularını işaretleyip Başvuru Yap'a basın.
4. Sonrası:
   • Paraşüt kullanıcısı: istemci hemen oluşturulur: Başvurunuz Oluşturuldu.
   • İş ortağı: Başvurunuz İletildi → değerlendirme → Başvurunuz Onaylandı e-postası → Başvuruma Devam Et → sözleşmeyi onaylayıp Onayla ve Başvuruyu Tamamla. Değerlendirme sürerken staging ortamında geliştirmeye başlayabilirsiniz.

2 · API bilgileri (Client ID / Secret)

1. DevHub'da Hesabım › API Bilgilerim sayfasını açın; Production ve Staging sekmeleri ayrı istemcilerdir.
2. Staging sekmesinde Client ID'yi kopyalayın. Client Secret'ı göz ikonuyla gösterip kopyalayın (60 saniye sonra yeniden maskelenir; DevHub saklamaz, e-postayla gönderilmez).
3. Redirect URL'ler altında http://localhost:4747/callback yoksa Düzenle ile ekleyip Kaydet'e basın.

Secret'ı Yenile eski secret'ı hemen geçersiz kılar: yeniledikten sonra yeni secret'ı 1 · Bağlantı › İstemci bilgileri'ne girip Kaydet'e basın (ya da .env dosyasını güncelleyip uygulamayı yeniden başlatın).

3 · Paraşüt staging hesabı

Staging istemciniz tek bir Paraşüt staging hesabına (şirkete) bağlıdır; testler o hesapta yapılır.

1. API Bilgilerim › Staging sekmesindeki Paraşüt Staging Hesabı kutusunda Staging Hesabı Oluştur'a basın (başvurunun başarı ekranında otomatik oluşturulmuş da olabilir).
2. Staging hesabınız hazır penceresindeki Şirket No, Kullanıcı Adı ve Geçici Şifre'yi kaydedin. Geçici şifre yalnızca bu ekranda gösterilir.
3. İsterseniz Seed Data Oluştur ile hesaba örnek veriler ekleyin (hesap başına bir kez).
4. Paraşüt'te Aç ile hesaba web'den de girebilirsiniz. Hesap oluşturulduktan 6 ay sonra otomatik silinir.

4 · Bu uygulamayı kurun

1. Node.js 22+ kurulu olsun. Klasörde npm install çalıştırın.
2. npm start → http://localhost:4747.
3. Üstten Staging'i seçin; 1 · Bağlantı › İstemci bilgileri'ne Client ID, Client Secret (public client ise boş) ve Redirect URI'yi girip Kaydet'e basın. Redirect URI, DevHub'daki staging redirect URL ile birebir aynı olmalı.
4. Ya da .env.example dosyasını .env olarak kopyalayıp STAGING_CLIENT_ID, STAGING_CLIENT_SECRET ve STAGING_REDIRECT_URI'yi doldurun; .env her değiştiğinde uygulamayı yeniden başlatın. Arayüzden girilen bilgiler .env'dekilerin yerine geçer; Bilgileri sil .env'e döner.

Arayüzden girilen bilgiler yalnızca bu uygulamanın belleğinde tutulur, diske yazılmaz; uygulama kapanınca ya da 30 dakika kullanılmayınca silinir. Secret tarayıcıya geri gönderilmez; token'lar konsolda maskelenir.

5 · Paraşüt hesabını bağlayın (OAuth)

1. Üstten Staging ortamını seçin ve Paraşüt Hesabını Bağla'ya basın.
2. Paraşüt giriş ekranında 3. adımdaki staging Kullanıcı Adı ve Geçici Şifre ile girin.
3. Onay (consent) ekranında erişimi onaylayın. Tarayıcı bu uygulamaya döner ve durum Bağlı olur. Konsolda POST /token isteğini (authorization code + PKCE) görürsünüz.
4. Firmaları Yükle → listeden staging hesabınızın Şirket No'sunu seçin.

Access token süresi dolmadan 60 saniye önce otomatik yenilenir; Token Yenile ile elle de yenileyebilirsiniz.

6 · Satış faturası: oluşturmadan resmileştirmeye

Fatura Akışı sekmesinde alanları kontrol edip Tüm Akışı Çalıştır'a basın ya da adımları tek tek çalıştırın. Her adımın istek/yanıtı alttaki konsolda görünür.

Adım	Ne olur?
Müşteri oluştur	Müşteri açılır. Varsayılan TCKN 11111111111 (nihai tüketici) e-Fatura mükellefi değildir → akış e-Arşiv keser.
Ürün oluştur	Fatura kalemindeki ürün/hizmet.
Satış faturası oluştur	Bugünün tarihiyle fatura; id ve tahsil edilecek tutar akış durumuna yazılır.
Tahsilat ekle (opsiyonel)	Tahsilat ekle işaretliyse ilk TRL kasa/banka hesabına tam tahsilat. Hesapta bir TRL kasa/banka hesabı olmalı.
e-Fatura mükellefi mi?	Alıcının VKN/TCKN'si e-Fatura gelen kutusunda varsa e-Fatura (alıcı etiketiyle), yoksa e-Arşiv.
Resmileştir	e-Fatura / e-Arşiv isteği. Yanıt belge değil, bir iş (trackable job) id'sidir.
İşi takip et	3 saniyede bir sorgulanır: running → done. error ise sebebi konsoldadır.
Resmileşen belgeyi al	Faturanın active_e_document ilişkisinden e-belge id'si.
PDF	Hazır değilse 204 döner ve tekrar denenir; hazır olunca 1 saat geçerli PDF bağlantısı gelir.

• e-Fatura denemek için VKN/TCKN alanına e-Fatura mükellefi bir alıcının numarasını yazın; senaryo Temel ya da Ticari seçilir.
• Düzenleme tarihi şirketinizin e-belge aktivasyon tarihinden ve alıcının e-Fatura etiketi tarihinden önce olamaz. Şirket e-belge kullanıcısı değilse resmileştirme hata döner.
• Akış durumu alanları düzenlenebilir: mevcut bir faturanın id'sini girip resmileştirme adımlarından devam edebilirsiniz. Akışı Sıfırla hepsini temizler.

7 · Hata senaryoları, rate limit, serbest istek

• Hata Senaryoları: her satır bilerek hatalı bir istek gönderir (token yok, geçersiz token, eksik alan, bozuk JSON, yanlış secret…) ve beklenen/gelen durum kodunu karşılaştırır. Rate limit aşımı satırı 15 eşzamanlı istekle 429 üretir. Olağandışı sayıda 401/403 alan istemciler engellenebilir; senaryoları art arda tekrarlamayın.
• Rate Limit: limit 10 saniyede 10 istektir. Aynı anda 15 istek → 429 görürsünüz; Sırayla ve 1100 ms aralıkla → 429 olmaz. Normal adımlar 429 alınca Retry-After kadar bekleyip tekrar dener.
• Serbest İstek: API base'e göre herhangi bir yol, ör. /{company_id}/sales_invoices?page[size]=5.
• Konsoldaki her satıra tıklayınca başlıklar ve gövdeler açılır; İstek/yanıt gövdelerini açık göster hepsini açık getirir.

8 · Prod'da test

Prod'da her işlem gerçek şirketinizde gerçek kayıt oluşturur. Resmileştirilen fatura GİB'e gider ve silinemez, yalnızca iptal edilebilir.

1. Ortam olarak Prod'u seçin. 1 · Bağlantı › İstemci bilgileri'ne API Bilgilerim › Production sekmesindeki Client ID / Secret'ı, Redirect URI'ye de başvuruda verdiğiniz production redirect URL'lerinden birini birebir girip Kaydet'e basın (ya da .env'de PROD_CLIENT_ID / PROD_CLIENT_SECRET / PROD_REDIRECT_URI, ardından yeniden başlatın).
2. Onay kutusunu işaretleyin ve Paraşüt Hesabını Bağla'ya basın; gerçek Paraşüt hesabınızla girin.
3. Giriş sonrası tarayıcı alan adınızdaki adrese gider (sayfa açılmayabilir; sorun değil). Adres çubuğundaki tam adresi (...?code=...&state=...) kopyalayın, Tarayıcı callback adresinde hata verdi mi? kutusuna yapıştırıp Token Al'a basın. Kod tek kullanımlıktır ve kısa sürede geçersizleşir; hemen yapıştırın.

O adreste çalışan kendi uygulamanız kodu önce kullanırsa (token'a çevirmeye çalışırsa) kod geçersiz olur; bu yüzden uygulamanızın işlemediği bir yol kullanın.

9 · Sık karşılaşılan sorunlar

Belirti	Sebep / çözüm
Giriş ekranında Invalid parameter: redirect_uri	Redirect URI (arayüzde ya da .env'de *_REDIRECT_URI), DevHub'da kayıtlı URL ile birebir aynı değil (port ve sondaki / dahil).
invalid_client (401)	Client ID/Secret yanlış ya da secret yenilenmiş. Doğru bilgileri 1 · Bağlantı'da girin (ya da .env'i güncelleyip yeniden başlatın).
state eşleşmedi ya da süresi doldu	Giriş başka bir oturumda başlatıldı, istemci bilgileri değiştirildi ya da uygulama yeniden başlatıldı. Paraşüt Hesabını Bağla ile yeniden başlatın.
Ortam yeniden (yapılandırılmamış) görünüyor	Arayüzden girilen bilgiler 30 dakika kullanılmayınca ya da uygulama kapanınca silinir. Yeniden girin ya da .env'e yazın.
invalid_grant (400) token isteğinde	Kod kullanılmış/süresi dolmuş ya da refresh token geçersiz. Yeniden bağlanın.
API'den 401	Token geçersiz; Token Yenile ya da yeniden bağlanın.
API'den 403	Kullanıcının o şirkette yetkisi yok ya da staging istemcisi başka bir şirkete bağlı. Doğru Şirket No'yu seçin.
422	Eksik ya da geçersiz alan; ayrıntı yanıttaki errors dizisindedir.
429	Rate limit (10 istek / 10 sn). Biraz bekleyin.

Ayrıntılar: DevHub OAuth Rehberi, Satış Faturası ve İrsaliye Rehberi, API Dokümantasyonu.