Steuersätze API

Die Steuersätze-API ermöglicht es dir, Mehrwertsteuersätze und andere Steuersätze für dein Unternehmen zu verwalten. Steuersätze werden in Buchungen, Rechnungen und Offerten verwendet und können mit spezifischen Konten (Aktiven oder Passiven) verknüpft werden. Die API unterstützt auch schweizspezifische Funktionen wie Saldosteuersätze und Bezugsteuer.

TaxRate-Objekt

{
  "id": 99,
  "company_id": 123,
  "account_id": 150,
  "acquisition_account_id": null,
  "field_number": 302,
  "name": "MwSt 8.1%",
  "name_en": null,
  "name_fr": null,
  "name_it": null,
  "name_on_documents": "MwSt 8.1%",
  "rate": 8.1,
  "saldo_rate": null,
  "calculation_method": "net",
  "is_acquisition_tax": false,
  "archived": false,
  "created_at": "2023-06-04T15:23:12.000000Z",
  "updated_at": "2025-01-14T10:45:00.000000Z",
  "account": {
    "id": 150,
    "name": "Mehrwertsteuer"
  },
  "acquisition_account": null
}

Attribute

Feld	Typ	Beschreibung
id	integer	Eindeutige ID des Steuersatzes
company_id	integer	ID des zugehörigen Unternehmens
account_id	integer	ID des Steuerkontos (muss Aktive oder Passive sein)
acquisition_account_id	integer|null	ID des Bezugsteuer-Kontos (nur bei Bezugsteuer)
field_number	integer|null	Feldnummer für MwSt-Abrechnung (z.B. für Schweizer MwSt-Formular)
name	string	Name des Steuersatzes (Hauptname)
name_en	string|null	Englische Übersetzung des Namens
name_fr	string|null	Französische Übersetzung des Namens
name_it	string|null	Italienische Übersetzung des Namens
name_on_documents	string	Name, der auf Rechnungen und Offerten angezeigt wird
rate	float	Steuersatz in Prozent (z.B. 8.1 für 8.1%)
saldo_rate	float|null	Saldosteuersatz für vereinfachte MwSt-Abrechnung
calculation_method	enum	Berechnungsmethode: net (Netto) oder gross (Brutto)
is_acquisition_tax	boolean	Gibt an, ob es sich um Bezugsteuer handelt
archived	boolean	Archivierungsstatus (Soft-Delete)
created_at	timestamp	Erstellungszeitpunkt
updated_at	timestamp	Zeitpunkt der letzten Aktualisierung
account	object	Das zugehörige Steuerkonto (wenn geladen)
acquisition_account	object|null	Das zugehörige Bezugsteuer-Konto (wenn geladen)

Endpoints

Alle Steuersätze auflisten

Gibt eine paginierte Liste aller Steuersätze des Unternehmens zurück.

GET /companies/{company}/tax-rates

Parameter

Parameter	Typ	Standard	Beschreibung
page	integer	1	Seitennummer für Paginierung
per_page	integer	15	Anzahl Einträge pro Seite (max. 100)
filter[name]	string	-	Filtert nach Name (Teilstring-Suche)
filter[archived]	boolean	-	Filtert nach Archivierungsstatus
filter[id]	integer	-	Filtert nach spezifischer ID
sort	string	-	Sortierung: name, -name, rate, -rate

Response

{
  "data": [
    {
      "id": 99,
      "company_id": 123,
      "account_id": 150,
      "name": "MwSt 8.1%",
      "rate": 8.1,
      "archived": false,
      ...
    }
  ],
  "links": {
    "first": "https://api.milkee.ch/companies/123/tax-rates?page=1",
    "last": "https://api.milkee.ch/companies/123/tax-rates?page=3",
    "prev": null,
    "next": "https://api.milkee.ch/companies/123/tax-rates?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "per_page": 15,
    "to": 15,
    "total": 42
  }
}

Beispiele

Alle Steuersätze

curl -X GET "https://api.milkee.ch/companies/123/tax-rates" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Nach Name filtern

curl -X GET "https://api.milkee.ch/companies/123/tax-rates?filter[name]=mwst" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Nur aktive Steuersätze

curl -X GET "https://api.milkee.ch/companies/123/tax-rates?filter[archived]=false" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Nach Steuersatz sortieren

