Accounts API

Accounts (Konten) ermöglichen es Ihnen, Ihre Buchhaltungskonten zu verwalten. Jedes Konto hat eine Nummer, einen Namen, eine Kategorie und kann Buchungen enthalten. Milkee unterstützt verschiedene Kontotypen gemäss Schweizer Kontenrahmen KMU.

Account-Objekt

json

{
  "data": {
    "id": 150,
    "company_id": 123,
    "account_category_id": 5,
    "number": 1020,
    "name": "Bank UBS",
    "currency": "CHF",
    "iban": "CH9300762011623852957",
    "is_primary_bank_account": true,
    "balance": 25430.50,
    "balance_formatted": "CHF 25,430.50",
    "created_at": "2023-06-04T15:23:12.000000Z",
    "updated_at": "2025-01-14T10:45:00.000000Z"
  }
}

Attribute

Feld	Typ	Beschreibung
`id`	integer	Eindeutige Account-ID
`company_id`	integer	ID der zugehörigen Firma
`account_category_id`	integer	ID der Kontokategorie
`number`	integer	Kontonummer (1000-9999)
`name`	string	Name des Kontos
`currency`	string	Währung (z.B. CHF, EUR)
`iban`	string\|null	IBAN (nur für Bankkonten)
`is_primary_bank_account`	boolean	Ob dies das Standard-Bankkonto ist
`balance`	float\|null	Aktueller Saldo (nur wenn berechnet)
`balance_formatted`	string\|null	Formatierter Saldo (nur wenn berechnet)
`created_at`	datetime	Erstellungsdatum
`updated_at`	datetime	Datum der letzten Aktualisierung

Kontotypen

Milkee unterstützt folgende Kontotypen gemäss Schweizer Kontenrahmen KMU:

Typ	Beschreibung	Nummernbereich	Verwendung
`bank`	Bankkonten	1000-1059	Liquidität, Bankguthaben
`deprecations`	Abschreibungskonten	1500-1599	Wertberichtigungen, Abschreibungen
`income`	Ertragskonten	3000-3999	Umsatzerlöse, Dienstleistungen
`expense`	Aufwandkonten	4000-8999	Betriebsaufwand, Kosten
`assets`	Aktivkonten	1000-1999	Vermögenswerte
`liabilities`	Passivkonten	2000-2999	Verbindlichkeiten, Eigenkapital
`balance_sheet`	Bilanzkonten	1000-2999	Alle Bilanzkonten

Endpoints

Alle Accounts auflisten

http

GET /companies/{company}/accounts

Ruft eine Liste aller Accounts der Firma ab, optional gefiltert nach Typ.

Parameter

Parameter	Typ	Standard	Beschreibung
`type`	string	all	Kontotyp-Filter: `bank`, `deprecations`, `income`, `expense`, `assets`, `liabilities`, `balance_sheet`, `all`
`start`	date	-	Startdatum für Saldobe rechnung (Format: YYYY-MM-DD)
`until`	date	-	Enddatum für Saldoberechnung (Format: YYYY-MM-DD)

Response

json

[
  {
    "id": 150,
    "company_id": 123,
    "account_category_id": 5,
    "number": 1020,
    "name": "Bank UBS",
    "currency": "CHF",
    "iban": "CH9300762011623852957",
    "is_primary_bank_account": true,
    "balance": 25430.50,
    "balance_formatted": "CHF 25,430.50",
    "created_at": "2023-06-04T15:23:12.000000Z",
    "updated_at": "2025-01-14T10:45:00.000000Z"
  },
  {
    "id": 151,
    "company_id": 123,
    "account_category_id": 5,
    "number": 1021,
    "name": "Bank PostFinance",
    "currency": "CHF",
    "iban": "CH4509000000123456789",
    "is_primary_bank_account": false,
    "balance": 5200.00,
    "balance_formatted": "CHF 5,200.00",
    "created_at": "2023-06-04T15:23:12.000000Z",
    "updated_at": "2025-01-14T10:45:00.000000Z"
  }
]

Saldo-Berechnung

Wenn Sie start und/oder until Parameter angeben, werden die Salden (balance und balance_formatted) für jeden Account automatisch für den angegebenen Zeitraum berechnet.

Spezial-Einträge bei Passivkonten

Wenn Sie type=liabilities verwenden, werden zusätzlich zwei berechnete Einträge angehängt:

Unverbuchter Gewinn / Verlustvortrag: Gewinnvortrag aus Vorperioden
Unverbuchter Gewinn / Verlust: Gewinn/Verlust der aktuellen Periode

