Haushaltsmanagement-API: Smarte Integrationen mit Victualia bauen

Was ist eine Haushaltsmanagement-API?

Eine Haushaltsmanagement-API gibt Entwicklern programmgesteuerten Zugriff auf Daten rund um die Organisation zu Hause: Bestandsverwaltung, Essensplaene, Einkaufslisten, Rezepte, Aufgaben und mehr. Anstatt diese Systeme von Grund auf selbst zu bauen, koennen Sie eine bewaehrte Plattform integrieren und sich auf Ihren konkreten Use Case konzentrieren.

Victualia bietet eine produktionsreife Haushaltsmanagement-API mit 74+ REST-Endpunkten – von Vorrats-Tracking bis zu Reiseplaenen. Ob Smart-Fridge-Integration, Voice-Assistant-Skill oder ein eigenes Dashboard: Unsere API liefert das Fundament.

API-Key erstellen und sofort loslegen.

API-Ueberblick

Authentifizierung

Alle Requests benoetigen einen API-Key als Bearer Token:

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://www.victualia.app/api/v1/homes

API-Keys sind fuer Premium-Abonnenten verfuegbar. Sie koennen Ihren Key unter Einstellungen → API Keys erstellen.

Core Resources

Die API ist um Homes herum organisiert – alle weiteren Ressourcen sind an ein bestimmtes Home gebunden (Multi-Property-Unterstuetzung).

Homes

Homes sind der oberste Container. Ein Nutzer kann mehrere Homes haben (Ferienhaus, gemeinsamer Haushalt usw.).

# List all homes
GET /homes

# Create a new home
POST /homes
{
  "name": "Beach House",
  "measurementSystem": "metric"
}

# Get a specific home
GET /homes/{homeId}

Items (Inventar)

Tracken Sie alles in Ihrem Haushalt – Vorratsartikel, Kuehlschrankinhalte, Tiefkuehlware, Reinigungsmittel und mehr.

# List all items in a home
GET /homes/{homeId}/items

# Add a new item
POST /homes/{homeId}/items
{
  "name": "Olive Oil",
  "location": "pantry",
  "quantity": 1,
  "unit": "bottle",
  "expirationDate": "2026-06-15"
}

# Update quantity (e.g., after using some)
PATCH /homes/{homeId}/items/{id}/quantity
{
  "quantity": 0.5
}

Wichtige Funktionen:

• Items nach Ort organisieren (Vorrat, Kuehlschrank, Gefrierfach, Garage, ...)
• Haltbarkeitsdaten mit Benachrichtigungen
• Kaufhistorie
• Barcode-Scan in den iOS/Android-Apps
• Mindestbestaende fuer automatische Einkaufslisten

Rezepte

Rezepte mit Zutatenlisten, Naehrwerten und Kochanleitungen speichern und organisieren.

# List recipes
GET /homes/{homeId}/recipes

# Get recipe gallery (with images)
GET /homes/{homeId}/recipes/gallery

# Create a recipe
POST /homes/{homeId}/recipes
{
  "name": "Pasta Carbonara",
  "servings": 4,
  "prepTime": 10,
  "cookTime": 20,
  "difficulty": "medium",
  "ingredients": [...],
  "steps": [...]
}

# Generate shopping list from recipe
POST /homes/{homeId}/recipes/{id}/shopping-lists

Rezept-Metadaten:

• 13 Cuisine-Typen (Italienisch, Mexikanisch, Japanisch, ...)
• Meal Types (Fruehstueck, Mittagessen, Abendessen, Snack)
• 15 Ernaehrungs-Tags (vegetarisch, vegan, glutenfrei, laktosefrei, ...)
• Schwierigkeitsgrade (easy, medium, hard)
• AI-Generation-Tracking (Provider, Modell, Prompt)

Essensplaene

Woechentliche oder monatliche Essensplanung mit AI-Generierung.

# List meal plans
GET /homes/{homeId}/meal-plans

