किसी अन्य सिस्टम से माइग्रेट करना

जब कोई कंपनी किसी अन्य लेखा सॉफ्टवेयर (accounting program) से Nordlet पर आती है, तो उसके बही-खाते शून्य से शुरू नहीं होते हैं। ऐतिहासिक-पुस्तकों का आयातक (historical-books importer) पुराने सिस्टम द्वारा छोड़ी गई हर चीज़ को लेता है और उसे एक कॉल, एक डेटाबेस ट्रांजेक्शन में दर्ज करता है: यदि कोई एक पंक्ति भी जाँच (check) में विफल हो जाती है, तो कुछ भी संग्रहीत नहीं होता है। इसी पैकेज को पहले केवल-जाँच (check-only) एंडपॉइंट के माध्यम से चलाया जा सकता है, जो प्रत्येक सत्यापन करता है और विफल होने पर रोलबैक करता है।

POST /v1/migration/books/validate   # सब कुछ जाँचता है, कुछ नहीं लिखता
POST /v1/migration/books/import     # सब कुछ लिखता है या कुछ नहीं

वेब ऐप में Account → Migration के तहत यही दो बटन होते हैं (JSON पेस्ट करें या फ़ाइल अपलोड करें)। API कुंजी के पास ledger:write के साथ-साथ आपके द्वारा शामिल किए जाने वाले प्रत्येक अनुभाग का राइट स्कोप (partners:write, catalog:write, sales:write, purchases:write, assets:write, inventory:write) होना आवश्यक है। दोनों एंडपॉइंट 32 MB तक के बॉडी स्वीकार करते हैं।

कट-ओवर तिथि (The cut-over date)

कट-ओवर तिथि चुनें: वह पहला दिन जब कंपनी को Nordlet में चलाया जाता है। इससे पहले की हर चीज़ पुराने सिस्टम में रहती है (या इतिहास के रूप में लाई जाती है, नीचे देखें); उस दिन से आगे की हर चीज़ Nordlet में सामान्य एंडपॉइंट के माध्यम से दर्ज की जाती है। पैकेज की सभी राशियाँ "कट-ओवर से एक दिन पहले की स्थिति के अनुसार" होती हैं: अंतिम ट्रायल बैलेंस, अभी भी भुगतान न किए गए चालान, शेल्फ पर बचा स्टॉक, और रजिस्टर पर मौजूद संपत्तियां।

आयात करने से पहले, Nordlet में निम्नलिखित कार्य करें:

1. कंपनी बनाएं और खातों के चार्ट का टेम्पलेट लागू करें (ledger/accounts/apply-template) - या पैकेज के accounts अनुभाग में अपनी आवश्यक सूचियां दें।
2. यदि आप स्टॉक आयात करते हैं, तो कम से कम एक गोदाम बनाएं (inventory/warehouses/create)।
3. पैकेज को तब तक migration/books/validate के माध्यम से चलाएं जब तक कि वह कोई त्रुटि न बताए और आप उसकी चेतावनियों को स्वीकार न कर लें।

पैकेज

प्रत्येक अनुभाग वैकल्पिक है; केवल उन्हीं को शामिल करें जो आपके पास हैं। अनुभागों के बीच के सभी संदर्भ कोड द्वारा होते हैं (खाता कोड, पार्टनर कोड, आइटम कोड, संपत्ति समूह कोड, गोदाम कोड), और कोई कोड या तो उस रिकॉर्ड को संदर्भित कर सकता है जो Nordlet में पहले से मौजूद है या उसी पैकेज के किसी पिछले अनुभाग द्वारा बनाए गए रिकॉर्ड को।

