Bir SaaS Platformuna Bulut Muhasebe API'si Nasıl Entegre Edilir?

Defteri bozmadan OAuth, webhook'lar, vergi kuralları ve mutabakat süreçlerinin üstesinden gelen çok kiracılı (multi-tenant) bir muhasebe entegrasyonu oluşturmak için uygulayıcı kılavuzu.

SaaS ürününe "muhasebe ekleme" işine girişen ekiplerin çoğu, bir sağlayıcı uç noktasına HTTP istemcisi bağlayıp fatura göndermekle işe başlar. Bu yaklaşım bir demoda çalışır. Ancak bir müşteri iki muhasebe organizasyonunu ilk kez bağladığında, bir webhook ilk kez iki kez geldiğinde veya bir yenileme belirteci (refresh token) istek sırasında dönüp kaybolduğunda sistem çöker. Bu işin sürdürülebilir versiyonu sıradan bir istemci yazmak değildir; bir entegrasyon katmanı inşa etmektir.

Söz konusu katmanın kiracı bağlantılarını, belirteç (token) depolama ve yenileme süreçlerini, sağlayıcıya özgü muhasebe kurallarını, kayıt eşleştirmelerini, ilk ve artımlı senkronizasyonu, yeniden deneme ve tekilleştirme mekanizmalarıyla webhook alımını, oran sınırlarını (rate limits), sürüm yönetimini ve destek ekibinizin gece saat 2'de okuyabileceği bir denetim izini (audit trail) yönetmesi gerekir. Bu makale, söz konusu mimariyi ve en önemli kararları ele almaktadır.

Faydalı bir zihni model:

SaaS ürünü → muhasebe entegrasyon servisi → sağlayıcı adaptörü (veya birleştirilmiş API) → asenkron senkronizasyon ve mutabakat

Muhasebe sistemi; hesaplar, vergi kodları, deftere işlenmiş işlemler ve yevmiye maddeleri (journal entries) gibi defter nesneleri için hakikat kaynağı (system of record) olmaya devam eder. SaaS platformunuz ise sistemler arası kararlı tanımlayıcıları, senkronizasyon durumunu, eşleştirme meta verilerini ve operasyonel denetim günlüğünü tutar.

"Bulut muhasebe API'si" terimi aslında neleri kapsar?

Bu ifade genellikle QuickBooks Online, Xero, Sage, Zoho Books gibi barındırılan bir ön muhasebe platformunun API'sini veya bölgesel bir sistemi ifade eder. Aynı zamanda, birkaç sağlayıcıyı tek bir arayüz arkasında normalleştiren birleştirilmiş bir muhasebe API'si (unified accounting API) anlamına da gelebilir.

Bu konuda kesin olmakta fayda var, çünkü uygulama amacı farklılık gösterir. Raporlama için faturaları okumak; SaaS faaliyetlerinden faturalar oluşturmak, gider fişleri (bills) kaydetmek, müşterileri ve ürünleri senkronize etmek, yevmiye maddeleri yazmak veya gerçek çift yönlü senkronizasyon (two-way sync) çalıştırmakla aynı iş değildir. Bir uç noktaya dokunmadan önce bunlardan hangisini inşa ettiğinize karar verin.

Bu yazı için önemli olan bir diğer ayrım da şudur: Bir ödeme API'si para hareketini yönetir. Bir bankacılık API'si hesap verilerini çeker. Bir faturalandırma API'si, defteri kebir verilerini açıkta bırakmadan belgeler oluşturabilir. Gömülü bir muhasebe defteri ise bambaşka bir konudur: SaaS şirketi muhasebe motorunun kendisine sahiptir. İşte Nordlet tam olarak bu son yaklaşımda konumlanır. Ürününüzü bir müşterinin harici defterlerine bağlamak yerine Nordlet; platformlara ve pazar yerlerine kendi ürünleri içinde, tiplendirilmiş SDK'lar ve webhook'lar içeren API öncelikli bir tasarım (API-first design with typed SDKs and webhooks) aracılığıyla gerçek çift taraflı kayıt defterleri, denetime hazır değiştirilemez bir defter (immutable ledger), AB KDV yönetimi ve ödemeler (payouts) sunar. Bir müşterinin muhasebe sistemini entegre edip etmeme veya defterleri kendi bünyenizde yürütme arasında karar vermesi gereken bir pazar yeriyseniz, bu gerçek bir yol ayrımıdır ve buna tekrar döneceğiz.

