Use the Local Automation API

Automate Billance on this computer

The Local Automation API connects custom scripts, workflows, or local business software to Billance. It manages outgoing documents and incoming receipts, payments and master data, and can validate or extract e-invoices.

Important: The API is a Premium feature. It runs only on this computer and only while the Billance desktop app is open. It is neither a cloud endpoint nor a ready-made connector for a specific ERP vendor.

Quick start

1. Open Settings → Integrations → Local Automation API.
2. Enable the local server.
3. Keep the suggested port or choose an available port between 1024 and 65535.
4. Copy the displayed base URL and access token into your automation tool.
5. Run the connection test.

| Setting | Default | Purpose | | --- | --- | --- | | Base URL | http://127.0.0.1:47115/api/integration/v1 | Shared prefix for every API path | | Network access | 127.0.0.1 | Only programs on the same computer can connect | | Authentication | Bearer token | Required for all business-data and write requests |

LAN devices, cloud services, and browser applications cannot connect directly. Browser applications deliberately receive no CORS permission.

Test the connection

Replace <TOKEN> with the token displayed in Billance:

curl \
  -H "Authorization: Bearer <TOKEN>" \
  "http://127.0.0.1:47115/api/integration/v1/health"

A successful response includes "status": "ok", the API and app versions, and the available capabilities.

Keep the token secure

Every protected request needs this header:

Authorization: Bearer blc_YOUR_TOKEN

The token grants access to your local Billance data. Therefore:

• Never store it in source code, Git repositories, or logs.
• Use environment variables or your automation tool's secret store.
• Rotate it immediately if it was accidentally disclosed.
• Update every client afterwards: the old token becomes invalid immediately.

Only GET / and GET /openapi.json are available without a token. GET /health also requires a token.

Discover the contract and endpoints

The API settings page includes a searchable endpoint overview with parameters, example payloads, and copyable cURL commands. The OpenAPI 3.1 specification is available for tools and generated clients at:

<BASE-URL>/openapi.json

Always use the specification served by your installed Billance version so your client matches the app's actual contract.

Outgoing documents

To create a draft, send POST /invoices with documentType and complete formData. formData mirrors the Billance editor: seller, recipient, line items, tax rules, payment data, text blocks, and document-specific values.

| Purpose | Route | Note | | --- | --- | --- | | Create a draft | POST /invoices | Use documentType and complete formData | | Read a draft | GET /invoices/{id} | Fetch before every full update | | Replace a draft | PUT /invoices/{id} | Replaces the form data completely | | Generate a document | POST /invoices/{id}/generate | Creates the configured PDF or e-invoice artifact | | Download an export | GET /invoices/{id}/export?format=pdf | One-shot download; see OpenAPI for other formats |

Supported documentType values are invoice, offer, confirmation, delivery_note, credit_note, recurring, and reminder. New integrations must use formData; data is only a deprecated compatibility alias.

Be careful with PUT: Read the current draft first, then send back the complete formData. This preserves unknown or future fields. Finalized documents cannot be changed because of the GoBD lock.

Generate, export, and finalize

POST /invoices/{id}/generate uses the same templates, fonts, payment profiles, and e-invoice rules as the interface. GET /invoices/{id}/export supports pdf, zugferd, xrechnung, ubl, and json; not every document type supports every file format.

Use POST /invoices/{id}/finalize for the first status transition. Send later permitted transitions to POST /invoices/{id}/status:

{
  "status": "cancelled",
  "note": "Cancellation by external workflow"
}

An invalid transition returns 409 with the stable error code invalid_status_transition. Send payments to POST /invoices/{id}/payments; Billance calculates paid amount, remaining balance, status, and early-payment discount automatically.

Master data and incoming receipts

/recipients and /products provide list, create, update, and delete operations. Writes always target the active company profile. You cannot override server-assigned IDs, profile assignments, or timestamps; writing to another profile returns 409 profile_not_active.

Use /receipts to manage incoming invoices and receipts. Upload original files with POST /receipts/{id}/attachment:

{
  "fileName": "incoming-invoice.pdf",
  "base64Content": "JVBERi0xLjQ..."
}

PDF, PNG, JPEG, WebP, HEIC, TIFF, and XML files up to 50 MB are supported. Billance stores them safely, calculates a SHA-256 hash, and never exposes local file-system paths. Finalized originals cannot be replaced or removed. Use /receipts/{id}/payments for receipt payments; Billance calculates partial payments, overpayments, and discounts automatically.

E-invoices and errors

• POST /import/validate validates PDF or XML files against supported EN 16931 rules.
• POST /import/einvoice additionally returns structured invoice data.
• Both endpoints expect Base64 content and fileType set to pdf or xml; they deliberately do not create an outgoing document automatically.

Errors follow RFC 7807 (application/problem+json). Use the stable code, not only the readable message:

| Status | Code | Meaning | | --- | --- | --- | | 401 | unauthorized | The token is missing or invalid | | 403 | premium_required | Premium access is unavailable | | 404 | not_found | The resource or local original file is unavailable | | 409 | profile_not_active, receipt_locked, invalid_status_transition | Business conflict or GoBD lock | | 413 / 415 / 422 | payload_too_large, unsupported_media_type, validation_failed | Request, file type, or data is invalid | | 429 | rate_limited | More than 120 requests within one minute |

If something does not work

1. Billance is open, you are signed in, and Premium is active.
2. The API is enabled and your client uses the exact displayed base URL and port.
3. The request comes from the same computer through 127.0.0.1.
4. The header is exactly Authorization: Bearer <TOKEN>.
5. No other program is using the port; otherwise choose another one in settings.
6. If the token was rotated, update your client's secret store.

For reliable integrations: store Billance IDs in the source system, handle 409 conflicts deliberately, check with GET after timeouts before retrying a write, and limit concurrency with backoff after 429. LAN, cloud, or mobile access requires your own secured gateway with authentication, encryption, authorization, and a privacy design.