API de Gestión del Hogar: Crea Integraciones Inteligentes con Victualia

¿Qué es una API de gestión del hogar?

Una API de gestión del hogar da a los desarrolladores acceso programático a datos de organización doméstica: inventario, planes de comidas, listas de la compra, recetas, tareas y más. En vez de construir estos sistemas desde cero, puedes integrarte con una plataforma probada y centrarte en tu caso de uso.

Victualia ofrece una API de gestión del hogar lista para producción con 74+ endpoints REST: desde inventario de despensa hasta itinerarios de viaje. Ya sea para una integración con una nevera inteligente, una skill para asistentes de voz o un panel a medida, nuestra API te da la base.

Consigue tu API key para empezar a construir hoy.

Visión general de la API

Autenticación

Todas las solicitudes requieren una API key enviada como Bearer token:

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

Las API keys están disponibles para suscriptores Premium. Genérala en Ajustes → API Keys.

Recursos principales

La API se organiza alrededor de los hogares; el resto de recursos están asociados a un hogar concreto (soporte multi‑hogar).

Homes

Los hogares son el contenedor de nivel superior. Un usuario puede tener varios hogares (segunda residencia, casa compartida, 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 (Inventario)

Registra todo lo que hay en tu hogar: despensa, nevera, congelador, productos de limpieza y más.

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

Funciones clave:

• Control por ubicación (despensa, nevera, congelador, garaje, etc.)
• Seguimiento de caducidades con alertas
• Historial de compras
• Escaneo de códigos de barras en las apps de iOS/Android
• Umbrales de stock para generar listas automáticamente

Recetas

Guarda y organiza recetas con ingredientes, información nutricional e instrucciones.

# 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

Opciones de metadatos:

• 13 tipos de cocina (italiana, mexicana, japonesa, etc.)
• Tipos de comida (desayuno, comida, cena, snack)
• 15 etiquetas dietéticas (vegetariana, vegana, sin gluten, sin lácteos, etc.)
• Dificultad (easy, medium, hard)
• Seguimiento de generación con IA (proveedor, modelo, prompt)

Planes de comidas

Planificación semanal o mensual con soporte de generación por 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

Listas de la compra

Crea y gestiona listas con seguimiento de cantidades deseadas y recogidas.

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

Funciones inteligentes:

• Lista automática de "Running Low" según umbrales de inventario
• Lista automática de "Weekly Meals" a partir de ingredientes del plan
• Seguimiento de cantidad deseada vs. recogida
• Marcar artículos mientras compras

Assets

Registra electrodomésticos, muebles y electrónica, con gestión de garantía y documentos.

# 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

Gestión de tareas del hogar con orden y seguimiento de completado.

# 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

Gestión de itinerarios con vuelos, hoteles, actividades y más.

# 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 del hogar con flujos para completar y cancelar.

# 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

Manejo de errores

Los errores devuelven una estructura JSON consistente:

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

Códigos de error:

Patrones comunes de integración

Integración con nevera inteligente

Consulta el inventario y actualiza cantidades cuando se consumen productos:

// 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 para asistente de voz

"¿Qué caduca esta semana?"

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 de la compra automatizada

Genera una lista a partir del plan de comidas actual:

// 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 especificación completa está disponible en:

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

Úsala para:

• Generar SDKs en cualquier lenguaje
• Importar en Postman o Insomnia
• Crear documentación
• Validar requests/responses

Servidor MCP para asistentes de IA

Si estás construyendo con asistentes de IA como Claude, considera usar nuestro servidor MCP en lugar de llamadas directas a la API. Ofrece una interfaz estandarizada que los modelos entienden de forma nativa.

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

Primeros pasos

1. Crea una cuenta de Victualia en Victualia
2. Suscríbete a Premium para habilitar acceso a la API
3. Genera tu API key en Ajustes → API Keys
4. Explora la API con la OpenAPI spec o los ejemplos de arriba
5. Construye algo y cuéntanos qué has creado

Preguntas frecuentes

¿Qué suscripción se requiere para acceder a la API?

El acceso a la API requiere una suscripción Premium. Incluye tanto la REST API como el servidor MCP.

¿Hay rate limits?

Sí, se aplican límites estándar para evitar abusos. Si necesitas alto volumen, contáctanos.

¿Puedo usarla en apps comerciales?

Sí. Puedes construir aplicaciones comerciales sobre la API de Victualia. Cada usuario final necesitará su propia suscripción Premium.

¿Hay un entorno sandbox?

Actualmente no ofrecemos un sandbox separado. Recomendamos crear un hogar de prueba en tu cuenta para desarrollo.

¿Cómo reporto bugs o pido funcionalidades?

Abre un issue en nuestro repositorio de GitHub o contacta soporte desde la app.

---

Artículos relacionados

• MCP Server for Home Management - Integración con asistentes de IA mediante Model Context Protocol
• Pantry Inventory App - Controla el inventario del hogar
• Family Organizer App - Organiza tu hogar en equipo

---

¿Listo para construir? Consigue tu API key y empieza a integrar la gestión del hogar en tu aplicación.