Getting started

Getting Started

HelvCore is a REST API for Swiss bookkeeping, billing, bank evidence, and MWST workflows. It gives product teams a production-shaped way to issue Swiss invoices, post canonical journal entries, manage open AR/AP, process CAMT evidence, and generate accountant-ready MWST packages with eCH-0217 XML.

https://api.helvcore.ch/v1 API key auth Production v1 contract Same DTOs across environments.

Your first call

Start with one server-side API key, confirm the activated connection, then submit source facts or domain actions. The client integration model is intentionally boring: one Bearer key, stable JSON DTOs, idempotent writes, and structured errors.

Create an API key

Open the client console after access approval, create a named key, copy it once, and store it in your backend secrets.

Confirm connection status

Call /v1/connection/status to read tenant, end-customer, fiscal year, VAT setup, readiness, and blockers.

Use production-shaped endpoints

Create invoices, expenses, supplier payables, CAMT evidence, statements, and MWST packages through the documented v1 contract.

GETGET /v1/connection/status

curl https://api.helvcore.ch/v1/connection/status \
  -H "Authorization: Bearer $HELVCORE_API_KEY"

What you can build

HelvCore owns Swiss finance logic that should not be re-derived in client apps.

Documents/v1/invoices

Create and issue Swiss invoices and credit notes with QR-bill validation, document-number control, tax snapshots, archive evidence, and journal posting.

Expenses and AP/v1/source-facts + /v1/supplier-payables

Persist receipt evidence, review expense VAT, post supplier payables, settle AP from bank evidence, and read canonical open items.

Bank evidence/v1/camt-053 + /v1/camt-054

Parse Swiss bank statement/payment notification files, expose reconciliation previews, and record reviewed decisions without hiding finality.

MWST/v1/mwst/review-packages

Generate accountant-readable MWST review packages, freeze them, produce eCH-0217 v2.0.0 XML, and validate the XML against the official XSD.

How the API works

Predictable REST

Resource-oriented URLs, JSON request/response bodies, and standard HTTP status codes.

Idempotent writes

Every mutating business action uses a stable Idempotency-Key so retries do not duplicate invoices, payments, or postings.

Swiss source of truth

Tax codes, QR rules, account mappings, fiscal-year setup, and MWST mappings are HelvCore-owned and exposed through read APIs.

Structured errors

Failures return stable error codes, field paths, request ids, retry posture, and documentation links.

Traceable accounting

Posted journals, VAT snapshots, CAMT hashes, source facts, and report hashes remain linkable for accountant review.

OpenAPI-first

The generated OpenAPI document is the canonical machine-readable contract for clients and SDKs.