Çok kiracılı yapı (Multi-tenancy): Her bağlantının kapsamını iki kez belirleyin

Bir SaaS ürününde tek bir uygulama, birçok müşteri organizasyonuna bağlanır. Her bağlantının kapsamı hem SaaS kiracısı (tenant) hem de Xero kiracı kimliği veya QuickBooks realm kimliği gibi sağlayıcının organizasyon tanımlayıcısı ile sınırlandırılmalıdır.

Bağlantıların anahtarını yalnızca OAuth kullanıcı kimliğine dayanarak oluşturmayın. Tek bir kullanıcı birkaç muhasebe organizasyonunu yetkilendirebilir ve bir organizasyon zaman içinde farklı kullanıcılar tarafından yeniden bağlanabilir. Bu konuda hata yaparsanız, bir gün bir müşterinin faturasını yanlışlıkla başka bir müşterinin defterine kaydedersiniz; bu da sessizce üstesinden gelebileceğiniz bir hata değildir.

İlk mimari karar: Doğrudan bağlayıcı, birleştirilmiş API veya gömülü defter

Doğrudan sağlayıcı entegrasyonları

Doğrudan entegrasyon size en yüksek kontrolü sağlar: sağlayıcıya özgü özellikler, özel alanlar, hata yönetimi, senkronizasyon sıklığı, veri saklama politikaları ve maliyet yapısı. Bunun bir bedeli vardır. Her sağlayıcı kendi OAuth akışını, şemasını, kendine has özelliklerini, oran sınırlarını, webhook davranışını, sertifikasyon sürecini ve sürekli bakım yükünü beraberinde getirir.

Birleştirilmiş muhasebe API'leri (Unified accounting APIs)

Birleştirilmiş bir API; müşteriler, faturalar, tedarikçiler, hesaplar, ödemeler ve ürünler gibi varlıkları normalleştirerek birkaç muhasebe sistemi genelinde tek bir arayüz sunar. İlk geliştirme süresini kısaltabilir. Ancak entegrasyon karmaşıklığını ortadan kaldırmaz ve sorunu çözdüğünü varsaymak yaygın bir hatadır.

Karar vermeden önce şu soruları sorun: Hangi sağlayıcılar ve işlemler destekleniyor? Yazma işlemleri çalışıyor mu, yoksa sadece okuma mı var? Yazma işlemleri senkron mu yoksa kuyruğa mı alınıyor? Sağlayıcıya özgü alanlar geçiş (passthrough) yoluyla kullanılabilir mi? Veriler önbelleğe (cache) alınıyor mu ve ne kadar güncel? Sağlayıcı kesintilerini ve API değişikliklerini kim yönetiyor? Fiyatlandırma çağrı başına, bağlanan hesap başına, kayıt başına mı yoksa bir platform ücreti mi? Eşlemelerinizi dışarı aktarıp (export) temiz bir şekilde bağlantıyı kesebilir misiniz? "Birleştirilmiş" kelimesi nadiren "sağlayıcılar arasında özellik eşdeğerliği" anlamına gelir.

Gömülü defter (Embedded ledger)

