thomas
/
furry
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 3 Wiki Activity
furry/docs/api_documentation.md

8.6 KiB
Raw Blame History

Kasico API Dokumentation

Übersicht

Die Kasico API ist eine RESTful API für den Fursuit Shop. Sie bietet Zugriff auf alle wichtigen Funktionen des Shops über HTTP-Endpoints.

Base URL: https://kasico.de/api/v1/

Authentication

Die API unterstützt zwei Authentifizierungsmethoden:

  1. Session Authentication (für Browser-basierte Clients)
  2. Token Authentication (für mobile Apps und externe Clients)

Token Authentication

# Token erhalten
curl -X POST https://kasico.de/api/v1/auth/token/
  -H "Content-Type: application/json"
  -d '{"username": "user", "password": "password"}'

# Token verwenden
curl -H "Authorization: Token YOUR_TOKEN" https://kasico.de/api/v1/products/

Endpoints

Produkte

Alle Produkte abrufen

GET /api/v1/products/

Parameter:

  • category - Kategorie-Slug
  • fursuit_type - Fursuit-Typ
  • style - Stil
  • min_price - Mindestpreis
  • max_price - Maximalpreis
  • on_sale - Nur Angebote (true/false)
  • is_featured - Nur Featured (true/false)
  • search - Suchbegriff
  • ordering - Sortierung (name, -name, price, -price, created, -created)
  • page - Seitennummer
  • page_size - Items pro Seite

Beispiel:

curl "https://kasico.de/api/v1/products/?category=fullsuits&min_price=500&ordering=price"

Einzelnes Produkt abrufen

GET /api/v1/products/{id}/

Featured Produkte

GET /api/v1/products/featured/

Produkte im Angebot

GET /api/v1/products/on-sale/

Produkte mit niedrigem Lagerbestand

GET /api/v1/products/low-stock/

Produkt-Statistiken

GET /api/v1/products/stats/

Response:

{
  "total_products": 150,
  "featured_products": 12,
  "on_sale_products": 8,
  "low_stock_products": 3,
  "categories_count": 5,
  "average_rating": 4.2,
  "total_reviews": 89
}

Produkt zur Wunschliste hinzufügen

POST /api/v1/products/{id}/add-to-wishlist/

Produkt von Wunschliste entfernen

POST /api/v1/products/{id}/remove-from-wishlist/

Kategorien

Alle Kategorien abrufen

GET /api/v1/categories/

Einzelne Kategorie abrufen

GET /api/v1/categories/{id}/

Produkte einer Kategorie

GET /api/v1/categories/{id}/products/

Reviews

Reviews für ein Produkt abrufen

GET /api/v1/reviews/?product={product_id}

Review erstellen

POST /api/v1/reviews/

Request Body:

{
  "product": 1,
  "rating": 5,
  "comment": "Tolles Produkt!"
}

Meine Reviews abrufen

GET /api/v1/reviews/my-reviews/

Wunschliste

Wunschliste abrufen

GET /api/v1/wishlist/

Produkt zur Wunschliste hinzufügen

POST /api/v1/wishlist/add-product/

Request Body:

{
  "product_id": 1
}

Produkt von Wunschliste entfernen

POST /api/v1/wishlist/remove-product/

Request Body:

{
  "product_id": 1
}

Custom Orders

Custom Orders abrufen

GET /api/v1/custom-orders/

Custom Order erstellen

POST /api/v1/custom-orders/

Request Body:

{
  "title": "Mein Custom Fursuit",
  "description": "Detaillierte Beschreibung...",
  "fursuit_type": "fullsuit",
  "style": "realistic",
  "size": "medium",
  "color_preferences": "Blau und Weiß",
  "special_requirements": "Besondere Anforderungen...",
  "budget": 1500.00
}

Custom Order Status aktualisieren

POST /api/v1/custom-orders/{id}/update-status/

Request Body:

{
  "status": "in_progress"
}

Galerie

Galerie-Bilder abrufen

GET /api/v1/gallery/

Parameter:

  • is_featured - Nur Featured (true/false)
  • fursuit_type - Fursuit-Typ
  • style - Stil

Featured Galerie-Bilder

GET /api/v1/gallery/featured/

Galerie-Bilder nach Produkt

GET /api/v1/gallery/by-product/?product_id={id}

Warenkorb

Warenkorb abrufen

GET /api/v1/cart/get/

Item zum Warenkorb hinzufügen

POST /api/v1/cart/add-item/

Request Body:

{
  "product_id": 1,
  "quantity": 2
}

Warenkorb-Menge aktualisieren

POST /api/v1/cart/update-quantity/

Request Body:

{
  "item_id": 1,
  "quantity": 3
}

Item aus Warenkorb entfernen

POST /api/v1/cart/remove-item/

Request Body:

{
  "item_id": 1
}

Warenkorb leeren

POST /api/v1/cart/clear/

Suche

Produkte suchen

GET /api/v1/search/products/

Parameter:

  • query - Suchbegriff
  • category - Kategorie
  • fursuit_type - Fursuit-Typ
  • style - Stil
  • min_price - Mindestpreis
  • max_price - Maximalpreis
  • on_sale - Nur Angebote
  • is_featured - Nur Featured
  • sort_by - Sortierung (newest, oldest, price_low, price_high, name, rating)
  • page - Seitennummer
  • page_size - Items pro Seite

Beispiel:

curl "https://kasico.de/api/v1/search/products/?query=wolf&min_price=300&sort_by=price_low"

Response Format

Alle API-Responses folgen diesem Format:

Erfolgreiche Response

{
  "count": 150,
  "next": "https://kasico.de/api/v1/products/?page=2",
  "previous": null,
  "results": [...]
}

Fehler-Response

{
  "error": "Fehlermeldung",
  "detail": "Detaillierte Beschreibung"
}

Rate Limiting

Die API implementiert Rate Limiting:

  • Anonyme Benutzer: 100 Requests/Stunde
  • Authentifizierte Benutzer: 1000 Requests/Stunde

Pagination

Alle Listen-Endpoints unterstützen Pagination:

  • page - Seitennummer (Standard: 1)
  • page_size - Items pro Seite (Standard: 12, Maximum: 100)

Filtering

Die API unterstützt umfangreiche Filter-Optionen:

Produkte

  • category - Nach Kategorie
  • fursuit_type - Nach Fursuit-Typ
  • style - Nach Stil
  • min_price / max_price - Preisbereich
  • on_sale - Nur Angebote
  • is_featured - Nur Featured
  • in_stock - Nur verfügbare Produkte

Suche

  • query - Volltext-Suche in Name und Beschreibung
  • Kombination aller Produkt-Filter

Sorting

Verfügbare Sortierungen:

  • newest - Neueste zuerst
  • oldest - Älteste zuerst
  • price_low - Preis aufsteigend
  • price_high - Preis absteigend
  • name - Name alphabetisch
  • rating - Bewertung absteigend

JavaScript Integration

Die API kann einfach in JavaScript verwendet werden:

// Produkte abrufen
const products = await fetch('/api/v1/products/').then(r => r.json());

// Produkt zur Wunschliste hinzufügen
await fetch('/api/v1/products/1/add-to-wishlist/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-CSRFToken': csrfToken
  }
});

// Mit dem Kasico API Client
await kasicoAPI.addToWishlist(1);
await kasicoAPI.getProducts({ category: 'fullsuits' });

SDKs und Libraries

Python

import requests

api_url = "https://kasico.de/api/v1/"
headers = {"Authorization": f"Token {token}"}

# Produkte abrufen
response = requests.get(f"{api_url}products/", headers=headers)
products = response.json()

JavaScript/TypeScript

interface Product {
  id: number;
  name: string;
  description: string;
  base_price: number;
  sale_price?: number;
  on_sale: boolean;
  stock: number;
  // ... weitere Felder
}

// Mit dem Kasico API Client
const products = await kasicoAPI.getProducts();
const featured = await kasicoAPI.getFeaturedProducts();

Webhooks

Die API unterstützt Webhooks für wichtige Events:

Verfügbare Webhooks

  • order.created - Neue Bestellung
  • order.updated - Bestellung aktualisiert
  • payment.completed - Zahlung abgeschlossen
  • stock.low - Niedriger Lagerbestand

Webhook Setup

POST /api/v1/webhooks/

Request Body:

{
  "url": "https://your-domain.com/webhook",
  "events": ["order.created", "payment.completed"]
}

Fehlerbehandlung

HTTP Status Codes

  • 200 - Erfolg
  • 201 - Erstellt
  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 429 - Too Many Requests
  • 500 - Internal Server Error

Fehler-Response Format

{
  "error": "Validation failed",
  "detail": {
    "field_name": ["Error message"]
  }
}

Versionierung

Die API verwendet URL-basierte Versionierung:

  • Aktuelle Version: v1
  • URL-Pattern: /api/v1/

Support

Bei Fragen zur API:

Changelog

v1.0.0 (2024-01-15)

  • Initiale API-Version
  • Produkt-, Kategorie- und Review-Endpoints
  • Warenkorb- und Wunschliste-Funktionen
  • Custom Order Management
  • Galerie-API
  • Such- und Filter-Funktionen