API'ye sahip muhasebe yazılımı

Nordlet'in her özelliği; SDK'lar, webhook'lar, güvenli yeniden denemeler ve yapay zeka asistanları için bir MCP sunucusu içeren tek bir JSON API üzerinden sunulur.

API (uygulama programlama arayüzü), bir programın başka bir programla iletişim kurmasını sağlayan bir yöntemdir. Muhasebe API'si ise kendi yazılımınızın, bir kullanıcının arayüz ekranlarında tıklama yapmasına gerek kalmadan fatura oluşturmasına, tahsilat ve ödemeleri kaydetmesine ve raporları okumasına olanak tanır.

Nordlet, API'nin temel erişim yöntemi olduğu bir muhasebe yazılımıdır. Web uygulamasının yaptığı her şey, aynı JSON API üzerinden kullanılabilir. Bu sayfa, geliştiriciler ve ürünlerinin neye bağlanacağına karar veren profesyoneller için hazırlanmıştır.

Nordlet ne yapar?

Tek istek kalıbı. Her çağrı, sales/invoices/create veya bank/transactions/match gibi bir JSON gövdesiyle birlikte POST /v1/{module}/{resource}/{action} şeklindedir.
Yetki kapsamlı (scope) API anahtarları. Her anahtar tek bir şirkete aittir ve sales:read ya da bank:write gibi yetki kapsamları barındırır. Gerekli kapsamı içermeyen bir anahtarla yapılan istekler 403 yanıtı alır.
Metin olarak para birimi. Tutar alanları, yuvarlama hataları yüzünden kuruş kaybı yaşanmaması için asla kayan noktalı sayılar (floating-point) kullanılmadan, en fazla 4 ondalık basamağa sahip ondalık dizeler (decimal string) şeklinde tutulur.
Tek hata biçimi. Her hata; bir kod, bir mesaj ve bir istek kimliği içeren aynı zarf yapısını (envelope) kullanır.
Ortak liste sorguları. Her list çağrısı aynı sayfalama, sıralama ve filtreleme alanlarını kullanır ve toplamları döndürebilir.
Gerçek muhasebe kuralları. Yevmiye maddeleri denk olmak zorundadır, belge numaralarında atlama olamaz ve kilitli bir muhasebe dönemi 409 yanıtıyla yeni kayıtlara kapatılır. Her değişiklik bir denetim günlüğüne (audit log) yazılır.

İdempotensiyel (çift yönlü güvenli) yeniden denemeler

İstek işlendikten ancak size yanıt ulaşmadan önce ağ bağlantısı kopabilir. Bu durumda yeniden deneme yapmak aynı faturanın iki kez oluşturulmasına yol açabilir. İdempotensiyel (çift yönlü güvenlilik), tekrarlanan bir isteğin ilk istekle tamamen aynı etkiyi yaratması anlamına gelir.

Veri değiştiren tüm çağrılara bir Idempotency-Key başlığı (header) ekleyin.
Aynı anahtar ve aynı gövdeyle yapılan bir yeniden deneme, x-idempotent-replay: true başlığıyla birlikte önceden saklanan yanıtı geri döndürür.
Aynı anahtarın farklı bir gövdeyle kullanılması reddedilir.
Anahtarlar 24 saat boyunca saklanır.

Webhook'lar

Webhook, sale_invoice.paid gibi bir olay gerçekleştiğinde Nordlet'in sunucunuza gönderdiği bir bildirimidir.

Olaylar, değişiklikle aynı veritabanı işleminde (transaction) yazılır, bu nedenle geri alınan (rollback) bir değişiklik hiçbir olay tetiklemez.
Her gönderim, abonelik gizli anahtarınız (secret) kullanılarak HMAC-SHA256 ile imzalanır, böylece bildirimin gerçekten Nordlet'ten geldiğini doğrulayabilirsiniz.
Başarısız olan bir gönderim yaklaşık 24 saat boyunca yeniden denenir. İsterseniz bildirimi manuel olarak da yeniden gönderebilirsiniz.
Abonelikler Hesap -> Webhook'lar (Account -> Webhooks) menüsünden veya API aracılığıyla yönetilebilir.

Geliştirici araçları

API referansı. OpenAPI tanımından oluşturulmuş interaktif bir API referansı ve bir Postman koleksiyonu.
SDK'lar. Aynı tanımdan üretilmiş TypeScript, Python, Go, Java, C#, Ruby, PHP, Swift ve Rust için tür güvenli (typed) istemciler. SDK'lar kılavuzunu inceleyin.
MCP sunucusu. Claude gibi yapay zeka asistanları, API anahtarınızı kullanarak API'de arama yapabilir ve çağrı gerçekleştirebilir. MCP sunucusu kılavuzunu inceleyin.
Test şirketleri (Sandbox). Gerçek bir şirket gibi çalışan, test verisi olarak işaretlenen ve beyannameler ile e-faturaları yalnızca idarelerin test uç noktalarına (endpoint) gönderen bir test ortamı sunar.
İstek sınırı (Rate limit). Kalan hakları gösteren başlıklarla birlikte API anahtarı başına dakikada 300 istek.

Sık sorulan sorular

API aracılığıyla neler yapabilirim?

Üründeki her şeyi: faturalama, satın alma, defteri kebir (general ledger), banka mutabakatı, stok, duran varlıklar, bordro, raporlar ve ülkeye özel beyannameler. Başlangıç kılavuzu, faturadan KDV rakamlarına kadar tüm döngüyü adım adım gösterir.

Kendi ürünüme muhasebe altyapısı entegre edebilir miyim?

Evet. Nordlet'teki her şirketin kendine ait defterleri vardır ve yazılımınız bu defterler üzerinde kendi API anahtarı aracılığıyla işlem yapar. API içerisinde deftere işlenmiş bir yevmiye maddesini düzenleyen veya silen hiçbir çağrı bulunmaz. Bir düzeltme ancak yeni bir yevmiye maddesi ile yapılabilir; bu da değiştirilemez bir defter (immutable ledger) yapısının korunmasını sağlar.