Platformunuzun temel sorunu, verileri kullanıcının mevcut defterlerine yansıtmak değil de onlar için muhasebe süreçlerini yürütmekse, gömülü bir defter bu denklemi değiştirir. Binlerce satıcısı olan bir pazar yeri veya denetime hazır AB KDV ve ülkeye özel uyumluluk gereksinimlerini doğrudan içinde barındırması gereken bir SaaS ürünü için N harici bağlayıcıyı kablolamak yerine muhasebe motoruna sahip olmak daha avantajlıdır. Nordlet'in konumu tam olarak budur: üçüncü taraf bir ödeme ekranı yerine ürününüzün içinde yer alan; API olarak gerçek defterler, değiştirilemez çift taraflı kayıt (immutable double-entry), VIES doğrulaması ve i.SAF beyannamesi oluşturma özellikli ülkeye özel KDV, SEPA dışa aktarımı ve XLSX, PDF veya JSON formatlarında raporlama çıktıları.

Kullandığım bir karar kuralı:

Durum	En uygun seçenek
Müşteri tabanınızda tek bir muhasebe sağlayıcısı baskınsa ve sağlayıcıya özgü davranışlar temel önem taşıyorsa	Doğrudan bağlayıcı (Direct connector)
Geniş sağlayıcı kapsamı ve pazara çıkış hızı, kontrolden daha önemliyse	Birleştirilmiş API (Unified API)
Kullanıcılarınız için AB KDV ve denetim izleriyle birlikte muhasebeyi yürütmeniz ve sahiplenmeniz gereken bir platform veya pazar yeriyseniz	Gömülü defter (Nordlet)
Karma bir yapı mevcutsa	Hibrit: yaygın akışlar için birleştirilmiş, stratejik sağlayıcılar için doğrudan bağlayıcılar

Önerilen entegrasyon mimarisi

Entegrasyonu çekirdek iş mantığından izole edin

Sağlayıcı çağrılarını faturalandırma, siparişler, abonelikler ve raporlama arasına dağıtmayın. Sağlayıcı adaptörlerini, OAuth bağlantı yönetimini, kanonik (canonical) modelleri, kimlik eşlemelerini, senkronizasyon işlerini ve kuyruklarını, webhook uç noktalarını, yeniden deneme ve ölü mektup kuyruğu (dead-letter) yönetimini, denetim günlüklerini ve mutabakat araçlarını barındıran özel bir entegrasyon servisi inşa edin. Bu sayede bir Xero veya QuickBooks alan adının kendi alan modelinize sızmasını engellersiniz.

Dar bir kanonik model tanımlayın

Yalnızca desteklediğiniz iş akışlarını modelleyin. Tipik nesneler şunlardır: müşteri, ürün veya hizmet kalemi, fatura, fatura kalemi, ödeme, alacak dekontu (credit note), tedarikçi, hesap, vergi oranı, para birimi ve yevmiye maddesi.

Muhasebeyi etkileyen ayrıntıları koruyun. Taslak ile onaylanmış ve deftere işlenmiş durumları, vergili ile vergisi hariç tutarları, alacak dekontları ile negatif faturaları, ödeme tahsisatı ile ödemenin varlığını veya müşteri odaklı bir fatura numarası ile sağlayıcı nesne kimliğini birbirine karıştırmayın. Her kayıt; SaaS kimliği, sağlayıcı kimliği, sağlayıcı adı ve API sürümü, hakikat kaynağı göstergesi, durum, zaman damgaları, son senkronizasyon zamanı, harici referans ve hata/mutabakat durumunu barındırmalıdır.

Açık eşleştirme tabloları (Mapping tables) tutun

SaaS kiracısını muhasebe organizasyonuyla, SaaS müşterisini sağlayıcı kontağıyla, SaaS ürününü sağlayıcı kalemi veya hesabı ile, SaaS faturasını sağlayıcı faturası ile, SaaS ödemesini sağlayıcı ödemesi ile, vergi kategorisini vergi koduyla ve gelir kategorisini defter hesabı ile eşleştirin.

Asla adları veya e-posta adreslerini kalıcı tanımlayıcı olarak kullanmayın. Adlar değişir, kopyalar bulunur ve iki müşteri aynı e-postayı paylaşabilir. Sağlayıcının değiştirilemez kimliğini (immutable ID) saklayın ve orijinal SaaS kimliğini koruyun.

