Uygulama geliştiricileri için Nordlet

Tek bir JSON API, türü belirlenmiş (typed) SDK'lar, webhook'lar, bir MCP sunucusu ve test şirketleri (sandbox company) aracılığıyla yazılımınıza faturalama, defter tutma ve AB vergi beyannameleri ekleyin.

Pek çok uygulama mali işlemler üretir: bir sipariş ödenir, bir abonelik yenilenir, bir iade gerçekleştirilir. Bu olayların her birinin bir şirketin defterlerine işlenmesi gerekir.

Nordlet, temelinde API öncelikli (API-first) anlayışla geliştirilmiş bir muhasebe yazılımıdır. Web uygulamasının yaptığı her şey, tek bir JSON API üzerinden de kullanılabilir. Uygulamanız bu olayları gönderir; Nordlet ise defterleri tutar ve vergi beyannamelerini hazırlar.

Nordlet ne yapar?

Her eylemi POST /v1/{module}/{resource}/{action} formatında, örneğin /v1/sales/invoices/create şeklinde JSON gövdesiyle (body) sunar.
Her isteği, tek bir şirkete ait bir API anahtarıyla (API key) doğrular. Her anahtar, yapabileceklerini sınırlayan sales:read veya sales:write gibi yetki kapsamlarına (scope) sahiptir.
Tutarları kayan noktalı sayılar (floating-point) olarak değil, her zaman ondalık dizeler (decimal string) şeklinde alır, böylece yuvarlama nedeniyle hiçbir kuruş kaybolmaz.
Her değişiklikte Idempotency-Key üst bilgisini (header) kabul eder. Aynı anahtarla yapılan yeniden deneme, işlemi iki kez yapmak yerine ilk yanıtı döndürür. Tekrarlanabilirlik (idempotency), yinelenen bir isteğin tek bir istekle aynı etkiye sahip olması anlamına gelir.
Her hatayı ortak bir formatta döndürür.
API anahtarı başına dakikada 300 isteğe izin verir.
Her değişikliği bir denetim günlüğüne (audit log) kaydeder.

API kuralları kılavuzu bu kuralların her birini ayrıntılı olarak ele alır.

Doğruluğunu koruyan defterler

Fatura düzenlemek, boşluksuz bir numara atar, muhasebe döneminin açık olup olmadığını kontrol eder ve yevmiye kaydını aynı veritabanı işleminde (transaction) kayda geçirir.
Her yevmiye kaydı denk olmalıdır (balance). İşlem kaydedildiğinde veritabanı bunu bizzat kontrol eder.
Düzenlenmiş ve kaydedilmiş belgeler silinemez. Yanlış eşleşen bir banka hareketi, eskisi düzenlenerek değil, ters kayıt (reversing entry) oluşturularak düzeltilir. Değiştirilemez defter (immutable ledger) tam olarak bunu ifade eder.

SDK'lar, MCP ve webhook'lar

TypeScript, Python, Go, Java, C#, Ruby, PHP, Swift ve Rust için aynı OpenAPI tanımından türü belirlenmiş SDK'lar üretilir. Bir SDK yayınlanana kadar onu kaynak kod deposundan (repository) yükleyebilirsiniz. Bkz. SDK kılavuzu.
Her uç noktayı (endpoint) içeren bir Postman koleksiyonu mevcuttur.
MCP sunucusu, Claude Code gibi bir yapay zeka asistanının API'de arama yapmasını ve bunu sizin API anahtarınızla çağırmasını sağlar. Her çağrı, aynı kapsam ve sınırlamalara sahip olağan bir API isteğidir.
Webhook'lar, örneğin sale_invoice.issued veya sale_invoice.paid gibi bir olay gerçekleştiğinde uygulamanızı bilgilendirir. Her teslimat, Nordlet'ten geldiğini doğrulayabilmeniz için bir HMAC imzasıyla imzalanır. Başarısız teslimatlar yaklaşık 24 saat boyunca yeniden denenir.

Test şirketleriyle (sandbox company) test etme

isSandbox: true parametresiyle bir şirket oluşturun veya uygulamada bir şirket kurarken test kutucuğunu (sandbox box) işaretleyin.
Bir test şirketi gerçek bir şirket gibi çalışır: aynı modüller, aynı API.
Test verisi olduğu açıkça belirtilir ve gerçek bir şirketi test şirketine ya da tam tersine dönüştüremezsiniz.
Test şirketinin beyannameleri ve e-faturaları, idarelerin test servislerine gider.
Test şirketindeki kullanım, gerçek bir şirketteki kullanım gibi ölçülür ve faturalandırılır.

Başlarken kılavuzu, ilk API anahtarını, ilk faturayı ve tüm süreci adım adım açıklar.

Sıkça sorulan sorular

Tek bir uygulama birden fazla şirkete hizmet edebilir mi?

Evet. Her API anahtarı tek bir şirkete aittir, bu nedenle her şirket için ayrı bir anahtar oluşturursunuz. Her webhook teslimatı, ait olduğu şirketin companyId değerini taşır, böylece tek bir alıcı birden fazla şirkete hizmet edebilir.

Vergi beyannamelerini kendim oluşturmak zorunda mıyım?

Hayır. Nordlet beyannameleri defterlerden oluşturur. Her beyanname için ülkeye bağlı olarak ya gönderim yapar, ya yükleyeceğiniz bir dosya hazırlar ya da girmeniz gereken rakamları gösterir. Beyanname destek tablosu her durumu listeler.