शुरुआत करना (Getting started)

API कुंजियाँ, पहली कॉल्स, संपूर्ण चालान चक्र (invoicing cycle), SDK और वेबहुक (webhooks)।

Nordlet यूरोपीय संघ (EU)/ईईए (EEA) बाज़ार के लिए एक API-प्रथम अकाउंटिंग प्लेटफ़ॉर्म है, जो पूर्ण लिथुआनियाई अनुपालन (compliance) के साथ लॉन्च किया गया है। उत्पाद जो कुछ भी करता है - चालान-प्रक्रिया, जनरल लेजर, बैंक मिलान (reconciliation), i.SAF - वह सब एक ही JSON API के माध्यम से उपलब्ध है।

1. API कुंजी प्राप्त करें

प्रत्येक अनुरोध (request) एक कंपनी के दायरे वाली Bearer API कुंजी के साथ प्रमाणित होता है:

Authorization: Bearer nl_...

स्थानीय डेवलपमेंट के लिए, एक कंपनी और कुंजी को बूटस्ट्रैप करें:

pnpm --filter @nordlet/db bootstrap:dev     # खाली कंपनी
pnpm --filter @nordlet/api seed:demo        # डेमो डेटा वाली कंपनी

इंटरएक्टिव API संदर्भ (OpenAPI स्पेक /openapi.json पर उपलब्ध है; एक स्थानीय इंस्टेंस http://localhost:3001/docs पर समान संदर्भ प्रदान करता है)।

Postman

Postman पसंद है? तैयार संग्रह (collection) आयात करें - प्रत्येक एंडपॉइंट, मॉड्यूल द्वारा समूहीकृत, बियरर प्रमाणीकरण (bearer auth) के साथ पहले से जुड़ा हुआ: Nordlet Postman collection। आयात करने के बाद, संग्रह के bearerToken चर (variable) को अपनी API कुंजी पर सेट करें और प्रत्येक अनुरोध प्रमाणित हो जाता है।

सैंडबॉक्स कंपनियाँ (Sandbox companies)

इंटीग्रेशन टेस्टिंग के लिए, isSandbox: true के साथ एक कंपनी बनाएँ (POST /v1/account/companies/create, या ऐप में ऑनबोर्डिंग के दौरान सैंडबॉक्स चेकबॉक्स पर टिक करें)। एक सैंडबॉक्स कंपनी बिल्कुल वास्तविक कंपनी की तरह काम करती है - वही मॉड्यूल, वही API, ताकि आप इसके माध्यम से वास्तविक लेनदेन वॉल्यूम भेज सकें - लेकिन इसे परीक्षण डेटा के रूप में स्पष्ट रूप से चिह्नित किया जाता है और इसे हटाने से 10 दिन की प्रतिधारण अवधि (retention window) के बाद के बजाय तुरंत सब कुछ मिट जाता है। एक ही खाते के तहत अपनी वास्तविक कंपनी के साथ किसी भी संख्या में सैंडबॉक्स कंपनियाँ चलाएँ; निर्माण के बाद फ़्लैग अपरिवर्तनीय होता है, इसलिए वास्तविक बहियों को कभी भी चुपचाप परीक्षण डेटा के रूप में पुनर्वर्गीकृत नहीं किया जा सकता है। सैंडबॉक्स कंपनी में उपयोग को बिल्कुल वास्तविक कंपनी की तरह मापा और बिल किया जाता है: अनुरोध, दस्तावेज़-स्कैनिंग पेज, संग्रहण और पुनर्सक्रियेशन शुल्क। सैंडबॉक्स कंपनी के फाइलिंग और ई-चालान हमेशा प्रशासकों के परीक्षण एंडपॉइंट पर जाते हैं।

2. पहली कॉल्स

प्रत्येक ऑपरेशन JSON बॉडी के साथ POST /v1/{module}/{resource}/{action} है। एक ग्राहक बनाएँ:

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"}'

एक चालान जारी करें (राशि दशमलव स्ट्रिंग हैं, फ़्लोट कभी नहीं):

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"}'

चालान जारी करने से एक अंतराल-मुक्त संख्या (SF-1) आवंटित होती है, यह जाँच होती है कि अकाउंटिंग अवधि खुली है, और एक ही लेनदेन में संतुलित जर्नल प्रविष्टि (D 2410 प्राप्त करने योग्य / C 5001 राजस्व / C 4492 वैट) पोस्ट हो जाती है।

3. संपूर्ण चक्र

चरण	कॉल
पिछले सिस्टम से बहियाँ लाएँ	`migration/books/validate` → `migration/books/import` - देखें किसी अन्य सिस्टम से माइग्रेट करना
एक आपूर्तिकर्ता बिल पंजीकृत करें	`purchases/invoices/create` → `purchases/invoices/register`
बैंक स्टेटमेंट आयात करें	`bank/statements/import` (camt.053 XML) या `bank/transactions/import` (JSON)
मिलान सुझाव प्राप्त करें	`bank/transactions/suggest-matches`
भुगतान का मिलान करें	`bank/transactions/match` - भुगतान पोस्ट करता है और `paymentStatus` अपडेट करता है
आपूर्तिकर्ताओं को भुगतान करें	`bank/payments/export` - आपके बैंक के लिए pain.001 SEPA फ़ाइल
मासिक वैट रजिस्टर	`declarations/lt/isaf/generate` - VMI के लिए i.SAF 1.2 XML
वैट रिटर्न आँकड़े	`declarations/lt/fr0600/compute` - रजिस्टरों के मुकाबले FR0600 फ़ील्ड का मिलान किया गया
माल चालान (waybill) के साथ भेजें	`transport/waybills/create` → `issue`, फिर `declarations/lt/ivaz/generate` - VMI के लिए 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 लाइव OpenAPI स्पेक से जेनरेट किया जाता है (pnpm --filter @nordlet/sdk generate), इसलिए प्रत्येक अनुरोध और प्रतिक्रिया पूरी तरह से टाइप की जाती है।

5. वेबहुक (Webhooks)

पोलिंग (polling) के बजाय इवेंट की सदस्यता लें:

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"]}'

डिलीवरी में मूल कच्चे बॉडी के मूल x-nordlet-signature: sha256=<hex> के बगल में एक टाइमस्टैम्प वाला HMAC हस्ताक्षर (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> आपके सब्सक्रिप्शन सीक्रेट के साथ <timestamp>.<raw body> पर) होता है, और लगभग 24 घंटे तक पुनः प्रयास किया जाता है। रीप्ले विंडो के लिए API सम्मेलन देखें।

प्रत्येक डिलीवरी बॉडी { id, version, companyId, eventType, createdAt, data } होती है: version लिफाफा संस्करण है (वर्तमान में 1) और companyId वह कंपनी है जिससे इवेंट संबंधित है, ताकि एक रिसीवर कई कंपनियों की सेवा कर सके। नीचे दी गई सूची में नहीं होने वाले नाम की सदस्यता लेने पर 400 के साथ अस्वीकार कर दिया जाता है; प्रत्येक इवेंट के लिए "*" का उपयोग करें। लगातार 5 इवेंट डिलीवर न हो पाने के बाद, सब्सक्रिप्शन को रोक (pause) दिया जाता है और कंपनी के मालिकों को एक ई-मेल मिलता है; खाता (Account) → वेबहुक में या webhooks/subscriptions/update और isActive: true के साथ इसे फिर से शुरू करें।

इवेंट्स: 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 दस्तावेज़ प्रत्येक को x-webhooks` के अंतर्गत सूचीबद्ध करता है।

सूची क्वेरी, त्रुटि लिफाफे, आइडपोटेंसी सिमेंटिक्स (idempotency semantics), और दर सीमाओं (rate limits) के लिए API सम्मेलन देखें।