Durum makineleri (State machines) ekleyin

Bir bağlantıya şu açık durumları atayın: bağlı değil, yetkilendirme beklemede, bağlı, ilk senkronizasyon beklemede, senkronize ediliyor, sağlıklı, oran sınırı aşıldı, yeniden yetkilendirme gerekiyor, sağlayıcı kullanılamıyor, bağlantı kesildi, kalıcı olarak başarısız oldu. Kayıtlara da kendi durumlarını verin: beklemede, gönderildi, onaylandı, yeniden denenebilir şekilde başarısız, kullanıcı müdahalesi gerekiyor şeklinde başarısız, mutabakat sağlandı, çakışma tespit edildi. İkili bir "bağlı/bağlı değil" bayrağı destek ekibinize hiçbir faydalı bilgi vermez.

OAuth ve bağlantı süreçleri

Yetkilendirme kodu akışını (authorization code flow) kullanın. Müşteri "Bağlan" düğmesine tıklar, sunucunuz kısa ömürlü bir yetkilendirme işlemi oluşturur, müşteri sağlayıcıda kimlik doğrulaması yapıp yetki kapsamlarını (scopes) onaylar, siz kodu belirteçlerle takas edersiniz, yetkilendirilen organizasyonu keşfedersiniz, bağlantıyı doğru kiracıya kaydeder ve ilk senkronizasyonu kuyruğa alırsınız.

Geri arama (callback) verilerini dikkatlice doğrulayın: Sunucu tarafındaki bir işlemle eşleşen state parametresini, tam yönlendirme URI'sini (redirect URI), sağlayıcı yayıncısını (issuer) ve kiracı bağlamını kontrol edin. RFC 9700, OAuth 2.0 Güvenlik En İyi Uygulamaları (RFC 9700, OAuth 2.0 Security Best Current Practice) kılavuzu mevcut standartları resmileştirmiştir: Yetkilendirme kodu akışlarında PKCE kullanın, örtük (implicit) ve parola yetkilendirmelerinden kaçının ve tam yönlendirme URI'si eşleştirmesi kullanın.

En az yetki kapsamları (least-privilege scopes) talep edin. Yazma iznine ihtiyacınız olmayan durumlarda salt okunur (read-only) kapsamlar kullanın. Kapsam modelleri değişebilir, bu nedenle eski örnekleri kopyalamayın. Xero'nun OAuth dokümantasyonu (Xero's OAuth documentation), geniş muhasebe kapsamlarının ayrıntılı kapsamlarla değiştirildiğini, Mart 2026'dan beri yeni uygulamalara ayrıntılı kapsamlar atandığını ve geniş kapsamların Eylül 2027'ye kadar kullanılabilir kalmasının planlandığını belirtmektedir.

Belirteçleri yalnızca sunucu tarafında saklayın. Bunları hiçbir zaman tarayıcı JavaScript'ine, mobil istemcilere, ön uç günlüklerine (frontend logs), analitik araçlarına veya müşteri dönük hata mesajlarına açmayın. Verileri dururken şifreleyin (encrypt at rest), günlüklerden gizleyin ve her bağlantıya ait şu meta verileri tutun: şifrelenmiş erişim ve yenileme belirteçleri, son kullanma tarihi, sağlayıcı organizasyon kimliği, verilen kapsamlar, çıkış zamanı, son başarılı yenileme ve iptal durumu.

Yenileme belirteci döndürme (Refresh-token rotation) sistemlerin bozulduğu yerdir

