Primeiros passos

Chaves de API, primeiras chamadas, o ciclo de faturação completo, SDKs e webhooks.

O Nordlet é uma plataforma de contabilidade centrada na API (API-first) para o mercado da UE/EEE, cujo lançamento integra a conformidade fiscal total com a Lituânia. Tudo o que o produto faz - faturação, contabilidade geral, reconciliação bancária, i.SAF - está disponível através de uma única API JSON.

1. Obter uma chave de API

Cada pedido (request) é autenticado com uma chave de API Bearer associada a uma única empresa:

Authorization: Bearer nl_...

Para desenvolvimento local, inicialize uma empresa e uma chave:

pnpm --filter @nordlet/db bootstrap:dev     # empresa vazia
pnpm --filter @nordlet/api seed:demo        # empresa com dados de demonstração

Referência da API interativa (especificação OpenAPI em /openapi.json; uma instância local disponibiliza a mesma referência em http://localhost:3001/docs).

Postman

Prefere o Postman? Importe a coleção pronta a usar - todos os endpoints, agrupados por módulo, com autenticação bearer pré-configurada: Coleção do Postman do Nordlet. Após a importação, defina a variável bearerToken da coleção com a sua chave de API e cada pedido será autenticado.

Empresas em sandbox

Para testes de integração, crie uma empresa com isSandbox: true (POST /v1/account/companies/create, ou selecione a caixa de verificação de sandbox durante a integração na aplicação). Uma empresa em sandbox comporta-se exatamente como uma empresa real - mesmos módulos, mesma API, para que possa testar com um volume de transações realista -, mas apresenta um distintivo visível de dados de teste e a respetiva eliminação purga tudo de imediato, em vez de aguardar o período de retenção de 10 dias. Pode executar qualquer número de empresas em sandbox juntamente com a sua empresa real sob a mesma conta; o parâmetro é imutável após a criação, pelo que a contabilidade real nunca pode ser reclassificada inadvertidamente como dados de teste. A utilização numa empresa em sandbox é contabilizada e faturada exatamente da mesma forma que numa empresa real: pedidos, páginas de digitalização de documentos, armazenamento e a taxa de reativação. As declarações e as faturas eletrónicas de uma empresa em sandbox são sempre enviadas para os endpoints de teste das administrações fiscais.

2. Primeiros passos

Cada operação consiste num POST /v1/{module}/{resource}/{action} com um corpo JSON. Criar um cliente:

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

Emitir uma fatura (osmontantes são strings decimais, nunca floats):

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

A emissão atribui um número sequencial sem falhas (SF-1), verifica se o período contabilístico está aberto e regista o lançamento contabilístico equilibrado (D 2410 clientes / C 5001 proveitos / C 4492 IVA) na mesma transação.

3. O ciclo completo

Passo	Chamada
Transferir a contabilidade de um sistema anterior	`migration/books/validate` → `migration/books/import` - ver Migrar de outro sistema
Registar uma fatura de fornecedor	`purchases/invoices/create` → `purchases/invoices/register`
Importar um extrato bancário	`bank/statements/import` (XML camt.053) ou `bank/transactions/import` (JSON)
Obter sugestões de correspondência	`bank/transactions/suggest-matches`
Reconciliar um pagamento	`bank/transactions/match` - regista o pagamento e atualiza o `paymentStatus`
Pagar a fornecedores	`bank/payments/export` - ficheiro SEPA pain.001 para o seu banco
Registos mensais de IVA	`declarations/lt/isaf/generate` - XML i.SAF 1.2 para a VMI
Valores da declaração de IVA	`declarations/lt/fr0600/compute` - campos do FR0600 reconciliados com os registos
Expedir mercadorias com uma guia de transporte	`transport/waybills/create` → `issue`, e depois `declarations/lt/ivaz/generate` - XML i.VAZ para a VMI

4. SDK para 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}`),
})

O SDK é gerado a partir da especificação OpenAPI em direto (pnpm --filter @nordlet/sdk generate), pelo que cada pedido e resposta está totalmente tipado.

5. Webhooks

Subscreva eventos em vez de efetuar consultas periódicas (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"]}'

As entregas incluem uma assinatura HMAC com carimbo de data/hora (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> sobre <timestamp>.<raw body> com o segredo da sua subscrição) a par da assinatura x-nordlet-signature: sha256=<hex> original do corpo bruto, sendo repetidas durante cerca de 24 horas. Consulte as Convenções da API relativamente à janela de retransmissão.

O corpo de cada entrega tem o formato { id, version, companyId, eventType, createdAt, data }: version é a versão do envelope (atualmente 1) e companyId é a empresa a que o evento pertence, permitindo que um único destinatário sirva várias empresas. A subscrição de um nome que não conste da lista abaixo é rejeitada com o código 400; utilize "*" para todos os eventos. Após 5 falhas consecutivas de entrega, a subscrição é suspensa e os proprietários da empresa recebem um e-mail; reative-a em Conta → Webhooks ou através de webhooks/subscriptions/update com isActive: true.

Eventos: 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. O documento OpenAPI lista cada um deles em x-webhooks.

Consulte as Convenções da API para obter informações sobre consultas de listagem, envelopes de erro, semântica de idempotência e limites de cadência (rate limits).