# 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

```bash
# 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
```http
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:**
```bash
curl "https://kasico.de/api/v1/products/?category=fullsuits&min_price=500&ordering=price"
```

#### Einzelnes Produkt abrufen
```http
GET /api/v1/products/{id}/
```

#### Featured Produkte
```http
GET /api/v1/products/featured/
```

#### Produkte im Angebot
```http
GET /api/v1/products/on-sale/
```

#### Produkte mit niedrigem Lagerbestand
```http
GET /api/v1/products/low-stock/
```

#### Produkt-Statistiken
```http
GET /api/v1/products/stats/
```

**Response:**
```json
{
  "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
```http
POST /api/v1/products/{id}/add-to-wishlist/
```

#### Produkt von Wunschliste entfernen
```http
POST /api/v1/products/{id}/remove-from-wishlist/
```

### Kategorien

#### Alle Kategorien abrufen
```http
GET /api/v1/categories/
```

#### Einzelne Kategorie abrufen
```http
GET /api/v1/categories/{id}/
```

#### Produkte einer Kategorie
```http
GET /api/v1/categories/{id}/products/
```

### Reviews

#### Reviews für ein Produkt abrufen
```http
GET /api/v1/reviews/?product={product_id}
```

#### Review erstellen
```http
POST /api/v1/reviews/
```

**Request Body:**
```json
{
  "product": 1,
  "rating": 5,
  "comment": "Tolles Produkt!"
}
```

#### Meine Reviews abrufen
```http
GET /api/v1/reviews/my-reviews/
```

### Wunschliste

#### Wunschliste abrufen
```http
GET /api/v1/wishlist/
```

#### Produkt zur Wunschliste hinzufügen
```http
POST /api/v1/wishlist/add-product/
```

**Request Body:**
```json
{
  "product_id": 1
}
```

#### Produkt von Wunschliste entfernen
```http
POST /api/v1/wishlist/remove-product/
```

**Request Body:**
```json
{
  "product_id": 1
}
```

### Custom Orders

#### Custom Orders abrufen
```http
GET /api/v1/custom-orders/
```

#### Custom Order erstellen
```http
POST /api/v1/custom-orders/
```

**Request Body:**
```json
{
  "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
```http
POST /api/v1/custom-orders/{id}/update-status/
```

**Request Body:**
```json
{
  "status": "in_progress"
}
```

### Galerie

#### Galerie-Bilder abrufen
```http
GET /api/v1/gallery/
```

**Parameter:**
- `is_featured` - Nur Featured (true/false)
- `fursuit_type` - Fursuit-Typ
- `style` - Stil

#### Featured Galerie-Bilder
```http
GET /api/v1/gallery/featured/
```

#### Galerie-Bilder nach Produkt
```http
GET /api/v1/gallery/by-product/?product_id={id}
```

### Warenkorb

#### Warenkorb abrufen
```http
GET /api/v1/cart/get/
```

#### Item zum Warenkorb hinzufügen
```http
POST /api/v1/cart/add-item/
```

**Request Body:**
```json
{
  "product_id": 1,
  "quantity": 2
}
```

#### Warenkorb-Menge aktualisieren
```http
POST /api/v1/cart/update-quantity/
```

**Request Body:**
```json
{
  "item_id": 1,
  "quantity": 3
}
```

#### Item aus Warenkorb entfernen
```http
POST /api/v1/cart/remove-item/
```

**Request Body:**
```json
{
  "item_id": 1
}
```

#### Warenkorb leeren
```http
POST /api/v1/cart/clear/
```

### Suche

#### Produkte suchen
```http
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:**
```bash
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
```json
{
  "count": 150,
  "next": "https://kasico.de/api/v1/products/?page=2",
  "previous": null,
  "results": [...]
}
```

### Fehler-Response
```json
{
  "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:

```javascript
// 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
```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
```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
```http
POST /api/v1/webhooks/
```

**Request Body:**
```json
{
  "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
```json
{
  "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:
- **E-Mail:** api@kasico.de
- **Dokumentation:** https://kasico.de/api/docs/
- **GitHub:** https://github.com/kasico/api-examples

## 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