Bir yenileme yanıtı yeni bir yenileme belirteci döndürebilir. En yeni değeri atomik olarak kalıcı hale getirmelisiniz, aksi takdirde müşterinin sisteme erişimi kilitlenir. Xero'nun geliştirici SSS sayfasına (Xero's developer FAQ) göre, her yenileme işlemi yeni bir yenileme belirteci üretir, bu belirteçler 60 güne kadar geçerlidir ve bir yanıtın kaybolması durumunda mevcut belirteçle yeniden deneme yapmak için 30 dakikalık bir yetkisiz kullanım süresi (grace period) bulunur. QuickBooks Online, geliştiricilere en son yanıttan gelen en güncel yenileme belirtecini saklamalarını söyler: yenileme belirteçleri 100 güne kadar geçerlidir ve değer her 24 saatte bir yenilenebilir.

Uygulamada yapılması gerekenler: Bağlantı başına bir yenileme kilidi kullanın, yenileme belirtecini atomik olarak değiştirin, geçici belirteç uç noktası hatalarını yeniden denemelerle yönetin, net bir yeniden yetkilendirme durumu sunun ve geçerli bir erişim belirteci dururken her API çağrısında belirteci yenilemeyin.

İlk senkronizasyon (Initial synchronization)

İlk senkronizasyonu bir arka plan işi olarak çalıştırın. OAuth geri aramasını veya kullanıcı arayüzünü bu süreçle bloke etmeyin.

Sağlam bir sıra şu adımlardan oluşur: Organizasyon meta verilerini getirmek, hesapları, vergi oranlarını, para birimlerini, kişileri ve kalemleri almak, sağlayıcı kimliklerini ve eşlemelerini saklamak, yalnızca ürünün ihtiyaç duyduğu geçmiş zaman penceresini içe aktarmak, bağımlı kayıtları bağımlılık sırasına göre kuyruğa almak, bir kontrol noktası (checkpoint) kaydetmek ve bağlantıyı yalnızca doğrulama sonrasında sağlıklı olarak işaretlemek.

Bağımlılık sırası önemlidir. Bir faturanın oluşturulabilmesi için önce bir kişinin, kalemin, gelir hesabının, vergi kodunun ve para biriminin mevcut olması gerekebilir. Körlemesine kopyalar oluşturmayın. Saklanan bir harici kimliğe, müşteri tarafından sağlanan bir referansa, tanımlanmış bir eşleştirme kuralına veya belirsiz durumlar için açık bir kullanıcı seçimi adımına göre eşleştirme yapın.

Artımlı senkronizasyon (Incremental synchronization)

Webhook'ları yetkili kayıtlar olarak değil, sinyaller olarak ele alın

Bir webhook genellikle bir şeyin değiştiğini söyler. İmzayı doğrulayın, ham olayı kaydedin, gerekli başarı yanıtını hızla döndürün, tekilleştirme yapın, takip eden bir veri çekme işlemi (fetch) kuyruğa alın, güncel nesneyi sağlayıcıdan alın, güncellemeyi işlemsel (transactional) olarak uygulayın, kontrol noktasını güncelleyin ve başarısızlıkları yeniden deneme ya da mutabakat mekanizmasına yönlendirin. Bu yaklaşım, eksik veri içeren yükleri (payloads) ve sırası bozulmuş olayları yönetmenizi sağlar.

Sağlayıcı kuralları farklılık gösterir, bu nedenle evrensel tek bir davranışı garanti etmeyin. Xero webhook'ları (Xero webhooks), x-xero-signature başlığında bir HMAC-SHA256 imzası taşır, HTTPS gerektirir, 24 saate kadar azalan sıklıkta yeniden deneme yapar, tekrarlanan başarısızlıklar sonrasında devre dışı bırakılabilir ve kurtarma sonrasında yeniden işleme (replay) için olayları 31 güne kadar saklayabilir. QuickBooks Online, HMAC-SHA256 ve doğrulayıcı belirteç ile doğrulama yapar, üç saniye içinde HTTP 200 yanıtı bekler ve Intuit'in asenkron işlemeyi önerdiği, zamanla altı saatlik aralıklara oturan sabit bir takvime göre yeniden denemeler gerçekleştirir.

Tekilleştirme ve talep tektaraflılığı (Idempotency)

