Primeros pasos

Claves de API, primeras llamadas, el ciclo completo de facturación, SDK y webhooks.

Nordlet es una plataforma contable orientada a la API (API-first) para el mercado de la UE y el EEE, cuyo lanzamiento incluye cumplimiento normativo total en Lituania. Todas las funciones del producto (facturación, libro mayor, conciliación bancaria y i.SAF) están disponibles a través de una única API JSON.

1. Obtener una clave de API

Cada solicitud se autentica mediante una clave de API de tipo Portador (Bearer) vinculada a una empresa concreta:

Authorization: Bearer nl_...

Para el desarrollo local, inicialice una empresa y una clave:

pnpm --filter @nordlet/db bootstrap:dev     # empresa vacía
pnpm --filter @nordlet/api seed:demo        # empresa con datos de demostración

Referencia de API interactiva (especificación OpenAPI en /openapi.json; una instancia local ofrece la misma referencia en http://localhost:3001/docs).

Postman

¿Prefiere Postman? Importe la colección ya preparada (todos los módulos agrupados con la autenticación de tipo portador preconfigurada): colección de Postman de Nordlet. Tras importarla, asigne su clave de API a la variable bearerToken de la colección y cada solicitud quedará autenticada.

Empresas de prueba (sandbox)

Para realizar pruebas de integración, cree una empresa con isSandbox: true (POST /v1/account/companies/create, o bien marque la casilla de entorno de pruebas durante el proceso de incorporación en la aplicación). Una empresa de prueba se comporta exactamente igual que una real (mismos módulos y misma API, lo que permite procesar un volumen realista de transacciones), pero muestra claramente un indicador de datos de prueba. Además, al eliminarla, se borra todo de forma inmediata en lugar de esperar el periodo de retención de 10 días. Puede ejecutar tantas empresas de prueba como desee junto a su empresa real bajo la misma cuenta; este indicador no se puede modificar tras la creación, por lo que los libros contables reales nunca pueden reclasificarse por error como datos de prueba. El uso en una empresa de prueba se mide y se factura exactamente igual que en una empresa real: solicitudes, páginas de digitalización de documentos, almacenamiento y la tarifa de reactivación. Las declaraciones y facturas electrónicas de una empresa de prueba se dirigen siempre a los puntos de fin de prueba de las administraciones.

2. Primeras llamadas

Cada operación se realiza mediante POST /v1/{module}/{resource}/{action} con un cuerpo JSON. Cree un 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"}'

Emita una factura (los importes son cadenas decimales, nunca números de coma flotante):

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

La emisión asigna un número correlativo sin huecos (SF-1), comprueba que el periodo contable esté abierto y registra el asiento contable cuadrado (D 2410 deudores comerciales / C 5001 ingresos / C 4492 IVA soportado y repercutido) en la misma transacción.

3. El ciclo completo

Paso	Llamada
Traer la contabilidad de un sistema anterior	`migration/books/validate` → `migration/books/import` - consulte Migración desde otro sistema
Registrar una factura de proveedor	`purchases/invoices/create` → `purchases/invoices/register`
Importar un extracto bancario	`bank/statements/import` (XML camt.053) o `bank/transactions/import` (JSON)
Obtener sugerencias de coincidencia	`bank/transactions/suggest-matches`
Conciliar un pago	`bank/transactions/match` - registra el pago y actualiza `paymentStatus`
Pagar a proveedores	`bank/payments/export` - archivo SEPA pain.001 para su banco
Declaraciones de IVA mensuales	`declarations/lt/isaf/generate` - XML i.SAF 1.2 para la Inspección Tributaria (VMI)
Cifras de la autoliquidación de IVA	`declarations/lt/fr0600/compute` - casillas del formulario FR0600 conciliadas con los registros
Expedir mercancías con una guía de remisión	`transport/waybills/create` → `issue`, y después `declarations/lt/ivaz/generate` - XML i.VAZ para la VMI

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

El SDK se genera a partir de la especificación OpenAPI en directo (pnpm --filter @nordlet/sdk generate), por lo que todas las solicitudes y respuestas están completamente tipadas.

5. Webhooks

Suscríbase a eventos en lugar de realizar sondeos (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"]}'

Los envíos incluyen una firma HMAC con marca de tiempo (x-nordlet-signature-v2: t=<unix seconds>,v1=<hex> generada sobre <timestamp>.<raw body> con su secreto de suscripción) junto a la cabecera original x-nordlet-signature: sha256=<hex> del cuerpo bruto, y se reintentan durante aproximadamente 24 horas. Consulte las Convenciones de la API para conocer la ventana de reintento.

El cuerpo de cada entrega tiene la estructura { id, version, companyId, eventType, createdAt, data }: version es la versión del sobre (actualmente 1) y companyId es la empresa a la que pertenece el evento, lo que permite que un único receptor gestione varias empresas. Si se suscribe a un nombre que no figura en la lista inferior, la solicitud se rechazará con un error 400; utilice "*" para suscribirse a todos los eventos. Si un envío falla durante 5 eventos consecutivos, la suscripción se pausará temporalmente y los propietarios de la empresa recibirán un correo electrónico. Puede reactivarla desde Cuenta → Webhooks o mediante webhooks/subscriptions/update estableciendo 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. El documento OpenAPI enumera cada uno de ellos bajo x-webhooks.

Consulte las Convenciones de la API para informarse sobre consultas de listas, sobres de error, semántica de idempotencia y límites de tasa (rate limits).