Tags API

Tags ermöglichen es Ihnen, Buchhaltungseinträge zu kategorisieren und zu organisieren. Jeder Tag hat einen Namen und eine Farbe für die visuelle Unterscheidung.

Tag-Objekt

{
  "id": 1,
  "name": "reisekosten",
  "color": "blue",
  "company_id": 123,
  "user_id": 456
}

Attribute

Feld	Typ	Beschreibung
id	integer	Eindeutige Tag-ID
name	string	Tag-Name (automatisch in Kleinbuchstaben konvertiert)
color	string	Tag-Farbe (siehe verfügbare Farben)
company_id	integer	ID der zugehörigen Firma
user_id	integer	ID des Benutzers, der den Tag erstellt hat

Endpoints

Alle Tags auflisten

GET /companies/{company}/tags

Ruft eine paginierte Liste aller Tags der Firma ab.

Parameter

Parameter	Typ	Standard	Beschreibung
page	integer	1	Seitennummer
per_page	integer	15	Anzahl Tags pro Seite (max. 100)

Response

{
  "data": [
    {
      "id": 1,
      "name": "reisekosten",
      "color": "blue",
      "company_id": 123,
      "user_id": 456
    },
    {
      "id": 2,
      "name": "büromaterial",
      "color": "green",
      "company_id": 123,
      "user_id": 456
    }
  ],
  "links": {
    "first": "https://app.milkee.ch/api/v2/companies/123/tags?page=1",
    "last": "https://app.milkee.ch/api/v2/companies/123/tags?page=3",
    "prev": null,
    "next": "https://app.milkee.ch/api/v2/companies/123/tags?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 3,
    "path": "https://app.milkee.ch/api/v2/companies/123/tags",
    "per_page": 15,
    "to": 15,
    "total": 37
  }
}

Beispiel

curl -H "Authorization: Bearer abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/tags"

Neuen Tag erstellen

POST /companies/{company}/tags

Erstellt einen neuen Tag für die angegebene Firma.

Request Body

{
  "name": "marketing",
  "color": "purple"
}

Validierung

Feld	Regeln
name	required, string, max:255, unique (pro Firma)
color	required, gültiger Farbwert

Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 15,
  "name": "marketing",
  "color": "purple",
  "company_id": 123,
  "user_id": 456
}

Beispiel

curl -X POST \
     -H "Authorization: Bearer abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{"name":"marketing","color":"purple"}' \
     "https://app.milkee.ch/api/v2/companies/123/tags"

Einzelnen Tag abrufen

GET /companies/{company}/tags/{tag}

Ruft die Details eines spezifischen Tags ab.

Parameter

Parameter	Typ	Beschreibung
company	integer	Firmen-ID
tag	integer	Tag-ID

Response

{
  "id": 1,
  "name": "reisekosten",
  "color": "blue",
  "company_id": 123,
  "user_id": 456
}

Beispiel

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

Tag aktualisieren

PUT /companies/{company}/tags/{tag}

Aktualisiert einen bestehenden Tag.

Request Body

{
  "name": "reisekosten-2024",
  "color": "red"
}

Validierung

Feld	Regeln
name	required, string, max:255, unique (pro Firma, ausser aktueller Tag)
color	required, gültiger Farbwert

Response

{
  "id": 1,
  "name": "reisekosten-2024",
  "color": "red",
  "company_id": 123,
  "user_id": 456
}

Beispiel

curl -X PUT \
     -H "Authorization: Bearer abcdef123456789..." \
     -H "Content-Type: application/json" \
     -d '{"name":"reisekosten-2024","color":"red"}' \
     "https://app.milkee.ch/api/v2/companies/123/tags/1"

Tag löschen

DELETE /companies/{company}/tags/{tag}

Löscht einen bestehenden Tag unwiderruflich.

Unwiderruflich

Das Löschen eines Tags kann nicht rückgängig gemacht werden. Stellen Sie sicher, dass der Tag nicht mehr benötigt wird.

Response

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

{
  "message": "Tag deleted successfully"
}

Beispiel

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

Verfügbare Farben abrufen

GET /companies/{company}/tags/colors

Ruft alle verfügbaren Tag-Farben ab.

Response