En az bir kez teslimat (at-least-once delivery) standarttır. Yinelenen webhook'ları, yazma işleminin aslında başarılı olduğu ancak zaman aşımı nedeniyle yapılan yeniden denemeleri, sırası değişmiş olayları ve kullanıcıların çift tıklamalarını bekleyin. Mümkün olan yerlerde sağlayıcı olay kimliğini, kalıcı depolamada benzersiz bir olay anahtarını, her yazma işleminden önce oluşturulan bir işlem kimliğini, veritabanı benzersizlik kısıtlamalarını, upsert mantığını ve belirsiz zaman aşımı durumlarından sonra bir mutabakat sorgusunu kullanın.

Her muhasebe API'sinin yerel talep tektaraflılığı anahtarları (idempotency keys) sunduğunu varsaymayın. Sağlayıcı bunu desteklemiyorsa, dahili bir işlem anahtarı saklayın ve yeniden denemeden önce beklenen uzak nesnenin zaten var olup olmadığını kontrol edin. Stripe'ın tektaraflı istekler (Stripe'istempotent requests) belgesindeki kalıplar ve genel webhook tektaraflılık kılavuzu (webhook idempotency guidance) buraya doğrudan uyarlanabilir.

Yoklama (Polling) ve değişiklik tespiti

Webhook'ları periyodik yoklama ile eşleştirin. Webhook'lar devre dışı bırakılabilir, gecikebilir, yanlış yapılandırma nedeniyle kaybolabilir veya belirli nesnelerle sınırlı kalabilir. Xero, bir UTC zaman damgasından sonraki değişiklikler için If-Modified-Since başlığını destekler, ancak belgelendirmesinde her değişikliğin UpdatedDateUTC değerini güncellemediğini, bu nedenle kısmen ödenmiş bazı işlemlerin ve kişi alanlarının bu filtre aracılığıyla görünmeyeceğini uyarır. QuickBooks Online'ın Değişiklik Verisi Yakalama (Change Data Capture) özelliği son 30 güne ait değişiklikleri izler, yanıtları 1.000 nesne ile sınırlar, silinen varlıkları Deleted durumuyla döndürür ve en iyi sonucu daha kısa yoklama pencereleriyle verir.

Sağlayıcı ve kiracı bazında bir kontrol noktası saklayın ve örtüşen pencereler (overlap windows) kullanın. Değişiklikleri son kontrol noktasından biraz önceki bir andan itibaren isteyin, ardından sağlayıcı kimliğine ve değişiklik sürümüne göre tekilleştirme yapın. Bu yaklaşım, saat sapmasına (clock skew) ve kısmi başarısızlıklara karşı koruma sağlar.

Muhasebeye özgü veri bütünlüğü

Burası, çalışan bir entegrasyonu güvenilir bir entegrasyondan ayıran kısımdır.

Vergi davranışı değiştirilebilir değildir. Xero'nun belgeleri; LineAmountTypes ayarlanmadığında faturalar, alacak dekontları ve satın alma siparişlerinin varsayılan olarak vergisi hariç (tax-exclusive) olduğunu, makbuzlar ve banka işlemlerinin vergisi dahil (tax-inclusive) olduğunu, manuel yevmiye kayıtlarının ise vergisiz olduğunu belirtir. Vergi oranı adı yerine TaxType alanını kullanın. "Yüzde 20 KDV" ifadesinin benzersiz bir vergi kodunu temsil ettiğini asla varsaymayın; bu oran ülkeye, işlem türüne, yürürlük tarihine ve organizasyon yapılandırmasına göre değişebilir. AB'nin çok ülkeli KDV süreçlerini elle doğru yönetmek işte bu noktada maliyetli hale gelir ve ülkeye özel uyumluluğu yerleşik olarak sunan gömülü bir defter burada değer kazanır.

Para birimleri için ikili kayan nokta (binary floating point) aritmetiği asla kullanmayın; ondalık veya sabit duyarlıklı aritmetik kullanın. Para birimi kodunu ve duyarlılığını, birim tutarını, miktarı, indirimi, vergi tutarını, net tutarı, brüt tutarı ve döviz kurunu kalıcı olarak saklayın. Kalem düzeyinde tutarları gönderip toplamları sağlayıcının hesaplamasına izin mi vereceğinize yoksa önceden hesaplanmış bir toplam mı göndereceğinize net bir şekilde karar verin. Ikisini karıştırmak muhasebecinizin kesinlikle fark edeceği yuvarlama tutarsızlıkları yaratır.

Defter hesaplarına görünen adlarıyla değil, sağlayıcı kimliği veya koduyla başvurun. Yazma işleminden önce hesapların, vergi kodlarının, müşterilerin, kalemlerin ve para biriminin aktif ve destekleniyor olduğunu doğrulayın. Başarısız bir fatura yazma işlemi genellikle geçici bir API hatası değil, bir eşleştirme veya yapılandırma sorunudr; bu nedenle arayüz "senkronizasyon başarısız" demek yerine sorunun nasıl giderileceğini açıklamalıdır.

Nesne eşdeğerliğini varsaymayın. Bir "ödeme" bir tahsilat, bir dağıtım, bir mevduat, bir banka işlemi veya bir yevmiye maddesi anlamına gelebilir. Bir SaaS "aboneliği" bir muhasebe "faturasıyla" birebir örtüşmeyebilir. Bir API nesnesi seçmeden önce temsil etmek istediğiniz muhasebe olayını tanımlayın. Bir sağlayıcının bunu nasıl modellediğini görmek için Xero'nun ödeme belgelerine (Xero's payments documentation) göz atın.

