API Ressourcen

Die MILKEE API bietet Zugriff auf verschiedene Buchhaltungsressourcen über RESTful Endpoints. Alle Ressourcen sind firmen-spezifisch und erfordern eine gültige Authentifizierung.

Verfügbare Ressourcen

Tags

Verwalten Sie Tags für die Kategorisierung Ihrer Buchhaltungseinträge.

Endpoints:

• GET /companies/{company}/tags - Alle Tags auflisten
• POST /companies/{company}/tags - Neuen Tag erstellen
• GET /companies/{company}/tags/{tag} - Einzelnen Tag abrufen
• PUT /companies/{company}/tags/{tag} - Tag aktualisieren
• DELETE /companies/{company}/tags/{tag} - Tag löschen
• GET /companies/{company}/tags/colors - Verfügbare Farben abrufen

Customers

Verwalten Sie Ihre Geschäftskunden mit allen relevanten Informationen.

Endpoints:

• GET /companies/{company}/customers - Alle Kunden auflisten
• POST /companies/{company}/customers - Neuen Kunden erstellen
• GET /companies/{company}/customers/{customer} - Einzelnen Kunden abrufen
• PUT /companies/{company}/customers/{customer} - Kunden aktualisieren
• DELETE /companies/{company}/customers/{customer} - Kunden löschen
• GET /companies/{company}/customers/number - Nächste Kundennummer abrufen
• GET /companies/{company}/customers/{customer}/statistics - Kundenstatistiken
• PUT /companies/{company}/customers/multiple - Mehrere Kunden aktualisieren
• DELETE /companies/{company}/customers/multiple - Mehrere Kunden löschen
• POST /companies/{company}/customers/import - Kunden aus CSV importieren

URL-Struktur

Alle API-Endpoints folgen einem konsistenten URL-Schema:

https://app.milkee.ch/api/v2/companies/{company}/{resource}

Parameter

• {company}: Ihre Firmen-ID (numerisch)
• {resource}: Name der Ressource (z.B. tags, customers, invoices)

Standard-Operationen

Die meisten Ressourcen unterstützen CRUD-Operationen (Create, Read, Update, Delete):

HTTP-Verb	Aktion	URL-Muster
GET	Liste abrufen	/companies/{company}/{resource}
POST	Erstellen	/companies/{company}/{resource}
GET	Einzeln abrufen	/companies/{company}/{resource}/{id}
PUT	Aktualisieren	/companies/{company}/{resource}/{id}
DELETE	Löschen	/companies/{company}/{resource}/{id}

Request/Response-Format

Content-Type

Alle Requests und Responses verwenden JSON:

Content-Type: application/json
Accept: application/json

Authentifizierung

Jeder Request erfordert einen Bearer Token:

Authorization: Bearer abcdef123456789...

Standard-Response-Struktur

Einzelne Ressource

{
  "id": 1,
  "name": "beispiel",
  "created_at": "2024-01-15T10:30:00.000000Z",
  "updated_at": "2024-01-15T10:30:00.000000Z"
}

Ressourcen-Liste

{
  "data": [
    {
      "id": 1,
      "name": "beispiel1"
    },
    {
      "id": 2,
      "name": "beispiel2"
    }
  ],
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "..."
  },
  "meta": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 15,
    "total": 67
  }
}

Validierung

Validation-Regeln

Jede Ressource hat spezifische Validierungsregeln für ihre Felder. Häufige Regeln sind:

• required: Feld ist erforderlich
• max:n: Maximale Länge/Wert
• min:n: Minimale Länge/Wert
• unique: Eindeutigkeit (meist pro Firma)
• email: Gültige E-Mail-Adresse
• url: Gültige URL

Validation-Errors

Bei Validierungsfehlern erhalten Sie eine 422-Antwort:

{
  "message": "The given data was invalid.",
  "errors": {
    "field_name": [
      "The field name is required.",
      "The field name must be unique."
    ]
  }
}

Rate Limiting

Alle Ressourcen unterliegen den gleichen Rate Limits:

• 120 Requests pro Minute und IP Adresse

Pagination

Listen-Endpoints verwenden Pagination mit folgenden Standard-Parametern:

• page: Seitennummer (Standard: 1)
• per_page: Elemente pro Seite (Standard: 15, Max: 100)

Fehlerbehandlung

Alle Ressourcen verwenden standardisierte HTTP-Status-Codes und Fehlerformate:

• 401: Authentifizierung fehlgeschlagen
• 403: Keine Berechtigung
• 404: Ressource nicht gefunden
• 422: Validierung fehlgeschlagen
• 429: Rate Limit überschritten

Best Practices

Effiziente API-Nutzung

1. Caching implementieren: Cachen Sie API-Responses lokal
2. Pagination nutzen: Verwenden Sie angemessene per_page-Werte
3. Rate Limits beachten: Monitoren Sie Ihre Request-Frequenz
4. Fehlerbehandlung: Implementieren Sie robuste Fehlerbehandlung

Sicherheit

1. HTTPS verwenden: Alle Requests über HTTPS senden
2. Tokens sicher verwahren: API-Tokens niemals öffentlich teilen
3. Minimaler Zugriff: Verwenden Sie separate Tokens für verschiedene Anwendungen
4. Token-Rotation: Erneuern Sie Tokens regelmässig

Nächste Schritte

• Tags API erkunden
• Authentifizierung einrichten
• Code-Beispiele ansehen