# Create a meal plan
POST /homes/{homeId}/meal-plans
{
  "name": "Week of Jan 20",
  "startDate": "2026-01-20",
  "endDate": "2026-01-26"
}

# Add a meal to a slot
POST /homes/{homeId}/meal-plans/{id}/slots
{
  "date": "2026-01-20",
  "mealType": "dinner",
  "recipeId": "recipe_abc123"
}

# Accept AI-generated meal plan
POST /homes/{homeId}/meal-plans/{id}/accept

Einkaufslisten

Einkaufslisten erstellen und verwalten – inklusive "gekauft" vs. "benoetigt".

# List shopping lists
GET /homes/{homeId}/shopping-lists

# Create a shopping list
POST /homes/{homeId}/shopping-lists
{
  "name": "Weekly Groceries"
}

# Add item to list
POST /homes/{homeId}/shopping-lists/{id}/items
{
  "name": "Milk",
  "quantity": 2,
  "unit": "liters"
}

# Mark item as collected
PATCH /homes/{homeId}/shopping-lists/{id}/items/{itemId}/quantity
{
  "collectedQuantity": 2
}

Smarte Listen:

• Automatische "Running Low"-Liste aus Mindestbestaenden
• Automatische "Weekly Meals"-Liste aus Essensplaenen
• Tracking: collected vs. desired quantity
• Items beim Einkaufen abhaekbar

Assets

Geraete, Moebel, Elektronik tracken – inkl. Garantie- und Dokumentenverwaltung.

# List assets
GET /homes/{homeId}/assets

# Create an asset
POST /homes/{homeId}/assets
{
  "name": "Dishwasher",
  "brand": "Bosch",
  "model": "SMS46GI01E",
  "purchaseDate": "2024-03-15",
  "warrantyExpiration": "2027-03-15",
  "location": "kitchen"
}

# Attach a document (warranty, manual, receipt)
POST /homes/{homeId}/assets/{id}/documents
{
  "name": "Warranty Certificate",
  "type": "warranty",
  "url": "https://..."
}

Task Lists & Tasks

Aufgabenverwaltung mit Sortierung und Completion-Tracking.

# List task lists
GET /homes/{homeId}/task-lists

# Create a task
POST /homes/{homeId}/task-lists/{listId}/tasks
{
  "title": "Clean gutters",
  "dueDate": "2026-02-01"
}

# Reorder tasks
POST /homes/{homeId}/task-lists/{listId}/tasks/{taskId}/reorder
{
  "position": 1
}

Trips

Reiseplaene verwalten (Fluege, Hotels, Aktivitaeten, ...).

# List trips
GET /homes/{homeId}/trips

# Create a trip
POST /homes/{homeId}/trips
{
  "name": "Paris Vacation",
  "startDate": "2026-05-01",
  "endDate": "2026-05-08",
  "destination": "Paris, France"
}

# Add a flight
POST /homes/{homeId}/trips/{tripId}/items
{
  "type": "flight",
  "title": "Outbound Flight",
  "startTime": "2026-05-01T08:00:00Z",
  "confirmationNumber": "ABC123"
}

Events (Kalender)

Haushaltskalender mit Workflows fuer "complete" und "cancel".

# List events
GET /homes/{homeId}/events?start=2026-01-01&end=2026-01-31

# Create an event
POST /homes/{homeId}/events
{
  "title": "Dentist Appointment",
  "startTime": "2026-01-25T14:00:00Z",
  "endTime": "2026-01-25T15:00:00Z"
}

# Mark event as complete
POST /homes/{homeId}/events/{id}/complete

Fehlerbehandlung

Alle Errors liefern eine konsistente JSON-Struktur:

{
  "error": {
    "code": "not-found",
    "message": "Item not found"
  }
}

Error Codes:

Hauefige Integrationsmuster

Smart-Fridge-Integration