{
  "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 में हर जगह की तरह राशियाँ दशमलव स्ट्रिंग (decimal strings) होती हैं। source एक स्वतंत्र लेबल है जो शुरुआती-शेष (opening-balance) ट्रांजेक्शन के विवरण में और माइग्रेट किए गए चालान के नोट्स में आ जाता है।

accounts

खातों के चार्ट की पंक्तियाँ: code, name, type (asset, liability, equity, income, expense), वैकल्पिक parentCode और isPostable। जो कोड पहले से मौजूद हैं उन्हें वैसे ही छोड़ दिया जाता है और उन्हें existing के रूप में गिना जाता है। इसका उपयोग तब करें जब पुराने सिस्टम का चार्ट टेम्पलेट से अलग हो, या इसे छोड़ दें और पहले टेम्पलेट लागू करें।

partners और items

ग्राहक, आपूर्तिकर्ता (suppliers) और कैटलॉग आइटम, जो code द्वारा पहचाने जाते हैं। लिथुआनिया में पार्टनर कोड सामान्यतः कंपनी रजिस्ट्री कोड होता है; निजी व्यक्तियों के लिए ऐसे किसी भी कोड का उपयोग करें जो कंपनी के भीतर अद्वितीय (unique) हो। मौजूदा कोड छोड़ दिए जाते हैं, अपडेट नहीं किए जाते। आइटम type (product या service), unit, barcode, vatRatePercent, salePriceExclVat, purchasePriceExclVat स्वीकार करते हैं।

openingBalances

पुराने सिस्टम का अंतिम ट्रायल बैलेंस, प्रति खाता एक पंक्ति: debit या credit के साथ accountCode। पंक्तियों को openingBalances.date (डिफ़ॉल्ट रूप से कट-ओवर तिथि) दिनांक वाले एक जर्नल ट्रांजेक्शन के रूप में migration_opening दस्तावेज़ प्रकार के साथ पोस्ट किया जाता है। पंक्तियों को पोस्ट करने योग्य खातों को संदर्भित करना चाहिए।

ट्रांजेक्शन संतुलित होना चाहिए। यदि पुराने सिस्टम का ट्रायल बैलेंस संतुलित नहीं है - राउंडिंग, इक्विटी में कभी बंद न किया गया लाभ, या कोई छूटा हुआ खाता - तो balancingAccountCode (आमतौर पर प्रतिधारित आय यानी retained earnings, लिथुआनियाई टेम्पलेट में 3410) दें और अंतर वहाँ पोस्ट कर दिया जाता है; प्रतिक्रिया राशि को balancingAmount के रूप में रिपोर्ट करती है।

प्रति कंपनी केवल एक शुरुआती-शेष ट्रांजेक्शन हो सकता है। openingBalances के साथ दूसरा आयात अस्वीकार कर दिया जाता है (409)। बाद में किए जाने वाले सुधार सामान्य मैनुअल जर्नल ट्रांजेक्शन होते हैं (ledger/journal/transactions/create); पोस्ट किए गए ट्रांजेक्शन अपरिवर्तनीय होते हैं, इसलिए मूल ट्रांजेक्शन आयात किए गए रूप में ही रहता है।

journal - शेष राशि के बजाय या उसके अतिरिक्त पूर्ण इतिहास

यदि आप पुराने सिस्टम के ट्रांजेक्शन को Nordlet में चाहते हैं (ताकि पिछली अवधि की रिपोर्ट काम कर सकें), तो उन्हें यहाँ भेजें: प्रति ट्रांजेक्शन एक ऑब्जेक्ट जिसमें date, वैकल्पिक description और reference, तथा accountCode + debit/credit की entries हों। प्रत्येक ट्रांजेक्शन को अपने आप में संतुलित होना चाहिए। उन्हें migration दस्तावेज़ प्रकार के साथ पोस्ट किया जाता है।

तिथियाँ कट-ओवर तिथि से पहले की होनी चाहिए। जब पैकेज में openingBalances भी शामिल हो, तो इतिहास की तिथि openingBalances.date को या उसके बाद की होनी चाहिए - सामान्य पैटर्न पिछले वित्तीय वर्ष की शुरुआत में शेष राशि और उस वर्ष के ट्रांजेक्शन हैं, जिसमें कट-ओवर वर्तमान वर्ष के पहले दिन होता है। एक ही अवधि के लिए शेष राशि और इतिहास दोनों न भेजें: शेष राशि की गिनती दो बार हो जाएगी।

शुरुआती शेष राशि या इतिहास से जुड़ी प्रत्येक माह एक खुली लेखा अवधि होनी चाहिए (अन्यथा 409 त्रुटि आएगी)।

openReceivables और openPayables

वे चालान जिनका भुगतान कट-ओवर के समय (पूरा या आंशिक रूप से) बाकी था। उन्हें जारी किए गए बिक्री चालान (sale invoices) और पंजीकृत खरीद चालान (purchase invoices) के रूप में paidAmount = grossTotal − outstanding के साथ बनाया जाता है, ताकि बैंक मिलान (bank/transactions/match, bank/transactions/suggest-matches), ऋण-आयु रिपोर्ट (debt-aging report) और भुगतान वेबहुक किसी अन्य चालान की तरह उन पर काम कर सकें।

• outstanding डिफ़ॉल्ट रूप से grossTotal होता है; vatTotal डिफ़ॉल्ट रूप से 0 होता है (नेट इससे प्राप्त होता है)।
• dueDate डिफ़ॉल्ट रूप से दस्तावेज़ की तिथि होती है।
• currency डिफ़ॉल्ट रूप से कंपनी की चालान मुद्रा होती है। कंपनी की मूल मुद्रा के अलावा किसी अन्य मुद्रा के लिए fxRate आवश्यक है - मूल मुद्रा की 1 इकाई प्रति उस मुद्रा की इकाइयाँ, बाकी API जैसी ही परंपरा - और इसे चालान पर संग्रहीत किया जाता है ताकि बाद के भुगतान वास्तविक विनिमय दर (FX) अंतर की सही गणना कर सकें।
• बिक्री चालान number पुराने सिस्टम की पूरी संख्या होती है और कंपनी में अद्वितीय होनी चाहिए। खरीद चालान प्रति पार्टनर और documentNumber अद्वितीय होते हैं।
• चालान फिर से पोस्ट नहीं किए जाते हैं: उनकी प्राप्य/देय (receivable/payable) शेष राशि पहले से ही शुरुआती शेष का हिस्सा है। वे शुरुआती-शेष ट्रांजेक्शन से जुड़े होते हैं, यही कारण है कि openPayables को उसी पैकेज में openingBalances की आवश्यकता होती है।
• चालान की पंक्तियाँ आयात नहीं की जाती हैं; चालान में केवल कुल राशि होती है। पंक्ति विवरण और कट-ओवर से पहले की अवधि के वैट रजिस्टरों के लिए पुराना सिस्टम ही स्रोत बना रहता है।

यदि पुराना सिस्टम खुले मदों के बिना ग्राहक शेष राशि को ट्रैक करता है, तो शेष राशि के लिए प्रति पार्टनर एक चालान बनाएं (उदाहरण के लिए संख्या OB-301111222) ताकि उसका निपटान किया जा सके।

संख्यांकन जारी रहता है। जब किसी आयातित बिक्री चालान संख्या का प्रारूप PREFIX-N हो और उसकी जारी होने की तिथि कट-ओवर वर्ष के अंतर्गत आती है, तो उस उपसर्ग और वर्ष के लिए संख्या श्रृंखला को N + 1 पर सेट कर दिया जाता है (कभी घटाया नहीं जाता)। प्रतिक्रिया परिणामी numberSeries को सूचीबद्ध करती है; अन्य मामलों के लिए श्रृंखला को स्वयं reference/series/create ({ documentType: "sale_invoice", prefix, year, startAt }) के साथ सेट करें।

assetGroups और fixedAssets

अचल संपत्तियां अब तक की मूल्यह्रास (depreciation) राशि के साथ आती हैं: acquisitionCost, salvageValue, accumulatedDepreciation, depreciatedMonths और usefulLifeMonths (या समूह का डिफ़ॉल्ट)। सीधी रेखा की प्रक्रिया (assets/depreciation/post) शेष महीनों में शेष मूल्य से जारी रहती है। वे संपत्तियां जिनकी संचित मूल्यह्रास राशि (accumulated depreciation) पहले से ही मूल्यह्रास योग्य मूल्य के बराबर है, उन्हें fully_depreciated के रूप में बनाया जाता है। कुछ भी पोस्ट नहीं किया जाता है - लागत और संचित मूल्यह्रास शुरुआती शेष का हिस्सा हैं।

समूहों की पहचान code से होती है और उन्हें assetAccountCode तथा depreciationAccountCode (डिफ़ॉल्ट व्यय खाता 6206) की आवश्यकता होती है।

stock

प्रति आइटम हाथ में स्टॉक: itemCode, quantity, unitCost (EUR में प्रति यूनिट लागत) और वैकल्पिक रूप से लॉट- या सीरियल-ट्रैक किए गए आइटम के लिए warehouseCode (डिफ़ॉल्ट: डिफ़ॉल्ट गोदाम), lotNumber और expiryDate। प्रत्येक पंक्ति कट-ओवर तिथि पर migration दस्तावेज़ प्रकार के साथ एक आने वाली स्टॉक गतिविधि (incoming stock movement) बन जाती है और उस लागत पर एक FIFO परत शुरू करती है। कुछ भी पोस्ट नहीं किया जाता है - स्टॉक का मूल्य शुरुआती शेष का हिस्सा है।

जाँच और चेतावनियाँ (Checks and warnings)

वैलिडेट एंडपॉइंट छूटे हुए खातों, गैर-पोस्ट करने योग्य खातों, असंतुलित ट्रांजेक्शन, अज्ञात पार्टनर/आइटम/समूह/गोदाम कोड, पैकेज के भीतर डुप्लीकेट कोड या नंबर, सकल राशि (gross) से अधिक बकाया राशि, मूल्यह्रास योग्य मूल्य से अधिक संचित मूल्यह्रास, और छूटी हुई FX दरों पर विफल (422) हो जाता है। जो नंबर या कोड Nordlet में पहले से मौजूद हैं, वे 409 त्रुटि देते हैं।

इसके शीर्ष पर, दोनों एंडपॉइंट सब-लेज़र (sub-ledgers) की तुलना उसी पैकेज में लेज़र प्रविष्टियों के साथ करते हैं और त्रुटियों के बजाय चेतावनियों के रूप में warnings अंतर वापस करते हैं:

• openReceivables की कुल बकाया राशि बनाम प्राप्य खाते पर शेष राशि (sales.receivable पोस्टिंग नियम, डिफ़ॉल्ट रूप से 2410);
• openPayables की कुल बकाया राशि बनाम देय खाता (purchases.payables, 4430);
• stock की कुल लागत बनाम स्टॉक खाता (inventory.stock, 2040);
• प्रति संपत्ति समूह, संपत्तियों की लागत बनाम समूह का संपत्ति खाता और उनका संचित मूल्यह्रास बनाम मूल्यह्रास खाता।

चेतावनी का अर्थ है कि पुराने सिस्टम का सब-लेज़र और जनरल लेज़र असहमत हैं। आयात करने से पहले पैकेज को ठीक करें (या अंतर को जानबूझकर स्वीकार करें)।

प्रतिक्रिया (The response)

{
  "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 एक वैलिडेट रन को चिह्नित करता है; वहाँ journalTransactionId का मान null होता है। एक आयात को ऑडिट लॉग में समान सारांश के साथ migration.imported के रूप में दर्ज किया जाता है।

आयात के बाद

• कट-ओवर से पहले की अवधि को लॉक करें (ledger/periods/lock) ताकि गलती से माइग्रेट किए गए इतिहास में कुछ भी पोस्ट न हो जाए।
• पुराने सिस्टम की अंतिम रिपोर्ट के मुकाबले कट-ओवर तिथि के अनुसार ट्रायल बैलेंस और बैलेंस शीट की जाँच करें।
• सामान्य प्रवाह के साथ जारी रखें: चालान जारी करें, बैंक स्टेटमेंट आयात करें, भुगतानों का मिलान करें - माइग्रेट किए गए खुले चालान किसी अन्य चालान की तरह ही निपट जाते हैं।

आयातक किस चीज़ को कवर नहीं करता है: पिछली अवधि की चालान पंक्तियाँ और वैट रजिस्टर (उन्हें पुराने सिस्टम या उसकेेड आर्काइव में रखें), पेरोल इतिहास, और चालान के अलावा अन्य दस्तावेज़ (ऑर्डर, वेबिल, अनुबंध)।