Nordlet

← Documentation / Guides

Prise en main

Clés API, premiers appels, cycle de facturation complet, SDK et webhooks.

Nordlet est une plateforme comptable axée sur l'API pour le marché de l'UE et de l'EEE, lancée avec une conformité totale pour la Lituanie. Toutes les fonctionnalités du produit (facturation, grand livre, lettrage bancaire, i.SAF) sont accessibles via une unique API JSON.

1. Obtenir une clé API

Chaque requête est authentifiée au moyen d'un jeton d'authentification Bearer associé à une seule entreprise :

Authorization: Bearer nl_...

Pour le développement local, initialisez une entreprise et une clé :

pnpm --filter @nordlet/db bootstrap:dev     # entreprise vide
pnpm --filter @nordlet/api seed:demo        # entreprise avec données de démonstration

Référence API interactive (spécification OpenAPI disponible sur /openapi.json; une instance locale héberge la même référence à l'adresse http://localhost:3001/docs).

Postman

Vous préférez utiliser Postman ? Importez la collection prête à l'emploi (tous les points de terminaison, regroupés par module, avec l'authentification Bearer préconfigurée) : Collection Postman de Nordlet. Après l'importation, attribuez votre clé API à la variable bearerToken de la collection pour authentifier chaque requête.

Entreprises bac à sable (sandbox)

Pour les tests d'intégration, créez une entreprise avec le paramètre isSandbox: true (POST /v1/account/companies/create, ou cochez la case bac à sable lors de l'intégration dans l'application). Une entreprise bac à sable fonctionne exactement comme une vraie (mêmes modules, même API, ce qui vous permet d'y injecter un volume de transactions réaliste), mais elle est clairement signalée comme étant des données de test et sa suppression efface tout immédiatement au lieu de respecter le délai de rétention de 10 jours. Vous pouvez exécuter un nombre quelconque d'entreprises bac à sable en parallèle de votre entreprise réelle sous le même compte ; le paramètre est immatérable après la création, de sorte que de véritables livres comptables ne peuvent jamais être reclassés par inadvertance en données de test. L'utilisation d'une entreprise bac à sable est mesurée et facturée exactement comme celle d'une entreprise réelle : requêtes, pages de numérisation de documents, stockage et frais de réactivation. Les déclarations et factures électroniques d'une entreprise bac à sable sont systématiquement transmises aux points de terminaison de test des administrations.

2. Premiers appels

Chaque opération s'effectue via une requête POST /v1/{module}/{ressource}/{action} avec un corps JSON. Créer un client :

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

Émettre une facture (les montants sont des chaînes décimales, jamais des nombres à virgule flottante) :

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

L'émission attribue un numéro séquentiel sans rupture (SF-1), vérifie que la période comptable est ouverte et comptabilise l'écriture équilibrée (D 2410 créances / C 5001 chiffre d'affaires / C 4492 TVA) au cours de la même transaction.

3. Le cycle complet

Étape Appel
Importer les livres comptables d'un système précédent migration/books/validate → migration/books/import - voir la section Migration depuis un autre système
Enregistrer une facture fournisseur purchases/invoices/create → purchases/invoices/register
Importer un relevé bancaire bank/statements/import (XML camt.053) ou bank/transactions/import (JSON)
Obtenir des suggestions de correspondances bank/transactions/suggest-matches
Lettrer un paiement bank/transactions/match - comptabilise le règlement et met à jour le champ paymentStatus
Régler les fournisseurs bank/payments/export - fichier SEPA pain.001 pour votre banque
Registres de TVA mensuels declarations/lt/isaf/generate - XML i.SAF 1.2 pour le VMI
Chiffres de la déclaration de TVA declarations/lt/fr0600/compute - rubriques du formulaire FR0600 rapprochées avec les registres
Expédier des marchandises avec un bon de livraison transport/waybills/create → issue, puis declarations/lt/ivaz/generate - XML i.VAZ pour le VMI

4. SDK TypeScript

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}`),
})

Le SDK est généré à partir de la spécification OpenAPI en direct (pnpm --filter @nordlet/sdk generate), si bien que chaque requête et chaque réponse est entièrement typée.

5. Webhooks

Abonnez-vous aux événements au lieu d'interroger l'API en continu :

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

Les livraisons comportent une signature HMAC horodatée (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> calculée sur <timestamp>.<raw body> avec votre secret d'abonnement) en plus de l'en-tête original x-nordlet-signature: sha256=<hex> du corps brut, et font l'objet de nouvelles tentatives pendant environ 24 heures. Consultez la section Conventions de l'API pour connaître la période de retransmission.

Le corps de chaque livraison prend la forme { id, version, companyId, eventType, createdAt, data } : version correspond à la version de l'enveloppe (actuellement 1) et companyId désigne l'entreprise à laquelle l'événement est rattaché, ce qui permet à un même récepteur de desservir plusieurs entités. L'abonnement à un nom d'événement absent de la liste ci-dessous est rejeté avec le code 400 ; utilisez "*" pour tous les événements. Après 5 échecs de livraison consécutifs, l'abonnement est suspendu et les propriétaires de l'entreprise reçoivent un e-mail ; vous pouvez le réactiver dans Account → Webhooks ou au moyen de la requête webhooks/subscriptions/update avec le paramètre isActive: true.

Événements : 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. Le document OpenAPI répertorie chacun d'eux sous la clé x-webhooks.

Consultez les Conventions de l'API pour en savoir plus sur les requêtes de listes, les enveloppes d'erreur, la sémantique d'idempotence et les limites de débit.