API

Base path: /api/v1

Auth

• Admin routes require an Authorization: Bearer <token> header. Obtain the token by POSTing credentials to /auth/login.
• Public routes require only the share token in the URL.

Auth

• POST /auth/login — body { "username": "...", "password": "..." } → `{ token, expiresIn }
  • The token is a short-lived JWT signed with JWT_SECRET.
  • The frontend stores the token in a secure, HTTP-only cookie; API clients must send the token back using the Authorization: Bearer header.

Settings

• GET /settings → map of settings
• PUT /settings → replace/normalize settings
• PATCH /settings → partial update

Keys you'll commonly set: companyName, companyAddress, companyEmail, companyPhone, companyTaxId, companyCountryCode, currency, logo, templateId, highlight, locale, numberFormat, dateFormat, paymentMethods, bankAccount, paymentTerms, defaultNotes, defaultTaxRate, defaultPricesIncludeTax, defaultRoundingMode, invoiceNumberPattern, invoiceNumberingEnabled, xmlProfileId, embedXmlInPdf, embedXmlInHtml.

Invoices (admin)

• GET /invoices → list
• GET /invoices/:id → details
• POST /invoices → create
• PUT /invoices/:id → update
• DELETE /invoices/:id → delete
• GET /invoices/next-number → preview next number
• POST /invoices/:id/duplicate → clone as draft
• POST /invoices/:id/publish → assign share token and set status to sent; lock final number
• POST /invoices/:id/unpublish → rotate share token and set status back to draft
• GET /invoices/:id/html → render invoice HTML (uses saved Settings)
• GET /invoices/:id/pdf → download PDF (optionally embed XML based on Settings)
• GET /invoices/:id/ubl.xml → UBL XML
• GET /invoices/:id/xml?profile=ubl21|facturx22 → XML via profile registry

Create payload (trimmed):

{
  "customerId": "...",
  "issueDate": "2025-09-25",
  "dueDate": "2025-10-25",
  "currency": "USD",
  "items": [
    { "description": "Service", "quantity": 1, "unitPrice": 500 }
  ],
  "discountAmount": 0,
  "discountPercentage": 0,
  "taxRate": 0,
  "pricesIncludeTax": false,
  "roundingMode": "line",
  "notes": "Thanks!"
}

Totals are computed server‑side. Per‑line taxes are supported by providing items[].taxes = [{ percent, note? }, ...].

Customers (admin)

• GET /customers → list
• GET /customers/:id → details
• POST /customers → create
• PUT /customers/:id → update
• DELETE /customers/:id → delete

Templates (admin)

• GET /templates → list (with isDefault, updatable)
• GET /templates/:id → details
• POST /templates → create
• DELETE /templates/:id → delete (not built‑ins)
• POST /templates/install-from-manifest → install from manifest URL
• POST /templates/:id/update → update using stored manifest URL
• POST /templates/:id/preview → returns rendered HTML using sample data
• POST /templates/load-from-file → read an HTML file from disk and save as a template

Export (admin)

• GET /export/full?includeDb=true&includeJson=true&includeAssets=true → tar.gz including DB (if present), JSON dump, and template assets

Public

• GET /public/invoices/:share_token → JSON invoice
• GET /public/invoices/:share_token/html → HTML view
• GET /public/invoices/:share_token/pdf → PDF download
• GET /public/invoices/:share_token/ubl.xml → UBL XML (legacy)
• GET /public/invoices/:share_token/xml → Default XML export via profile registry
• GET /public/xml-profiles → list XML profiles
• GET /demo-mode → { demoMode: boolean }