Beispiele

bash

# Alle Accounts abrufen
curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/accounts"

# Nur Bankkonten abrufen
curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/accounts?type=bank"

# Ertragskonten mit Saldo für 2024
curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/accounts?type=income&start=2024-01-01&until=2024-12-31"

# Passivkonten mit Gewinn/Verlust
curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/accounts?type=liabilities"

Neuen Account erstellen

http

POST /companies/{company}/accounts

Erstellt ein neues Konto für die angegebene Firma.

Request Body

json

{
  "name": "Bank Raiffeisen",
  "number": 1025,
  "type": "bank",
  "iban": "CH5604835012345678009",
  "is_primary_bank_account": false
}

Validierung

Feld	Regeln
`name`	`required`, `string`, `max:255`
`number`	`required`, `integer`, `min:1000`, `max:9999`, muss einzigartig sein
`type`	`required`, `string`, einer von: `bank`, `income`, `expense`, `assets`, `liabilities`, `balance_sheet`
`iban`	`nullable`, `string`, `max:34`, gültige IBAN (nur für Bankkonten)
`is_primary_bank_account`	`nullable`, `boolean` (nur für Bankkonten)

Besonderheiten

Bankkonten: Nummer muss zwischen 1000 und 1059 liegen
IBAN-Validierung: IBAN wird automatisch validiert und formatiert (Leerzeichen entfernt, Grossbuchstaben)
Standard-Bankkonto: Wenn is_primary_bank_account=true, werden alle anderen Bankkonten als nicht-primär markiert
Kontokategorie: Wird automatisch basierend auf type zugewiesen

Response

http

HTTP/1.1 200 OK
Content-Type: application/json

{
  "data": {
    "id": 152,
    "company_id": 123,
    "account_category_id": 5,
    "number": 1025,
    "name": "Bank Raiffeisen",
    "currency": "CHF",
    "iban": "CH5604835012345678009",
    "is_primary_bank_account": false,
    "created_at": "2025-01-14T14:22:00.000000Z",
    "updated_at": "2025-01-14T14:22:00.000000Z"
  }
}

Beispiele

bash

# Bankkonto erstellen
curl -X POST \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Bank Raiffeisen",
       "number": 1025,
       "type": "bank",
       "iban": "CH5604835012345678009"
     }' \
     "https://app.milkee.ch/api/v2/companies/123/accounts"

# Ertragskonto erstellen
curl -X POST \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Dienstleistungserlöse",
       "number": 3200,
       "type": "income"
     }' \
     "https://app.milkee.ch/api/v2/companies/123/accounts"

# Aufwandkonto erstellen
curl -X POST \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Büromaterial",
       "number": 6300,
       "type": "expense"
     }' \
     "https://app.milkee.ch/api/v2/companies/123/accounts"

Einzelnes Account abrufen

http

GET /companies/{company}/accounts/{account}

Ruft die Details eines spezifischen Accounts ab, inklusive aktuellem Saldo.

Parameter

Parameter	Typ	Beschreibung
`company`	integer	Firmen-ID
`account`	integer	Account-ID

Response

json

{
  "data": {
    "id": 150,
    "company_id": 123,
    "account_category_id": 5,
    "number": 1020,
    "name": "Bank UBS",
    "currency": "CHF",
    "iban": "CH9300762011623852957",
    "is_primary_bank_account": true,
    "balance": 25430.50,
    "balance_formatted": "CHF 25,430.50",
    "created_at": "2023-06-04T15:23:12.000000Z",
    "updated_at": "2025-01-14T10:45:00.000000Z"
  }
}

Saldo automatisch berechnet

Der show Endpoint berechnet automatisch den aktuellen Saldo (balance und balance_formatted) des Kontos.

Beispiel

bash

curl -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/accounts/150"

Account aktualisieren

http

PUT /companies/{company}/accounts/{account}

Aktualisiert ein bestehendes Konto.

Request Body

json

{
  "name": "Bank UBS Geschäftskonto",
  "number": 1020,
  "iban": "CH9300762011623852957",
  "is_primary_bank_account": true
}

Validierung

Feld	Regeln
`name`	`sometimes`, `string`, `max:255`
`number`	`sometimes`, `integer`, `min:1000`, `max:9999`, muss einzigartig sein
`iban`	`nullable`, `string`, `max:34`, gültige IBAN (nur für Bankkonten)
`is_primary_bank_account`	`sometimes`, `boolean` (nur für Bankkonten)

Besonderheiten