[
  "orange",
  "blue", 
  "lime",
  "yellow",
  "turquoise",
  "marine",
  "purple",
  "pink",
  "green",
  "red",
  "gray"
]

Beispiel

curl -H "Authorization: Bearer abcdef123456789..." \
     "https://app.milkee.ch/api/v2/companies/123/tags/colors"

Verfügbare Farben

Tags können eine der folgenden Farben haben:

Farbe	Hex-Code	Verwendung
orange	#ff6b35	Warnung, wichtige Ausgaben
blue	#007bff	Standard, allgemeine Kategorien
lime	#32cd32	Umwelt, nachhaltige Ausgaben
yellow	#ffc107	Aufmerksamkeit, zu prüfende Ausgaben
turquoise	#20c997	Reisen, externe Kosten
marine	#495057	Offiziell, behördliche Ausgaben
purple	#6f42c1	Marketing, kreative Ausgaben
pink	#e83e8c	Events, soziale Ausgaben
green	#28a745	Erfolg, profitable Kategorien
red	#dc3545	Fehler, dringende Ausgaben
gray	#6c757d	Archiv, inaktive Kategorien

Webhooks

Die Tags-API unterstützt Webhooks für folgende Events:

tag.created

Wird ausgelöst, wenn ein neuer Tag erstellt wird.

{
  "event": "tag.created",
  "data": {
    "id": 15,
    "name": "marketing",
    "color": "purple",
    "company_id": 123,
    "user_id": 456
  }
}

tag.updated

Wird ausgelöst, wenn ein Tag aktualisiert wird.

{
  "event": "tag.updated", 
  "data": {
    "id": 1,
    "name": "reisekosten-2024",
    "color": "red",
    "company_id": 123,
    "user_id": 456
  }
}

tag.deleted

Wird ausgelöst, wenn ein Tag gelöscht wird.

{
  "event": "tag.deleted",
  "data": {
    "id": 1,
    "name": "reisekosten-2024",
    "color": "red", 
    "company_id": 123,
    "user_id": 456
  }
}

Mehr Informationen zu Webhooks finden Sie in der Webhooks-Dokumentation.

Fehlerbehandlung

Häufige Fehler

404 Not Found

{
  "message": "No query results for model [App\\Models\\Tag] 999"
}

Ursache: Tag mit der angegebenen ID existiert nicht oder gehört nicht zur angegebenen Firma.

422 Validation Error

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name has already been taken."
    ],
    "color": [
      "The selected color is invalid."
    ]
  }
}

Mögliche name-Fehler:

• required: Name ist erforderlich
• max:255: Name zu lang (maximal 255 Zeichen)
• unique: Name bereits in dieser Firma vorhanden

Mögliche color-Fehler:

• required: Farbe ist erforderlich
• invalid: Ungültige Farbe (muss eine der verfügbaren Farben sein)

Best Practices

Tag-Naming

• Kleinschreibung: Namen werden automatisch in Kleinbuchstaben konvertiert
• Konsistenz: Verwenden Sie einheitliche Benennungskonventionen
• Präfixe: Nutzen Sie Präfixe für Kategorien (z.B. "ausgaben-", "projekt-")
• Kürze: Kurze, prägnante Namen sind besser lesbar

// Gut
{
  "name": "reisekosten-2024",
  "color": "blue"
}

// Weniger gut
{
  "name": "Reisekosten für das Jahr 2024 und alle damit verbundenen Ausgaben",
  "color": "blue"
}

Farb-Systematik

Entwickeln Sie eine konsistente Farb-Systematik:

// Beispiel-Systematik
{
  "ausgaben-büro": "blue",      // Standard-Ausgaben
  "ausgaben-reise": "turquoise", // Reise-bezogen
  "ausgaben-marketing": "purple", // Marketing
  "ausgaben-dringend": "red",     // Dringend zu prüfen
  "einnahmen": "green"            // Einnahmen
}

Performance

• Caching: Cachen Sie die Tag-Liste lokal
• Batch-Erstellung: Erstellen Sie mehrere Tags mit kurzen Pausen
• Farben-Cache: Cachen Sie die verfügbaren Farben (ändern sich selten)

Nächste Schritte

• Code-Beispiele ansehen
• Webhooks einrichten
• Testing durchführen