curl -X GET "https://api.milkee.ch/companies/123/tax-rates?sort=-rate" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Neuen Steuersatz erstellen

Erstellt einen neuen Steuersatz für das Unternehmen.

POST /companies/{company}/tax-rates

Request Body

{
  "name": "MwSt 8.1%",
  "name_on_documents": "MwSt 8.1%",
  "account_id": 150,
  "rate": 8.1,
  "saldo_rate": null,
  "field_number": 302,
  "is_acquisition_tax": false,
  "acquisition_account_id": null,
  "archived": false
}

Validierung

Feld	Regel	Beschreibung
name	required, string, max:255	Name des Steuersatzes (Pflichtfeld)
account_id	required, integer	Muss ein existierendes Konto vom Typ Aktive oder Passive sein
name_on_documents	optional, string	Wenn nicht angegeben, wird name verwendet
rate	numeric	Steuersatz in Prozent
saldo_rate	optional, numeric	Saldosteuersatz (setzt automatisch calculation_method auf gross)
field_number	optional, integer	Feldnummer für MwSt-Abrechnung
is_acquisition_tax	boolean	Gibt an, ob Bezugsteuer
acquisition_account_id	required if is_acquisition_tax	Muss Aktive oder Passive sein
archived	optional, boolean	Standard: false

Wichtig

Das Konto (account_id) und das Bezugsteuer-Konto (acquisition_account_id) müssen vom Typ Aktive oder Passive sein. Andere Kontotypen werden nicht akzeptiert.

Automatische Berechnung

Wenn saldo_rate gesetzt ist, wird calculation_method automatisch auf gross gesetzt. Bei normalen Steuersätzen wird net verwendet.

Response

{
  "id": 99,
  "company_id": 123,
  "account_id": 150,
  "acquisition_account_id": null,
  "field_number": 302,
  "name": "MwSt 8.1%",
  "name_on_documents": "MwSt 8.1%",
  "rate": 8.1,
  "saldo_rate": null,
  "calculation_method": "net",
  "is_acquisition_tax": false,
  "archived": false,
  "created_at": "2025-01-14T10:45:00.000000Z",
  "updated_at": "2025-01-14T10:45:00.000000Z"
}

Status Code: 200 OK

Beispiele

Normaler MwSt-Satz

curl -X POST "https://api.milkee.ch/companies/123/tax-rates" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MwSt 8.1%",
    "name_on_documents": "MwSt 8.1%",
    "account_id": 150,
    "rate": 8.1,
    "field_number": 302
  }'

Mit Saldosteuersatz

curl -X POST "https://api.milkee.ch/companies/123/tax-rates" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Saldosteuersatz 2.4%",
    "name_on_documents": "Saldosteuersatz 2.4%",
    "account_id": 150,
    "rate": 8.1,
    "saldo_rate": 2.4,
    "field_number": 302
  }'

Bezugsteuer

curl -X POST "https://api.milkee.ch/companies/123/tax-rates" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bezugsteuer 8.1%",
    "name_on_documents": "Bezugsteuer 8.1%",
    "account_id": 150,
    "rate": 8.1,
    "is_acquisition_tax": true,
    "acquisition_account_id": 151,
    "field_number": 381
  }'

Einzelnen Steuersatz abrufen

Gibt die Details eines spezifischen Steuersatzes zurück.

GET /companies/{company}/tax-rates/{taxRate}

Parameter

Parameter	Typ	Beschreibung
company	integer	ID des Unternehmens
taxRate	integer	ID des Steuersatzes

Response

{
  "id": 99,
  "company_id": 123,
  "account_id": 150,
  "acquisition_account_id": null,
  "field_number": 302,
  "name": "MwSt 8.1%",
  "name_on_documents": "MwSt 8.1%",
  "rate": 8.1,
  "saldo_rate": null,
  "calculation_method": "net",
  "is_acquisition_tax": false,
  "archived": false,
  "created_at": "2023-06-04T15:23:12.000000Z",
  "updated_at": "2025-01-14T10:45:00.000000Z",
  "account": {
    "id": 150,
    "name": "Mehrwertsteuer",
    "account_number": 2200
  },
  "acquisition_account": null
}

Status Code: 200 OK

Beispiel

curl -X GET "https://api.milkee.ch/companies/123/tax-rates/99" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Steuersatz aktualisieren

