API di Gestione della Casa: Crea Integrazioni Smart Home con Victualia

Cos'è una API di gestione della casa?

Una API di gestione della casa offre agli sviluppatori accesso programmatico ai dati di organizzazione domestica: inventario, piani pasti, liste della spesa, ricette, compiti e altro. Invece di costruire tutto da zero, puoi integrare una piattaforma collaudata e concentrarti sul tuo caso d'uso.

Victualia offre una API di gestione della casa pronta per la produzione con oltre 74 endpoint REST: dall'inventario della dispensa fino agli itinerari di viaggio. Che tu stia creando un'integrazione per un frigorifero smart, una skill per assistenti vocali o una dashboard personalizzata, la nostra API e' la base.

Ottieni la tua API key per iniziare a costruire oggi.

Panoramica API

Autenticazione

Tutte le richieste richiedono una API key passata come Bearer token:

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

Le API key sono disponibili per gli abbonati Premium. Generala in Impostazioni → API Keys.

Risorse principali

L'API e' organizzata attorno alle case; tutte le altre risorse sono legate a una casa specifica (supporto multi‑casa).

Homes

Le case sono il contenitore di livello superiore. Un utente puo' avere piu' case (casa vacanze, abitazione condivisa, ecc.).

# List all homes
GET /homes

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

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

Items (Inventario)

Tieni traccia di tutto in casa: dispensa, frigo, freezer, prodotti per la pulizia e altro.

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

Funzionalita' principali:

• Tracciamento per posizione (dispensa, frigo, freezer, garage, ecc.)
• Scadenze con avvisi
• Storico acquisti
• Scansione barcode nelle app iOS/Android
• Soglie di scorta bassa per generare liste automaticamente

Ricette

Salva e organizza ricette con ingredienti, valori nutrizionali e istruzioni.

# 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

Metadati ricetta:

• 13 cucine (italiana, messicana, giapponese, ecc.)
• Tipi pasto (colazione, pranzo, cena, snack)
• 15 tag dietetici (vegetariano, vegano, senza glutine, senza lattosio, ecc.)
• Difficolta' (easy, medium, hard)
• Tracciamento generazione AI (provider, modello, prompt)

Piani pasti

Pianificazione settimanale o mensile con supporto alla generazione AI.

# 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

Liste della spesa

Crea e gestisci liste con tracciamento di quantita' desiderate e raccolte.

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

Liste smart:

• Lista "Running Low" generata dalle soglie inventario
• Lista "Weekly Meals" generata dagli ingredienti del piano pasti
• Tracciamento collected vs. desired quantity
• Spunta elementi mentre fai la spesa

Assets

Tieni traccia di elettrodomestici, mobili ed elettronica, con gestione garanzie e documenti.

# 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

Gestione dei compiti domestici con ordinamento e completamento.

# 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

Gestione itinerari di viaggio con voli, hotel, attivita' e altro.

# 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 (Calendario)

Calendario della casa con workflow di completamento e annullamento.

# 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

Gestione errori

Gli errori restituiscono una struttura JSON coerente:

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

Codici errore:

Pattern comuni di integrazione

Integrazione frigo smart

Interroga l'inventario e aggiorna le quantita' quando si consumano gli articoli:

// 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 })
});

Skill per assistente vocale

"Cosa scade questa settimana?"

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;
});

Lista della spesa automatizzata

Genera una lista dal piano pasti corrente:

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

La specifica completa e' disponibile qui:

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

Usala per:

• Generare SDK client in qualsiasi linguaggio
• Importare in Postman o Insomnia
• Costruire documentazione
• Validare requests/responses

MCP server per assistenti AI

Se stai costruendo con assistenti AI come Claude, valuta l'uso del nostro MCP server al posto di chiamate API dirette. Fornisce un'interfaccia standardizzata che i modelli comprendono nativamente.

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

Come iniziare

1. Crea un account Victualia su Victualia
2. Abbonati a Premium per abilitare l'accesso API
3. Genera la tua API key in Impostazioni → API Keys
4. Esplora l'API tramite la OpenAPI spec o gli esempi sopra
5. Costruisci qualcosa e facci sapere cosa hai creato

Domande frequenti

Quale abbonamento serve per l'accesso API?

L'accesso API richiede un abbonamento Premium. Include sia la REST API sia l'MCP server.

C'e' un rate limit?

Si, si applicano limiti standard per prevenire abusi. Per integrazioni ad alto volume, contattaci.

Posso usarla per applicazioni commerciali?

Si. Puoi costruire applicazioni commerciali sopra la API di Victualia. Ogni utente finale dovra' avere un proprio abbonamento Premium.

Esiste un ambiente sandbox?

Al momento non offriamo una sandbox separata. Consigliamo di creare una casa di test nel tuo account.

Come segnalo bug o richiedo funzionalita'?

Apri un'issue nel nostro repository GitHub o contatta il supporto dall'app.

---

Articoli correlati

• MCP Server for Home Management - Integrazione con assistenti AI via Model Context Protocol
• Pantry Inventory App - Tieni traccia dell'inventario di casa
• Family Organizer App - Organizza la casa insieme

---

Pronto a costruire? Ottieni la tua API key e inizia a integrare la gestione domestica nella tua applicazione.