Başka bir sistemden geçiş

Hesap planı, iş ortakları, açılış bakiyeleri veya tam geçmiş, açık faturalar, duran varlıklar ve stokları tek bir istek ile bir şirketin defterlerine aktarın.

Bir şirket başka bir muhasebe programından Nordlet'a taşındığında, defterleri sıfırdan başlamaz. Tarihsel defter aktarıcısı (historical-books importer), eski sistemin size bıraktığı her şeyi alır ve bunu tek bir istekte, tek bir veritabanı işleminde (database transaction) kaydeder: tek bir satır bile bir kontrolden geçemezse hiçbir şey kaydedilmez. Aynı paket, önce tüm doğrulamaları gerçekleştiren ve geri alan (roll back) yalnızca kontrol amaçlı bir uç nokta (endpoint) üzerinden çalıştırılabilir.

POST /v1/migration/books/validate   # her şeyi kontrol eder, hiçbir şey yazmaz
POST /v1/migration/books/import     # her şeyi yazar veya hiçbir şey yazmaz

Web uygulamasında Hesap (Account) → Geçiş (Migration) altında aynı iki düğme bulunur (JSON'u yapıştırın veya bir dosya yükleyin). API anahtarının ledger:write iznine ve dahil ettiğiniz her bölümün yazma yetki kapsamına (partners:write, catalog:write, sales:write, purchases:write, assets:write, inventory:write) sahip olması gerekir. Her iki uç nokta da 32 MB'a kadar olan gövdeleri (body) kabul eder.

Geçiş tarihi (cut-over date)

Geçiş tarihini seçin: şirketin Nordlet'ta çalıştırılacağı ilk gün. Bu tarihten önceki her şey eski sistemde kalır (veya aşağıda açıklandığı gibi geçmiş olarak aktarılır); o günden itibaren her şey normal uç noktalar aracılığıyla Nordlet'a girilir. Paketteki tüm tutarlar "geçiş tarihinden bir gün önceki haliyle" ifade edilir: kapanış mizanı, henüz ödenmemiş faturalar, raftaki stok, defterdeki varlıklar.

İçe aktarmadan önce Nordlet'ta şunları yapın:

Şirketi oluşturun ve hesap planı şablonunu uygulayın (ledger/accounts/apply-template) veya paketin accounts bölümünde ihtiyacınız olan hesapları listeleyin.
Stok içe aktaracaksanız en az bir depo oluşturun (inventory/warehouses/create).
Paketi, herhangi bir hata bildirmeyene ve uyarılarını kabul edene kadar migration/books/validate üzerinden çalıştırın.

Paket

Her bölüm isteğe bağlıdır; elinizde olanları dahil edin. Bölümler arasındaki tüm referanslar kod (code - hesap kodu, iş ortağı kodu, kalem kodu, varlık grubu kodu, depo kodu) aracılığıyla yapılır ve bir kod, halihazırda Nordlet'ta var olan bir kayda ya da aynı paketin önceki bir bölümü tarafından oluşturulmuş bir kayda atıfta bulunabilir.

{
  "cutoverDate": "2026-01-01",
  "source": "Rivilė GAMA",
  "accounts": [
    { "code": "6210", "name": "Advertising expenses", "type": "expense", "parentCode": "6" }
  ],
  "partners": [
    { "code": "301111222", "name": "UAB Klientas", "vatCode": "LT100001112223", "isCustomer": true },
    { "code": "302222333", "name": "UAB Tiekėjas", "isCustomer": false, "isSupplier": true }
  ],
  "items": [
    { "code": "SKU-1", "name": "Widget", "type": "product", "unit": "vnt", "vatRatePercent": "21" }
  ],
  "assetGroups": [
    { "code": "TRANSP", "name": "Vehicles", "assetAccountCode": "1230", "depreciationAccountCode": "1239",
      "defaultUsefulLifeMonths": 60 }
  ],
  "openingBalances": {
    "balancingAccountCode": "3410",
    "entries": [
      { "accountCode": "2710", "debit": "5000.00" },
      { "accountCode": "2410", "debit": "1500.00" },
      { "accountCode": "2040", "debit": "300.00" },
      { "accountCode": "1230", "debit": "12000.00" },
      { "accountCode": "1239", `credit`: "2400.00" },
      { "accountCode": "4430", "credit": "700.00" },
      { "accountCode": "3010", "credit": "10000.00" }
    ]
  },
  "openReceivables": [
    { "partnerCode": "301111222", "number": "SF-1050", "issueDate": "2025-12-10", "dueDate": "2026-01-09",
      "grossTotal": "1210.00", "vatTotal": "210.00" },
    { "partnerCode": "301111222", "number": "SF-1049", "issueDate": "2025-11-20",
      "grossTotal": "500.00", "outstanding": "290.00" }
  ],
  "openPayables": [
    { "partnerCode": "302222333", "documentNumber": "T-77", "documentDate": "2025-12-15", "grossTotal": "700.00" }
  ],
  "fixedAssets": [
    { "groupCode": "TRANSP", "code": "CAR-1", "name": "Delivery van", "acquisitionDate": "2025-01-01",
      "acquisitionCost": "12000.00", "accumulatedDepreciation": "2400.00", "depreciatedMonths": 12 }
  ],
  "stock": [
    { "itemCode": "SKU-1", "quantity": "30", "unitCost": "10" }
  ]
}

API'nin her yerinde olduğu gibi tutarlar ondalık dizelerdir (decimal string). source, açılış bakiyesi işleminin açıklamasında ve aktarılan faturaların notlarında yer alan serbest bir etikettir.

`accounts`

Hesap planı satırları: code, name, type (asset, liability, equity, income, expense), isteğe bağlı parentCode ve isPostable. Halihazırda var olan kodlara dokunulmaz ve bunlar existing olarak sayılır. Eski sistemin hesap planı şablondan farklı olduğunda bunu kullanın veya şablonu atlayıp önce şablonu uygulayın.

`partners` ve `items`

Müşteriler, tedarikçiler ve katalog kalemleri, anahtarları code olacak şekilde belirtilir. Litvanya'da iş ortağı kodu normalde şirket sicil kodudur; tüzel kişiliği olmayan şahıslar için şirket içinde benzersiz olan herhangi bir kodu kullanın. Var olan kodlar güncellenmez, atlanır. Kalemler type (product veya service), unit, barcode, vatRatePercent, salePriceExclVat, purchasePriceExclVat alanlarını kabul eder.

`openingBalances`

Eski sistemin kapanış mizanı, hesap başına bir satır: debit veya credit içeren accountCode. Satırlar, belge türü migration_opening olan ve tarihi openingBalances.date (varsayılan olarak geçiş tarihidir) şeklinde tek bir yevmiye işlemi olarak kaydedilir. Satırlar, kayda uygun (postable) hesaplara başvurmalıdır.

İşlemin denk olması gerekir. Eski sistemin mizanı denk değilse - yuvarlama, özkaynağa hiç kapatılmamış bir kar, eksik bir hesap - balancingAccountCode (tipik olarak geçmiş yıllar karları, Litvanya şablonunda 3410) sağlayın; aradaki fark buraya kaydedilir ve yanıt, tutarı balancingAmount olarak bildirir.

Şirket başına yalnızca bir açılış bakiyesi işlemi bulunabilir. openingBalances içeren ikinci bir içe aktarım reddedilir (409). Sonradan yapılan düzeltmeler sıradan manuel yevmiye işlemleridir (ledger/journal/transactions/create); kaydedilen işlemler değiştirilemez (immutable), bu nedenle orijinal veri aktarıldığı haliyle kalır.

`journal` - bakiyeler yerine veya bunlara ek olarak tam geçmiş

Eski sistemin işlemlerini Nordlet'a aktarmak istiyorsanız (böylece önceki dönemlere ait raporlar çalışır), bunları buraya gönderin: işlem başına date, isteğe bağlı description ve reference ile accountCode + debit/credit içeren entries nesneleri. Her işlemin kendi içinde denk olması gerekir. Bunlar migration belge türüyle kaydedilir.

Tarihler geçiş tarihinden önce olmalıdır. Paket aynı zamanda openingBalances içeriyorsa, geçmişin tarihi openingBalances.date tarihinde veya sonrasında olmalıdır - olağan düzen, önceki mali yılın başlangıcındaki bakiyeler artı o yılın işlemleri olup, geçiş cari yılın ilk günündedir. Aynı dönem için hem bakiye hem de geçmiş göndermeyin: bakiyeler iki kez sayılır.

Açılış bakiyelerinin veya geçmişin dokunduğu her ay açık bir muhasebe dönemi olmalıdır (aksi takdirde 409 hatası alınır).

`openReceivables` ve `openPayables`

Geçiş sırasında (tamamen veya kısmen) ödenmemiş olan faturalar. Bunlar, banka eşleştirme (bank/transactions/match, bank/transactions/suggest-matches), borç yaşlandırma raporu ve ödeme webhook'larının diğer tüm faturalarda olduğu gibi çalışabilmesi için paidAmount = grossTotal − outstanding ile düzenlenmiş (issued) satış faturaları ve kaydedilmiş (registered) alış faturaları olarak oluşturulur.

outstanding alanı varsayılan olarak grossTotal değerini alır; vatTotal varsayılan olarak 0'dır (net tutar buradan türetilir).
dueDate varsayılan olarak belge tarihidir.
currency varsayılan olarak şirketin fatura para birimidir. Şirketin baz para birimi dışındaki herhangi bir para birimi için fxRate zorunludur (API'nin geri kalanıyla aynı kurala göre, baz para biriminin 1 birimi başına o para biriminin birimi) ve daha sonraki ödemelerin gerçekleşen kur farkını doğru şekilde hesaplayabilmesi için faturada saklanır.
Satış faturası number alanı, eski sistemin tam numarasıdır ve şirkette benzersiz olmalıdır. Alış faturaları, iş ortağı ve documentNumber bazında benzersizdir.
Faturalar yeniden kaydedilmez: alacak/borç bakiyeleri zaten açılış bakiyelerinin bir parçasıdır. Açılış bakiyesi işlemine bağlanırlar, bu nedenle openPayables, aynı pakette openingBalances bulunmasını gerektirir.
Fatura kalemleri içe aktarılmaz; faturada yalnızca toplamlar yer alır. Eski sistem, kalem detayları ve geçiş öncesi dönemlerin KDV defterleri için kaynak olmaya devam eder.

Eski sistem, müşteri bakiyelerini açık kalemler olmadan takip ediyorsa, kapatılabilmesi için bakiye başına her iş ortağı için bir fatura oluşturun (örneğin OB-301111222 numarasıyla).

Numaralandırma devam eder. Aktarılan bir satış faturası numarası PREFIX-N biçimindeyse ve düzenlenme tarihi geçiş yılına denk geliyorsa, o önek ve yıl için numara serisi N + 1 olarak ayarlanır (asla düşürülmez). Yanıt, ortaya çıkan numberSeries değerini listeler; diğer durumlar için seriyi kendiniz reference/series/create ({ documentType: "sale_invoice", prefix, year, startAt }) ile ayarlayın.

`assetGroups` ve `fixedAssets`

Duran varlıklar bugüne kadarki amortismanlarıyla birlikte aktarılır: acquisitionCost, salvageValue, accumulatedDepreciation, depreciatedMonths ve usefulLifeMonths (veya grubun varsayılan değeri). Doğrusal amortisman çalışması (assets/depreciation/post), kalan ay üzerinden kalan değerle devam eder. Birikmiş amortismanı halihazırda amortismana tabi değere eşit olan varlıklar fully_depreciated olarak oluşturulur. Hiçbir şey kaydedilmez - maliyet ve birikmiş amortisman açılış bakiyelerinin bir parçasıdır.

Grupların anahtarı code olup assetAccountCode ve depreciationAccountCode (varsayılan gider hesabı 6206) gereklidir.

`stock`

Kalem bazında eldeki stok: itemCode, quantity, unitCost (EUR cinsinden birim maliyet) ve isteğe bağlı olarak parti veya seri takipli kalemler için warehouseCode (varsayılan: varsayılan depo), lotNumber ve expiryDate. Her satır, belge türü migration olan ve geçiş tarihinde düzenlenen gelen bir stok hareketine dönüşür ve bu maliyetle bir FIFO katmanı başlatır. Hiçbir şey kaydedilmez - stok değeri açılış bakiyelerinin bir parçasıdır.

Kontroller ve uyarılar

Doğrulama (validate) uç noktası; eksik hesaplar, kayda uygun olmayan hesaplar, denk olmayan işlemler, bilinmeyen iş ortağı/kalem/grup/depo kodları, paket içinde yinelenen kodlar veya numaralar, brüt tutarı aşan açık tutarlar, amortismana tabi değeri aşan birikmiş amortisman ve eksik kur oranları (FX rates) durumunda 422 hatası verir. Nordlet'ta halihazırda var olan numaralar veya kodlar 409 hatasına neden olur.

Bunun da ötesinde, her iki uç nokta da muavin defterleri (sub-ledgers) aynı paketteki defter-i kebir (ledger) kayıtlarıyla karşılaştırır ve farkları hata olarak değil warnings (uyarılar) şeklinde döndürür:

openReceivables toplam açık tutarı ile alacaklar hesabı (sales.receivable muhasebeleştirme kuralı, varsayılan olarak 2410) üzerindeki bakiye;
openPayables toplam açık tutarı ile borçlar hesabı (purchases.payables, 4430);
stock toplam maliyeti ile stok hesabı (inventory.stock, 2040);
varlık grubu bazında, varlıkların maliyeti ile grubun varlık hesabı ve birikmiş amortismanları ile amortisman hesabı.

Bir uyarı, eski sistemin muavin defteri ile defter-i kebirinin uyuşmadığı anlamına gelir. İçeri aktarmadan önce paketi düzeltin (veya farkı bilerek kabul edin).

Yanıt

{
  "dryRun": false,
  "cutoverDate": "2026-01-01",
  "accounts": { "created": 1, "existing": 0 },
  "partners": { "created": 2, "existing": 0 },
  "items": { "created": 1, "existing": 0 },
  "assetGroups": { "created": 1, "existing": 0 },
  "openingBalances": { "journalTransactionId": "…", "date": "2026-01-01", "entries": 8,
                        "debitTotal": "18800.00", "creditTotal": "18800.00", "balancingAmount": "5700.00" },
  "journal": { "transactions": 0, "entries": 0 },
  "openReceivables": { "created": 2, "outstandingTotal": "1500.00" },
  "openPayables": { "created": 1, "outstandingTotal": "700.00" },
  "fixedAssets": { "created": 1, "costTotal": "12000.00", "accumulatedDepreciationTotal": "2400.00" },
  "stock": { "movements": 1, "costTotal": "300.00" },
  "numberSeries": [],
  "warnings": []
}

dryRun: true bir doğrulama çalışmasını işaret eder; bu durumda journalTransactionId değeri null olur. Bir içe aktarım, denetim günlüğünde (audit log) aynı özetle migration.imported olarak kaydedilir.

Aktarım sonrası

Geçişten önceki dönemleri kilitleyin (ledger/periods/lock), böylece yanlışlıkla aktarılan geçmişe hiçbir kayıt atılmaz.
Geçiş tarihi itibarıyla mizanı ve bilançoyu eski sistemin kapanış raporlarıyla karşılaştırarak kontrol edin.
Normal akışla devam edin: fatura düzenleyin, banka ekstrelerini içe aktarın, ödemeleri eşleştirin - aktarılan açık faturalar diğer tüm faturalar gibi kapanır.

Aktarıcının kapsamadığı alanlar: geçmiş dönemlere ait fatura kalemleri ve KDV defterleri (eski sistemde veya arşivinde saklayın), bordro geçmişi ve faturalar dışındaki belgeler (siparişler, irsaliyeler, sözleşmeler).

Başka bir sistemden geçiş

Geçiş tarihi (cut-over date)

Paket

accounts

partners ve items

openingBalances

journal - bakiyeler yerine veya bunlara ek olarak tam geçmiş

openReceivables ve openPayables

assetGroups ve fixedAssets

stock