Oran sınırları (Rate limits) ve sürüm yönetimi

Sınırlar genellikle kiracıya, organizasyona, uygulamaya veya bunların bir kombinasyonuna göre belirlenir. Xero'nun sınır SSS sayfasına (Xero's FAQ on limits) göre: kiracı başına eşzamanlı beş istek, kiracı başına dakikada 60 istek, kiracı başına günde 5.000 istek ve uygulama genelinde dakikada 10.000 istek uygulanır; ayrıca kalan limit başlıkları ve 429 yanıtlarında Retry-After başlığı döner. QuickBooks Online, realm kimliği başına dakikada 500 istek ve saniyede 10 istek sınırı belirlerken, istek başına 30'a kadar işlemi destekleyen bir toplu (batch) uç nokta sunar.

Kiracı bazlı oran sınırlaması, küresel akış kontrolü (throttling), jitters (rastgele gecikme) içeren üstel geri çekilme (exponential backoff) mantığı, Retry-After başlığına uyum, sınırlı eşzamanlılık, sayfalama (pagination) ve 429 hataları ile kalan kota metrikleri oluşturun. İçeri aktarma işlemleri için sınırsız paralellik kullanmayın; büyük bir müşteri o kiracıdaki diğer tüm işleri kısıtlayabilir.

API sürümlerini sabitleyin veya açıkça yönetin. QuickBooks Online, herhangi bir sürüm belirtilmediğinde varsayılan olarak 75 numaralı alt sürümü kullanır. Sürümleri yapılandırma dosyasında merkezileştirin, sandbox ortamlarında sözleşme testleri (contract tests) çalıştırın, sürüm notlarını izleyin ve bilinmeyen yanıt alanlarını gelecekle uyumlu (forward-compatible) olarak ele alın. Sandbox ortamları her üretim koşulunu yeniden üretmez; bu nedenle lansmandan önce bağlantıyı kesme, yeniden bağlanma, iptal edilen izinler, süresi dolmuş belirteçler, oran sınırları ve sağlayıcı tarafındaki düzenlemeleri test edin.

İlk olarak ne inşa etmeliyim?

Bunu yarın sabah yapıyor olsaydım sırasıyla şunları yapardım:

