API de Gestion du Foyer : Créez des Intégrations Smart Home avec Victualia

Qu'est-ce qu'une API de gestion du foyer ?

Une API de gestion du foyer donne aux développeurs un accès programmatique aux données d'organisation à la maison : inventaire, plans de repas, listes de courses, recettes, tâches, etc. Plutôt que de reconstruire ces systèmes de zéro, vous pouvez vous intégrer à une plateforme éprouvée et vous concentrer sur votre cas d'usage.

Victualia propose une API de gestion du foyer prête pour la production avec plus de 74 endpoints REST : de l'inventaire du garde-manger jusqu'aux itinéraires de voyage. Que vous construisiez une intégration de frigo connecté, une skill d'assistant vocal ou un tableau de bord sur mesure, notre API vous fournit la base.

Obtenez votre clé API pour commencer à construire dès aujourd'hui.

Vue d'ensemble de l'API

Authentification

Toutes les requêtes nécessitent une clé API transmise en Bearer token :

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

Les clés API sont disponibles pour les abonnés Premium. Générez la vôtre dans Paramètres → API Keys.

Ressources principales

L'API est organisée autour des foyers ; toutes les autres ressources sont rattachées à un foyer spécifique (support multi‑foyers).

Homes

Les foyers sont le conteneur de plus haut niveau. Un utilisateur peut avoir plusieurs foyers (résidence secondaire, colocation, etc.).

# List all homes
GET /homes

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

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

Items (Inventaire)

Suivez tout ce qu'il y a dans votre foyer : garde‑manger, réfrigérateur, congélateur, produits ménagers, etc.

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

Fonctionnalités clés :

• Suivi par emplacement (placards, frigo, congélateur, garage, etc.)
• Dates de péremption avec alertes
• Historique d'achats
• Scan de code‑barres dans les apps iOS/Android
• Seuils de stock bas pour générer des listes de courses

Recettes

Stockez et organisez des recettes avec ingrédients, infos nutritionnelles et étapes.

# 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

Métadonnées recettes :

• 13 types de cuisine (italienne, mexicaine, japonaise, etc.)
• Types de repas (petit‑déjeuner, déjeuner, dîner, collation)
• 15 tags alimentaires (végétarien, vegan, sans gluten, sans lactose, etc.)
• Difficulté (easy, medium, hard)
• Traçabilité IA (fournisseur, modèle, prompt)

Plans de repas

Planification hebdomadaire ou mensuelle avec génération par IA.

# 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

Listes de courses

Créez et gérez des listes avec suivi des quantités souhaitées et collectées.

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

Listes intelligentes :

• Liste "Running Low" générée à partir des seuils d'inventaire
• Liste "Weekly Meals" générée à partir des ingrédients des plans de repas
• Suivi collected vs. desired quantity
• Cocher les articles pendant les courses

Assets

Suivez appareils, meubles, électronique, avec gestion des garanties et documents.

# 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

Gestion des tâches du foyer avec ordonnancement et suivi de complétion.

# 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

Gestion d'itinéraires de voyage (vols, hôtels, activités, etc.).

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

Calendrier du foyer avec workflows de complétion et d'annulation.

# 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

Gestion des erreurs

Toutes les erreurs renvoient une structure JSON cohérente :

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

Codes d'erreur :

Modèles d'intégration courants

Intégration de frigo connecté

Interroger l'inventaire et mettre à jour les quantités au fur et à mesure :

// 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 d'assistant vocal

"Qu'est‑ce qui périme cette semaine ?"

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

Liste de courses automatisée

Générer une liste de courses à partir du plan de repas actuel :

// 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 spécification complète est disponible ici :

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

Elle permet de :

• Générer des SDKs clients dans n'importe quel langage
• Importer dans Postman ou Insomnia
• Construire de la documentation
• Valider requests/responses

Serveur MCP pour assistants IA

Si vous développez avec des assistants IA comme Claude, pensez à utiliser notre serveur MCP plutôt que des appels API directs. Il fournit une interface standardisée que les modèles comprennent nativement.

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

Bien démarrer

1. Créez un compte Victualia sur Victualia
2. Abonnez-vous à Premium pour activer l'accès API
3. Générez votre clé API dans Paramètres → API Keys
4. Explorez l'API via l'OpenAPI spec ou les exemples ci-dessus
5. Construisez quelque chose et dites‑nous ce que vous avez créé

Foire aux questions

Quel abonnement est nécessaire pour accéder à l'API ?

L'accès à l'API nécessite un abonnement Premium. Cela inclut la REST API et le serveur MCP.

Y a-t-il une limite de débit (rate limit) ?

Oui, des limites standard s'appliquent pour éviter les abus. Pour des intégrations à fort volume, contactez‑nous.

Puis-je l'utiliser pour une application commerciale ?

Oui. Vous pouvez construire des applications commerciales sur l'API Victualia. Chaque utilisateur final aura besoin de son propre abonnement Premium.

Existe-t-il un environnement sandbox ?

Pour le moment, nous n'offrons pas de sandbox séparée. Nous recommandons de créer un foyer de test dans votre compte pour le développement.

Comment signaler un bug ou demander une fonctionnalité ?

Ouvrez une issue sur notre dépôt GitHub ou contactez le support via l'app.

---

Articles connexes

• MCP Server for Home Management - Intégration d'assistants IA via Model Context Protocol
• Pantry Inventory App - Suivre l'inventaire du foyer
• Family Organizer App - Organiser le foyer à plusieurs

---

Prêt à construire ? Obtenez votre clé API et commencez à intégrer la gestion du foyer dans votre application.