cry-bizbox

TypeScript library for exchanging e-documents (e-računi, naročila, dobavnice) through the bizBox EDI network. Built for veterinary practices and other tenants in Slovenia/Croatia.

Installation

bun install cry-bizbox

Verify credentials

import { verifyBizBoxCredentials } from 'cry-bizbox';

const valid = await verifyBizBoxCredentials({
  baseUrl: 'https://demohr.zzi.si/BizBoxEdiRest/BizBoxEdi',
  username: 'SI60573350.HQ',
  password: 'your-api-password',
});

console.log('Credentials valid:', valid); // true | false

For browser environments, use the fetch-only variant:

import { testBizBoxCredentials } from 'cry-bizbox';

const valid = await testBizBoxCredentials(
  'https://demohr.zzi.si/BizBoxEdiRest/BizBoxEdi',
  'SI60573350.HQ',
  'your-api-password',
);

Quick start

import { BizBoxClient, DocumentType, DocumentFormat } from 'cry-bizbox';

const client = new BizBoxClient({
  baseUrl: 'https://demohr.zzi.si/BizBoxEdiRest/BizBoxEdi',
  username: 'SI60573350.HQ',
  password: 'your-api-password',
});

const guid = await client.login();

// Send an e-invoice
const docId = await client.sendInvoice(guid, {
  from: 'C:SI60573350.HQ',
  to: 'C:SI12345678',
  document: {
    fileName: 'invoice-123.xml',
    rawData: Buffer.from(invoiceXml).toString('base64'),
  },
});

// Receive pending messages
for await (const message of client.receiveAllMessages(guid)) {
  console.log('Received docId:', message.docId);
  console.log('Envelope:', message.envelope);
  await client.commitMessage(guid, message.docId!);
}

await client.logout(guid);

Scripts

bun run build          # compile TypeScript to dist/
bun test               # run all tests
bun run test:unit      # unit tests only
bun run test:integration # integration tests against demohr.zzi.si

Configuration

Integration tests read credentials from .env:

BIZBOX_USERNAME=SI60573350.HQ
BIZBOX_PASSWORD=your-api-password
BIZBOX_BASE_URL=https://demohr.zzi.si/BizBoxEdiRest/BizBoxEdi

Document types

| Use case | Type constant | Typical format | |----------|--------------|----------------| | e-račun | DocumentType.INVOICE | DocumentFormat.eSLOG_2_0_INVOICE | | dobavnica | DocumentType.DESPATCH_ADVICE | DocumentFormat.eSLOG_2_0_DESPATCH_ADVICE |

Interactive CLI scripts

The interactive/ folder contains manual helpers for testing against the real API. They read credentials from .env directly, bypassing any shell environment overrides.

# Send a test e-invoice to the configured receiver (defaults to self)
bun interactive/toBizBox.ts

# Send a specific XML file as an invoice or despatch advice
bun interactive/toBizBox.ts --type invoice --file tests/fixtures/incoming-invoices/1_61772_2026.XML --to C:SI12345678
bun interactive/toBizBox.ts --type despatch --file tests/fixtures/dobavnice/NENSIXMLDOB25043023.xml --to C:SI12345678

# Inspect pending messages without committing them
bun interactive/readBizBox.ts
bun interactive/readBizBox.ts --limit 10

Retry

All API calls are retried automatically on transient network errors and 5xx/429 responses. Configure via constructor options:

const client = new BizBoxClient({
  baseUrl: '...',
  username: '...',
  password: '...',
  retry: { maxAttempts: 5, initialDelayMs: 1000 },
});

Receiving documents

import { DocumentType, nensiDobavnicaXmlToJson, decodeDocument } from 'cry-bizbox';

for await (const msg of client.receiveAllMessages(guid)) {
  const type = msg.envelope?.document?.type;
  const xml = decodeDocument(msg.envelope!.document!.rawData!);

  if (type === DocumentType.INVOICE) {
    // process invoice
  } else if (type === DocumentType.DESPATCH_ADVICE) {
    const dobavnica = nensiDobavnicaXmlToJson(xml);
    console.log(dobavnica.GLAVA.STEVILKA_DOBAVNICE);
  }

  // Manually commit after successful processing.
  await client.commitMessage(guid, msg.docId!);
}

⚠️ bizBox returns the same uncommitted message on every receiveAllMessages call. You must commit each message before the next one is returned.

See also

• AGENTS.md — detailed API notes, sample fixtures, and implementation context
• docs/swagger-bizbox-edi-2.0.0.json — official OpenAPI spec