Kesin muhasebe iş akışını tanımlayın: hangi olayları ve nesneleri okuyup yazacağınızı belirleyin.
Sağlayıcı stratejisini seçin: doğrudan, birleştirilmiş, gömülü veya hibrit.
Sağlayıcı organizasyon kimlikleri, kapsamları, durumu ve belirteç meta verileri ile kiracı kapsamlı bir bağlantı modeli oluşturun.
OAuth akışını yetkilendirme kodu, PKCE, durum doğrulama, en az yetki kapsamları ve sunucu tarafı belirteç depolama ile uygulayın.
Kararlı bir dahili arayüzün arkasında tek bir sağlayıcı adaptörü inşa edin.
Değiştirilemez sağlayıcı kimlikleri üzerinde kimlik eşlemeleri oluşturun.
Önce okuma işlemlerini uygulayın; herhangi bir yazma işleminden önce referans verilerini içeri aktarın.
Sayfalama, oran sınırlaması, kontrol noktaları ve bağımlılık sıralaması içeren bir ilk senkronizasyon işi ekleyin.
Yalnızca müşteri, kalem, vergi ve hesap eşlemeleri doğrulandıktan sonra dar kapsamlı tek bir yazma işlemi (fatura oluşturma) uygulayın.
Dahili işlem kimlikleri, benzersizlik kısıtlamaları ve uzak durum kontrolleri ile yazma işlemlerini yeniden deneme açısından güvenli hale getirin.
Hızlı yanıt veren ve asenkron işlenen imzalı webhook'lar ekleyin.
Webhook'ların tek hakikat kaynağı değil, birer hızlandırıcı olması için yoklama ve mutabakat ekleyin.
Hata modlarını bilinçli olarak test edin.
Hataların açıklanabilir ve onarılabilir olmasını sağlayan destek ve denetim araçları ekleyin.
Nesne kapsamını kademeli olarak genişletin.

FAQ

Birleştirilmiş bir API mi kullanmalıyım yoksa doğrudan bağlayıcılar mı inşa etmeliyim?

Müşteri tabanınızda tek bir sağlayıcı baskınsa veya sağlayıcıya özgü davranışlar temel önem taşıyorsa doğrudan bağlayıcı kullanın. Geniş kapsam ve hız, kontrolden daha önemli olduğunda birleştirilmiş bir API'yi değerlendirin. Asıl ihtiyacınız müşterinin sistemine senkronize etmek değil de defterleri kendi bünyenizde yürütmekse, bunların ikisi de sorunuzun yanıtı değildir; bunun yerine Nordlet gibi gömülü bir defteri inceleyin.

Webhook'lar senkronizasyonda kalmak için yeterli midir?

Hayır. Webhook'lar devre dışı bırakılabilir, gecikebilir veya kaybolabilir; ayrıca veri yükleri eksik veya sırası bozulmuş olabilir. Bunları birer değişiklik sinyali olarak ele alın, sonrasında güncel nesneyi dışarıdan çekin ve bu süreci periyodik yoklama ile mutabakat mekanizmalarıyla destekleyin.

Yenileme belirteci (refresh token) hatalarının müşterilerin sistemde kilitli kalmasına nasıl engel olurum?

Her yenileme işleminde en yeni yenileme belirtecini atomik olarak kalıcı hale getirin, bağlantı başına bir kilit kullanın, geçici belirteç uç noktası hatalarını yeniden deneyin ve net bir yeniden yetkilendirme durumu sunun. Xero'nun 30 dakikalık yetkisiz kullanım süresi (grace period) yardımcı olur, ancak sizi kurtaran şey atomik kalıcılık adımıdır.

Kayıtları müşteri adına veya e-postasına göre eşleştirebilir miyim?

Kalıcı bir tanımlayıcı olarak hayır. Adlar değişir, kopyalar oluşur ve iki müşteri aynı e-postayı paylaşabilir. Sağlayıcının değiştirilemez kimliğini (immutable ID) saklayın ve kendi SaaS kimliğinizi bunun yanında tutun.