Aktualisiert einen existierenden Steuersatz.

PUT /companies/{company}/tax-rates/{taxRate}

Einschränkungen bei Buchungen

Wenn der Steuersatz bereits in Buchungen verwendet wird, können folgende Felder nicht mehr geändert werden:

• rate (Steuersatz)
• saldo_rate (Saldosteuersatz)
• account_id (Steuerkonto)

Andere Felder wie name, name_on_documents, archived und field_number können weiterhin angepasst werden.

Request Body

Alle Felder sind optional. Nur die Felder, die aktualisiert werden sollen, müssen gesendet werden.

{
  "name": "MwSt 8.1% (aktualisiert)",
  "name_on_documents": "MwSt 8.1%",
  "archived": false
}

Validierung

Die gleichen Validierungsregeln wie beim Erstellen gelten, zusätzlich:

Bedingung	Fehler	Status Code
Steuersatz hat Buchungen + rate ändern	"Der Steuersatz kann nicht angepasst werden, da Buchungen vorhanden sind."	422
Steuersatz hat Buchungen + saldo_rate ändern	"Der Saldosteuersatz kann nicht angepasst werden, da Buchungen vorhanden sind."	422
Steuersatz hat Buchungen + account_id ändern	"Das Konto kann nicht angepasst werden, da Buchungen vorhanden sind."	422
Konto ist nicht Aktive/Passive	"Bitte verwende nur Aktiven und Passiven für Steuersätze."	422

Response

{
  "id": 99,
  "company_id": 123,
  "name": "MwSt 8.1% (aktualisiert)",
  "name_on_documents": "MwSt 8.1%",
  "rate": 8.1,
  "archived": false,
  ...
}

Status Code: 200 OK

Beispiele

Name aktualisieren

curl -X PUT "https://api.milkee.ch/companies/123/tax-rates/99" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MwSt 8.1% (aktualisiert)"
  }'

Archivieren

curl -X PUT "https://api.milkee.ch/companies/123/tax-rates/99" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "archived": true
  }'

Steuersatz löschen

Löscht einen Steuersatz permanent.

DELETE /companies/{company}/tax-rates/{taxRate}

Löscheinschränkungen

Ein Steuersatz kann nicht gelöscht werden, wenn:

• Er in Buchungen verwendet wird
• Er in Rechnungen verwendet wird
• Er in Offerten verwendet wird

Empfehlung: Verwende stattdessen die Archivierungsfunktion (archived: true), um den Steuersatz aus der aktiven Nutzung zu entfernen, ohne historische Daten zu beeinträchtigen.

Parameter

Parameter	Typ	Beschreibung
company	integer	ID des Unternehmens
taxRate	integer	ID des Steuersatzes

Response

Bei erfolgreicher Löschung wird kein Body zurückgegeben.

Status Code: 204 No Content

Fehler

Bedingung	Fehlermeldung	Status Code
Hat Buchungen	"Dieser Steuersatz hat Buchungen. Archiviere ihn stattdessen."	409
Hat Rechnungen	"Dieser Steuersatz hat Rechnungen. Archiviere ihn stattdessen."	409
Hat Offerten	"Dieser Steuersatz hat Offerten. Archiviere ihn stattdessen."	409

Beispiel

curl -X DELETE "https://api.milkee.ch/companies/123/tax-rates/99" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Schweizspezifische Funktionen

Saldosteuersatz

Der Saldosteuersatz ist eine vereinfachte Methode der MwSt-Abrechnung in der Schweiz. Dabei wird ein reduzierter Steuersatz auf den Bruttoumsatz angewendet.

Wichtig:

• Wenn saldo_rate gesetzt ist, wird automatisch calculation_method auf gross gesetzt
• Der normale rate bleibt für die Rechnungsstellung erhalten
• Der saldo_rate wird für die MwSt-Abrechnung verwendet

Beispiel:

{
  "rate": 8.1,           // Normaler MwSt-Satz (für Rechnung)
  "saldo_rate": 2.4,     // Saldosteuersatz (für Abrechnung)
  "calculation_method": "gross"
}

Bezugsteuer

Die Bezugsteuer (Acquisition Tax) ist ein schweizspezifischer Mechanismus für die Versteuerung von Leistungen aus dem Ausland.

Wichtig:

