Başlangıç Kılavuzu

API anahtarları, ilk çağrılar, eksiksiz faturalandırma döngüsü, SDK'lar ve webhook'lar.

Nordlet, AB/AEA (EEA) pazarına yönelik, tam Litvanya uyumluluğuyla kullanıma sunulan API odaklı bir muhasebe platformudur. Faturalandırma, defter-i kebir (general ledger), banka mutabakatı ve i.SAF dahil olmak üzere ürünün gerçekleştirdiği her işlem tek bir JSON API üzerinden sunulur.

1. API anahtarı edinme

Her istek, tek bir şirkete yetkilendirilmiş bir Bearer API anahtarı ile doğrulanır:

Authorization: Bearer nl_...

Yerel geliştirme (local development) için bir şirket ve anahtar oluşturun:

pnpm --filter @nordlet/db bootstrap:dev     # boş şirket
pnpm --filter @nordlet/api seed:demo        # demo verilerine sahip şirket

İnteraktif API referansı (OpenAPI özellikleri /openapi.json adresindedir; yerel bir örnek aynı referansı http://localhost:3001/docs adresinde sunar).

Postman

Postman tercih edersiniz? Hazır koleksiyonu içe aktarın; modüllere göre gruplandırılmış, bearer kimlik doğrulaması önceden yapılandırılmış tüm uç noktalar (endpoints) hazırdır: Nordlet Postman koleksiyonu. İçe aktardıktan sonra koleksiyonun bearerToken değişkenini API anahtarınızla ayarlayın; böylece her istek otomatik olarak doğrulanır.

Sandbox şirketleri

Entegrasyon testleri için isSandbox: true parametresiyle bir şirket oluşturun (POST /v1/account/companies/create veya uygulamadaki başlangıç kurulumu -onboarding- sırasında sandbox onay kutusunu işaretleyin). Sandbox şirketi gerçek bir şirketle tamamen aynı şekilde çalışır; aynı modüllere ve aynı API'ye sahiptir, böylece gerçekçi işlem hacimlerini bu şirket üzerinden test edebilirsiniz. Ancak bu şirketler test verisi olduğunu açıkça gösterecek şekilde etiketlenir ve silindiğinde 10 günlük saklama penceresi beklenmeden veriler derhal imha edilir. Aynı hesap altında, gerçek şirketinizin yanında dilediğiniz sayıda sandbox şirketi çalıştırabilirsiniz. Bu bayrak (flag) oluşturulduktan sonra değiştirilemez, bu nedenle gerçek defterlerin yanlışlıkla test verisi olarak yeniden sınıflandırılması önlenmiş olur. Sandbox şirketindeki kullanım, gerçek bir şirketteki kullanım gibi ölçülür ve faturalandırılır: istekler, belge tarama sayfaları, depolama ve yeniden etkinleştirme ücreti. Bir sandbox şirketinin beyannameleri ve e-faturaları her zaman ilgili kurumların test uç noktalarına gönderilir.

2. İlk çağrılar

Her işlem bir JSON gövdesi ile birlikte POST /v1/{module}/{resource}/{action şeklindedir. Bir müşteri oluşturun:

curl -X POST https://api.nordlet.com/v1/partners/create \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: partner-create-001" \
  -d '{"name": "UAB Klientas", "code": "301111222", "vatCode": "LT100001112223"}'

Bir fatura düzenleyin (tutarlar ondalık dizelerdir -decimal strings-, asla kayan noktalı sayı -float- değildir):

curl -X POST https://api.nordlet.com/v1/sales/invoices/create \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{
    "partnerId": "<partner id>",
    "lines": [{"description": "Konsultacijos", "quantity": 4, "unitPriceExclVat": "75.0000", "vatClassifierCode": "PVM1"}]
  }'

curl -X POST https://api.nordlet.com/v1/sales/invoices/issue \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"id": "<invoice id>", "issueDate": "2026-07-09"}'

Fatura düzenleme işlemi boşluksuz bir numara atar (SF-1), muhasebe döneminin açık olup olmadığını kontrol eder ve aynı işlem (transaction) içinde dengeli yevmiye kaydını (B 2410 alıcılar / A 5001 yurt içi satışlar / A 4492 hesaplanan KDV) kayda geçirir.

3. Tam döngü

Adım	Çağrı
Defterleri önceki bir sistemden aktarma	`migration/books/validate` → `migration/books/import` - bkz. Başka bir sistemden geçiş
Tedarikçi faturası kaydetme	`purchases/invoices/create` → `purchases/invoices/register`
Banka ekstresi içe aktarma	`bank/statements/import` (camt.053 XML) veya `bank/transactions/import` (JSON)
Eşleşme önerileri alma	`bank/transactions/suggest-matches`
Ödeme mutabakatı yapma	`bank/transactions/match` - ödemeyi kaydeder ve `paymentStatus` alanını günceller
Tedarikçilere ödeme yapma	`bank/payments/export` - bankanız için pain.001 SEPA dosyası
Aylık KDV defterleri	`declarations/lt/isaf/generate` - VMI için i.SAF 1.2 XML
KDV beyannamesi rakamları	`declarations/lt/fr0600/compute` - defterlerle mutabık kılınmış FR0600 alanları
Sevk irsaliyesi ile mal sevkiyatı	`transport/waybills/create` → `issue`, ardından `declarations/lt/ivaz/generate` - VMI için i.VAZ XML

4. TypeScript SDK

import { createNordletClient, idempotent } from '@nordlet/sdk'

const client = createNordletClient({
  baseUrl: 'https://api.nordlet.com',
  apiKey: process.env.NORDLET_API_KEY!,
})

const { data, error } = await client.POST('/v1/sales/invoices/create', {
  body: {
    partnerId,
    lines: [{ description: 'Konsultacijos', quantity: 4, unitPriceExclVat: '75.0000' }],
  },
  ...idempotent(`order-${orderId}`),
})

SDK, canlı OpenAPI spesifikasyonundan üretilir (pnpm --filter @nordlet/sdk generate), bu nedenle her istek ve yanıt tamamen tür güvenlidir (fully typed).

5. Webhook'lar

Sürekli sorgulama (polling) yapmak yerine olaylara abone olun:

curl -X POST https://api.nordlet.com/v1/webhooks/subscriptions/create \
  -H "Authorization: Bearer $API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/hyperion", "events": ["sale_invoice.issued", "sale_invoice.paid"]}'

