496 lines
8.6 KiB
Markdown
496 lines
8.6 KiB
Markdown
# 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 |