• Setze is_acquisition_tax auf true
• Gib ein acquisition_account_id an (Konto für Vorsteuer)
• Wird automatisch auf calculation_method: gross gesetzt
• Feldnummer typischerweise 381 (für Schweizer MwSt-Formular)

Beispiel:

{
  "name": "Bezugsteuer 8.1%",
  "rate": 8.1,
  "is_acquisition_tax": true,
  "acquisition_account_id": 151,
  "field_number": 381
}

Mehrsprachigkeit

Steuersätze unterstützen mehrsprachige Namen für internationale Unternehmen:

Feld	Sprache
name	Deutsch (Standard)
name_en	Englisch
name_fr	Französisch
name_it	Italienisch

Beispiel:

{
  "name": "Mehrwertsteuer 8.1%",
  "name_en": "VAT 8.1%",
  "name_fr": "TVA 8.1%",
  "name_it": "IVA 8.1%",
  "name_on_documents": "MwSt 8.1%"
}

Beziehungen zu anderen Ressourcen

Steuersätze werden in folgenden Ressourcen verwendet:

• Kunden (customers): Haben einen Standard-Steuersatz (tax_rate_id)
• Buchungen (entries): Referenzieren einen Steuersatz
• Rechnungen (invoices): Haben einen Standard-Steuersatz
• Offerten (proposals): Haben einen Standard-Steuersatz

Include-Parameter bei anderen Endpoints:

• GET /companies/{company}/customers?include=taxRate
• GET /companies/{company}/entries?include=taxRate

Fehlerbehandlung

Häufige Fehler

422 Unprocessable Entity

Ungültiger Kontotyp:

{
  "message": "Bitte verwende nur Aktiven und Passiven für Steuersätze.",
  "errors": {
    "account_id": [
      "Das Konto muss vom Typ Aktive oder Passive sein."
    ]
  }
}

Steuersatz mit Buchungen ändern:

{
  "message": "Der Steuersatz kann nicht angepasst werden, da Buchungen vorhanden sind.",
  "errors": {
    "rate": [
      "Dieser Steuersatz wird bereits in Buchungen verwendet und kann nicht geändert werden."
    ]
  }
}

409 Conflict

Steuersatz löschen mit Abhängigkeiten:

{
  "message": "Dieser Steuersatz hat Buchungen. Archiviere ihn stattdessen."
}

404 Not Found

Steuersatz existiert nicht:

{
  "message": "Steuersatz nicht gefunden."
}

Best Practices

1. Archivieren statt Löschen

Empfehlung

Verwende immer die Archivierung (archived: true) statt das Löschen von Steuersätzen. Dies verhindert Probleme mit historischen Daten und ermöglicht es dir, den Steuersatz bei Bedarf wiederherzustellen.

# Empfohlen: Archivieren
curl -X PUT "https://api.milkee.ch/companies/123/tax-rates/99" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"archived": true}'

# Nicht empfohlen: Löschen (nur wenn keine Abhängigkeiten)
curl -X DELETE "https://api.milkee.ch/companies/123/tax-rates/99" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

2. Steuersätze frühzeitig planen

Erstelle Steuersätze, bevor du Buchungen, Rechnungen oder Offerten erstellst. Nachträgliche Änderungen des Steuersatzes oder Kontos sind nicht möglich.

3. Korrekte Kontowahl

Verwende immer Konten vom Typ Aktive oder Passive für Steuersätze:

• Passive: Für geschuldete MwSt (z.B. Verkaufssteuer)
• Aktive: Für Vorsteuern (z.B. Einkaufssteuer, Bezugsteuer)

4. Feldnummern für MwSt-Abrechnung

Setze korrekte field_number für die Schweizer MwSt-Abrechnung:

• 302: Normaler Steuersatz (8.1%)
• 342: Reduzierter Steuersatz (2.5%)
• 312: Sondersatz Beherbergung (3.8%)
• 381: Bezugsteuer

5. Mehrsprachigkeit nutzen

Für internationale Unternehmen: Fülle die mehrsprachigen Felder (name_en, name_fr, name_it) aus, um eine bessere Benutzererfahrung zu bieten.

Nächste Schritte

• Rechnungen API - Erstelle Rechnungen mit Steuersätzen
• Buchungen API - Verwalte Buchungen mit Steuern
• Konten API - Verwalte Steuerkonten
• Kunden API - Weise Kunden Standard-Steuersätze zu