Teslimatlar, ham gövdenin orijinal x-nordlet-signature: sha256=<hex> başlığının yanında, abonelik gizli anahtarınızla oluşturulan zaman damgalı bir HMAC imzası (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex>, <timestamp>.<raw body> üzerinden hesaplanır) taşır ve yaklaşık 24 saat boyunca yeniden denenir. Yeniden deneme penceresi için bkz. API kuralları.

Her teslimat gövdesi şu yapıdadır: { id, version, companyId, eventType, createdAt, data }. Burada version zarf sürümünü (şu anda 1) ve companyId olayın ait olduğu şirketi belirtir; böylece tek bir alıcı (receiver) birkaç্ণ şirkete hizmet edebilir. Aşağıdaki listede yer almayan bir olaya abone olunmak istenirse 400 hatasıyla reddedilir; tüm olaylar için "*" kullanın. Üst üste 5 olay teslim edilemezse abonelik duraklatılır ve şirket sahiplerine bir e-posta gönderilir; aboneliği Hesap → Webhook'lar bölümünden veya webhooks/subscriptions/update ile isActive: true kullanarak yeniden etkinleştirebilirsiniz.

Olaylar: agreement.invoice_generated, bank_feed.synced, document_capture.peppol_received, filing.failed, filing.rejected, goods_receipt.posted, intercompany.invoice_mirrored, item.created, item.deleted, item.updated, lead.converted, lead.created, partner_inquiry.created, payroll_run.approved, payroll_run.reversed, pos_report.created, price_list.updated, purchase_invoice.paid, purchase_invoice.registered, purchase_order.approved, purchase_order.received, refund_liability.actual, refund_liability.trued_up, report.completed, report.failed, revenue_recognition.modified, revenue_recognition.posted, sale_invoice.einvoice_sent, sale_invoice.issued, sale_invoice.paid, sale_invoice.peppol_delivered, sale_invoice.peppol_failed, sale_invoice.peppol_rejected, sale_invoice.peppol_sent, sale_invoice.quote_sent, sale_invoice.sent, sales_order.created, sales_order.fulfilled, settlement.imported, settlement.posted, settlement.updated, stock.changed, stock.reorder_needed, vat_review.opened, vat_review.resolved. OpenAPI belgesi bunların her birini x-webhooks altında listeler.

Liste sorguları, hata zarfları, işlem tektipliği (idempotency) semantiği ve oran sınırları (rate limits) için bkz. API kuralları.