Nummernänderung: Prüft ob neue Nummer bereits vergeben ist
Bankkonten: Nummer muss weiterhin zwischen 1000-1059 liegen
IBAN: Kann nur für Bankkonten gesetzt werden (Fehler 422 sonst)
Standard-Bankkonto: Kann nur für Bankkonten gesetzt werden (Fehler 422 sonst)

Response

json

{
  "data": {
    "id": 150,
    "company_id": 123,
    "account_category_id": 5,
    "number": 1020,
    "name": "Bank UBS Geschäftskonto",
    "currency": "CHF",
    "iban": "CH9300762011623852957",
    "is_primary_bank_account": true,
    "created_at": "2023-06-04T15:23:12.000000Z",
    "updated_at": "2025-01-14T15:45:00.000000Z"
  }
}

Beispiel

bash

curl -X PUT \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{
       "name": "Bank UBS Geschäftskonto",
       "is_primary_bank_account": true
     }' \
     "https://app.milkee.ch/api/v2/companies/123/accounts/150"

Account löschen

http

DELETE /companies/{company}/accounts/{account}

Löscht ein bestehendes Konto unwiderruflich.

Löschbedingungen

Ein Account kann nur gelöscht werden, wenn:

Keine Buchungen (Soll oder Haben) mit dem Konto verknüpft sind
Keine wiederkehrenden Buchungen das Konto verwenden
Die Kontokategorie danach noch mindestens ein Konto enthält

Andernfalls wird ein 400-Fehler zurückgegeben.

Response

http

HTTP/1.1 204 No Content

Beispiel

bash

curl -X DELETE \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/accounts/152"

Kontenplan zurücksetzen

http

POST /companies/{company}/accounts/reset

Setzt den Kontenplan der Firma auf den Standard-Kontenrahmen KMU zurück. Alle bestehenden Konten werden gelöscht und durch die Standardkonten ersetzt.

Achtung: Datenverlust

Dieser Vorgang ist unwiderruflich! Alle benutzerdefinierten Konten werden gelöscht. Stellen Sie sicher, dass Sie ein Backup haben.

Response

json

{
  "data": [
    {
      "id": 200,
      "company_id": 123,
      "account_category_id": 5,
      "number": 1000,
      "name": "Kasse",
      "currency": "CHF",
      "iban": null,
      "is_primary_bank_account": false,
      "created_at": "2025-01-14T16:00:00.000000Z",
      "updated_at": "2025-01-14T16:00:00.000000Z"
    },
    {
      "id": 201,
      "company_id": 123,
      "account_category_id": 5,
      "number": 1020,
      "name": "Bank",
      "currency": "CHF",
      "iban": null,
      "is_primary_bank_account": false,
      "created_at": "2025-01-14T16:00:00.000000Z",
      "updated_at": "2025-01-14T16:00:00.000000Z"
    }
  ]
}

Beispiel

bash

curl -X POST \
     -H "Authorization: Bearer 1|abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/accounts/reset"

Fehlerbehandlung

Häufige Fehler

400 Bad Request - Kontonummer bereits vergeben

json

{
  "message": "Die Kontonummer ist bereits vergeben."
}

400 Bad Request - Ungültige Bankkontonummer

json

{
  "message": "Die Kontonummer für Bankkonten muss zwischen 1000 und 1059 liegen."
}

400 Bad Request - Konto hat Buchungen

json

{
  "message": "Das Konto kann nicht gelöscht werden, da es Buchungen hat."
}

400 Bad Request - Konto hat wiederkehrende Buchungen

json

{
  "message": "Das Konto hat wiederkehrende Buchungen. Lösche diese zuerst."
}

400 Bad Request - Letztes Konto in Kategorie

json

{
  "message": "Du brauchst mindestens 1 Konto in dieser Kategorie."
}

422 Validation Error - Ungültige IBAN

json

{
  "message": "Invalide IBAN"
}

422 Validation Error - IBAN nur für Bankkonten

json

{
  "message": "IBANs können nur für Bankkonten erfasst werden."
}

422 Validation Error

json

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "Der Name ist erforderlich."
    ],
    "number": [
      "Die Kontonummer muss mindestens 1000 sein."
    ],
    "type": [
      "Der Kontotyp ist ungültig."
    ]
  }
}

Häufige Validierungsfehler:

name.required: Name ist erforderlich
name.max: Name zu lang (maximal 255 Zeichen)
number.required: Kontonummer ist erforderlich
number.integer: Kontonummer muss eine Zahl sein
number.min: Kontonummer muss mindestens 1000 sein
number.max: Kontonummer darf maximal 9999 sein
type.required: Kontotyp ist erforderlich
type.in: Ungültiger Kontotyp
iban.max: IBAN zu lang (maximal 34 Zeichen)

Best Practices

Kontonummern-Schema

Folgen Sie dem Schweizer Kontenrahmen KMU für konsistente Buchhaltung. Die wichtigsten Nummernbereiche sind:

1000-1009: Kasse
1000-1059: Bankkonten
1100-1199: Forderungen
2000-2099: Kurzfristige Verbindlichkeiten
2800-2899: Eigenkapital
3000-3999: Erträge
4000-4999: Materialaufwand
5000-5999: Personalaufwand
6000-6999: Übriger Aufwand

IBAN-Validierung

Validieren und formatieren Sie IBANs vor dem Absenden. Entfernen Sie Leerzeichen und Bindestriche und konvertieren Sie zu Grossbuchstaben. Schweizer IBANs haben immer 21 Zeichen (CH + 2 Prüfziffern + 5 Bankcode + 12 Kontonummer).

Saldo-Überwachung

Nutzen Sie die start und until Parameter beim Abrufen von Konten, um Salden für bestimmte Zeiträume zu berechnen. Dies ist nützlich für Liquiditätsüberwachung und Reporting.

Sicheres Löschen von Konten

Konten mit Buchungen können nicht gelöscht werden. Als Alternative können Sie das Konto umbenennen (z.B. mit dem Zusatz "Veraltet - nicht mehr verwenden").

Standard-Bankkonto setzen

Nur Konten im Bereich 1000-1059 können als Standard-Bankkonto markiert werden. Beim Setzen von is_primary_bank_account=true werden automatisch alle anderen Bankkonten als nicht-primär markiert.

Nächste Schritte

Entries API - Buchungen auf Konten erstellen
Tax Rates API - Steuersätze mit Konten verknüpfen
Code-Beispiele ansehen
Webhooks einrichten

Accounts API ​

Account-Objekt ​

Attribute ​

Kontotypen ​

Endpoints ​

Alle Accounts auflisten ​

Parameter ​

Response ​

Beispiele ​

Neuen Account erstellen ​

Request Body ​

Validierung ​

Besonderheiten ​

Response ​

Beispiele ​

Einzelnes Account abrufen ​

Parameter ​

Response ​

Beispiel ​

Account aktualisieren ​

Request Body ​

Validierung ​

Besonderheiten ​

Response ​

Beispiel ​

Account löschen ​

Response ​

Beispiel ​

Kontenplan zurücksetzen ​

Response ​

Beispiel ​

Fehlerbehandlung ​

Häufige Fehler ​

400 Bad Request - Kontonummer bereits vergeben ​

400 Bad Request - Ungültige Bankkontonummer ​

400 Bad Request - Konto hat Buchungen ​

400 Bad Request - Konto hat wiederkehrende Buchungen ​

400 Bad Request - Letztes Konto in Kategorie ​

422 Validation Error - Ungültige IBAN ​

422 Validation Error - IBAN nur für Bankkonten ​

422 Validation Error ​

Best Practices ​

Kontonummern-Schema ​

IBAN-Validierung ​

Saldo-Überwachung ​

Sicheres Löschen von Konten ​

Standard-Bankkonto setzen ​

Nächste Schritte ​

Accounts API

Account-Objekt

Attribute

Kontotypen

Endpoints

Alle Accounts auflisten

Parameter

Response

Beispiele

Neuen Account erstellen

Request Body

Validierung

Besonderheiten

Response

Beispiele

Einzelnes Account abrufen

Parameter

Response

Beispiel

Account aktualisieren

Request Body

Validierung

Besonderheiten

Response

Beispiel

Account löschen

Response

Beispiel

Kontenplan zurücksetzen

Response

Beispiel

Fehlerbehandlung

Häufige Fehler

400 Bad Request - Kontonummer bereits vergeben

400 Bad Request - Ungültige Bankkontonummer

400 Bad Request - Konto hat Buchungen

400 Bad Request - Konto hat wiederkehrende Buchungen

400 Bad Request - Letztes Konto in Kategorie

422 Validation Error - Ungültige IBAN

422 Validation Error - IBAN nur für Bankkonten

422 Validation Error

Best Practices

Kontonummern-Schema

IBAN-Validierung

Saldo-Überwachung

Sicheres Löschen von Konten

Standard-Bankkonto setzen

Nächste Schritte