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.

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, editable JSON, copyable cURL commands, and a test button. The test button runs the request against the active local API and shows the HTTP status and response below it. Mutating operations require an extra confirmation and change real local data. 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.

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.

For a simple invoice, POST /invoices/simple accepts invoiceNumber, invoiceDate, a recipient with name and address, and items with name, quantity, unit price, and tax rate. Optional fields are paymentDueDays, currency, outputMode (pdf or zugferd_en16931), and designTemplateId. Billance uses seller details from the active company profile. Use complete formData for further e-invoice fields.

Reliable writes and cloud sync

Send a unique Idempotency-Key (1–128 printable ASCII characters) with mutating requests. After a transport failure, retry the exact same request with the same key. Billance retains the result for seven days; different content with the same key returns 409 idempotency_key_reused. An unresolved first attempt returns 409 idempotency_pending. The read-only import and validation requests do not use this header.

Single-resource GET responses contain an ETag. Supply it as If-Match on general PUT/DELETE requests to reject a resource changed in the meantime with 412 revision_conflict. Omitting If-Match keeps the existing behavior.

Successful writes confirm local storage. GET /sync/status reports the current cloud sync provider state; it is not a delivery receipt for an individual record. Invoice lists are paginated. For recipients, products, and receipts, page or pageSize enables SQL-backed pagination with totals, up to 200 items per page.

Select a PDF design

Use GET /invoice-designs to list the custom and built-in PDF designs of the active company profile. Each item includes its id, name, and isDefault status. ?profileId=<id> selects another profile for this read operation.

Send the chosen ID as top-level designTemplateId in POST /invoices, POST /invoices/simple, or PUT /invoices/{id}. Billance checks that the design belongs to the active company profile before saving. If omitted, that profile’s default design applies. On a full PUT, designTemplateId: null clears the previous selection; omitting the top-level field preserves the selection in formData._designTemplateId. Responses include the stored designTemplateId.

The design controls PDF appearance, including ZUGFeRD PDFs. XML-only exports have no PDF design. An unknown or other-profile design ID returns 422 validation_failed.

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; invoice and receipt writes to another profile return 409 profile_not_active; master-data repository rules protect profile assignments.

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:

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.

More API guides

Related articles explain the full API workflow through PDF download, e-invoices through the API, and safe retries/conflicts. The app also includes expandable field/response references from its OpenAPI specification and selectable API examples.