Local automation API

What the API is — and what it is not

The automation API is a local HTTP server that Billance starts on your computer. It manages outgoing documents and incoming receipts, payments and master data, and it can validate or read e-invoices. It is not a cloud endpoint and not a ready-made connector for a particular ERP vendor but a technical interface for your own scripts, workflows and local business software.

Access is deliberately narrow: the server listens on 127.0.0.1, so only programs on the same computer reach it. Devices on the LAN, cloud services and browser applications cannot access it directly — browsers are intentionally given no CORS clearance. Every business request needs the bearer token Billance shows in the settings; without a token only the root path and the OpenAPI specification are reachable.

The contract is shipped rather than described: the settings hold a searchable endpoint overview with parameters, example payloads and copyable cURL commands, and <BASE-URL>/openapi.json serves the OpenAPI 3.1 specification for tools and generated clients. Always use the specification of your installed version so your client matches the app’s actual contract.

Connected in five steps

1. 1

   Enable the API

   Turn the local server on under Settings → Integrations.

2. 2

   Set the port

   Keep the default port 47115 or pick a free port between 1024 and 65535 if another program occupies it.

3. 3

   Copy base URL and token

   Both go into your automation tool; the token belongs in a secret store, never in source code, a repository or logs.

4. 4

   Test the connection

   A call to /health with the authorization header returns the status, API and app version and the available capabilities.

5. 5

   Explore the endpoints

   The endpoint overview in the settings and the OpenAPI specification show parameters, example payloads and cURL commands.

What the API covers

• Create outgoing documents

  POST /invoices with documentType and complete formData — the form model mirrors the app’s editor.

• All seven document types

  invoice, offer, confirmation, delivery_note, credit_note, recurring and reminder are available.

• Generate and export

  POST /invoices/{id}/generate uses the same templates, fonts, payment profiles and e-invoice rules as the interface; the export returns PDF, ZUGFeRD, XRechnung, UBL or JSON.

• Status changes with clear errors

  finalize for the first transition, status for the rest; disallowed changes return 409 with the stable code invalid_status_transition.

• Payments calculated for you

  Payments go to /invoices/{id}/payments; Billance derives paid amount, remaining balance, status and discount itself.

• Maintain master data

  /recipients and /products offer list, create, update and delete access; writes always apply to the active company profile.

• Receipts and attachments

  /receipts manages supplier invoices; original files are uploaded as base64 — PDF, PNG, JPEG, WebP, HEIC, TIFF and XML up to 50 MB.

• Validate and read e-invoices

  POST /import/validate checks PDF or XML files, POST /import/einvoice additionally returns structured invoice data — neither creates a document automatically.

• Errors under RFC 7807

  Responses arrive as application/problem+json with a stable code you can evaluate instead of parsing text.

Token, boundaries and error codes

The token grants access to your local Billance data. The boundaries are drawn narrowly to match — and the token deserves to be handled accordingly.

Never store the token in source code, repositories or logs. After renewing it, the old token becomes invalid immediately and every client has to be updated.

What makes an integration hold up

A handful of rules decide whether a connection still works after the second update.

• Read before every PUT

  PUT /invoices/{id} replaces the form data entirely. Read the current draft first and send it back completely so unknown or later added fields are preserved.

• Store IDs in the source system

  That way your software finds a document again after a restart instead of creating it a second time.

• Read first after a timeout

  Check with GET whether the write already arrived before repeating it.

• Handle conflicts deliberately

  A 409 is a business statement — a lock on finalized data, say — and not a reason to simply retry.

• Limit concurrency

  After a 429, continue with backoff instead of sending at the same rate.

• Use only formData

  New integrations use formData exclusively; data is only a deprecated compatibility alias.

For LAN, cloud or mobile access you need your own secured intermediary layer with authentication, encryption, permissions and a data protection concept.

Where the API runs

The automation API is a feature of the desktop application, because it needs a local server on your machine.

Free or Premium

Without Premium access the API answers with 403 premium_required rather than quietly doing nothing.

Frequently asked questions about the automation API

Read on