Inventar abfragen und Mengen aktualisieren, wenn Items verbraucht werden:

// Check what's in the fridge
const items = await fetch('/homes/{homeId}/items?location=fridge')
  .then(r => r.json());

// Update quantity when item is removed
await fetch('/homes/{homeId}/items/{id}/quantity', {
  method: 'PATCH',
  body: JSON.stringify({ quantity: newQuantity })
});

Voice-Assistant-Skill

"Was laeuft diese Woche ab?"

const items = await fetch('/homes/{homeId}/items')
  .then(r => r.json());

const expiringThisWeek = items.filter(item => {
  const expiry = new Date(item.expirationDate);
  const weekFromNow = new Date();
  weekFromNow.setDate(weekFromNow.getDate() + 7);
  return expiry <= weekFromNow;
});

Automatisierte Einkaufsliste

Einkaufsliste aus dem aktuellen Essensplan generieren:

// Get active meal plan
const mealPlans = await fetch('/homes/{homeId}/meal-plans').then(r => r.json());
const activePlan = mealPlans[0];

// Get entries with recipe details
const entries = await fetch(`/homes/{homeId}/meal-plans/${activePlan.id}/entries`)
  .then(r => r.json());

// Create shopping list from recipes
for (const entry of entries) {
  if (entry.recipeId) {
    await fetch(`/homes/{homeId}/recipes/${entry.recipeId}/shopping-lists`, {
      method: 'POST'
    });
  }
}

OpenAPI Specification

Die vollstaendige Spezifikation finden Sie hier:

https://www.victualia.app/api/v1/openapi.json

Damit koennen Sie:

• Client-SDKs in beliebigen Sprachen generieren
• In Postman oder Insomnia importieren
• Dokumentation bauen
• Requests/Responses validieren

MCP-Server fuer AI Assistants

Wenn Sie mit AI Assistants wie Claude arbeiten, nutzen Sie ggf. unseren MCP-Server statt direkter API-Calls. Er bietet eine standardisierte Schnittstelle, die AI-Modelle nativ verstehen.

{
  "mcpServers": {
    "victualia": {
      "command": "npx",
      "args": ["-y", "victualia-mcp"],
      "env": {
        "VICTUALIA_API_KEY": "your-api-key"
      }
    }
  }
}

Getting Started

1. Victualia Account erstellen unter Victualia
2. Premium abonnieren, um API-Zugriff zu aktivieren
3. API-Key erzeugen in Einstellungen → API Keys
4. API erkunden ueber die OpenAPI Spec oder die Beispiele oben
5. Etwas bauen und uns zeigen, was Sie erstellt haben

Hauefig gestellte Fragen

Welches Abo brauche ich fuer API-Zugriff?

API-Zugriff setzt ein Premium-Abo voraus. Das gilt sowohl fuer die REST API als auch fuer den MCP-Server.

Gibt es ein Rate Limit?

Ja, Standard-Limits gelten zum Schutz vor Missbrauch. Fuer High-Volume-Integrationen kontaktieren Sie uns bitte.

Darf ich das kommerziell nutzen?

Ja. Sie koennen kommerzielle Anwendungen auf Basis der Victualia API bauen. Jeder Endnutzer benoetigt ein eigenes Victualia Premium-Abo.

Gibt es eine Sandbox?

Aktuell bieten wir keine separate Sandbox. Fuer Entwicklung empfehlen wir ein Test-Home in Ihrem Account.

Wie melde ich Bugs oder Feature-Wuensche?

Erstellen Sie ein Issue in unserem GitHub-Repository oder kontaktieren Sie den Support in der App.

---

Verwandte Artikel

• MCP Server for Home Management - AI-Assistant-Integration via Model Context Protocol
• Pantry Inventory App - Haushaltsinventar tracken
• Family Organizer App - Haushalt gemeinsam organisieren

---

Bereit zu bauen? API-Key erstellen und Haushaltsmanagement in Ihre App integrieren.