API de Gestão da Casa: Crie Integrações de Smart Home com a Victualia

O que é uma API de gestão da casa?

Uma API de gestão da casa dá aos developers acesso programático a dados de organização do lar: inventário, planos de refeições, listas de compras, receitas, tarefas e muito mais. Em vez de construir estes sistemas do zero, pode integrar uma plataforma comprovada e focar-se no seu caso de uso.

A Victualia oferece uma API de gestão da casa pronta para produção com mais de 74 endpoints REST: desde inventário da despensa até itinerários de viagem. Quer esteja a criar uma integração com um frigorífico inteligente, uma skill de assistente de voz ou um dashboard personalizado, a nossa API dá-lhe a base.

Obtenha a sua API key para começar a construir hoje.

Visão geral da API

Autenticação

Todos os pedidos exigem uma API key enviada como Bearer token:

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

As API keys estão disponíveis para subscritores Premium. Gere a sua em Definições → API Keys.

Recursos principais

A API é organizada em torno das casas; os restantes recursos são associados a uma casa específica (suporte multi‑casa).

Homes

As casas são o contentor de nível superior. Um utilizador pode ter várias casas (casa de férias, casa partilhada, 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 (Inventário)

Acompanhe tudo o que existe na sua casa: despensa, frigorífico, congelador, produtos de limpeza e mais.

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

Funcionalidades chave:

• Inventário por localização (despensa, frigorífico, congelador, garagem, etc.)
• Datas de validade com alertas
• Histórico de compras
• Leitura de código de barras nas apps iOS/Android
• Limiares de stock baixo para gerar listas de compras

Receitas

Guarde e organize receitas com ingredientes, informação nutricional e instruções.

# 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

Metadados de receitas:

• 13 tipos de cozinha (italiana, mexicana, japonesa, etc.)
• Tipos de refeição (pequeno‑almoço, almoço, jantar, snack)
• 15 tags alimentares (vegetariana, vegan, sem glúten, sem lactose, etc.)
• Dificuldade (easy, medium, hard)
• Registo de geração por IA (provider, modelo, prompt)

Planos de refeições

Planeamento semanal ou mensal com suporte de geração 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 compras

Crie e gira listas com controlo de quantidades desejadas e recolhidas.

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

Listas inteligentes:

• Lista "Running Low" gerada a partir de limiares de inventário
• Lista "Weekly Meals" gerada a partir de ingredientes do plano
• Controlo collected vs. desired quantity
• Riscar itens enquanto faz compras

Assets

Registe eletrodomésticos, mobiliário e eletrónica, com gestão de garantia e 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

Gestão de tarefas do lar com ordenação e acompanhamento de conclusão.

# 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

Gestão de itinerários com voos, hotéis, atividades e mais.

# 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 (Calendário)

Calendário do lar com workflows de conclusão e cancelamento.

# 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

Tratamento de erros

Todos os erros devolvem uma estrutura JSON consistente:

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

Códigos de erro:

Padrões comuns de integração

Integração com frigorífico inteligente

Consultar inventário e atualizar quantidades à medida que os itens são usados:

// 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 de assistente de voz

"O que expira 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 compras automatizada

Gerar uma lista de compras a partir do plano de refeições atual:

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

A especificação completa está disponível em:

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

Use-a para:

• Gerar SDKs em qualquer linguagem
• Importar para Postman ou Insomnia
• Construir documentação
• Validar requests/responses

MCP server para assistentes de IA

Se está a desenvolver com assistentes de IA como o Claude, considere usar o nosso MCP server em vez de chamadas diretas à API. Ele fornece uma interface padronizada que os modelos compreendem nativamente.

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

Como começar

1. Crie uma conta Victualia em Victualia
2. Subscreva Premium para ativar o acesso à API
3. Gere a sua API key em Definições → API Keys
4. Explore a API via OpenAPI spec ou exemplos acima
5. Construa algo e diga-nos o que criou

Perguntas frequentes

Que subscrição é necessária para acesso à API?

O acesso à API requer uma subscrição Premium. Inclui tanto a REST API como o MCP server.

Existe rate limit?

Sim, aplicam-se limites padrão para prevenir abusos. Para integrações de alto volume, contacte-nos.

Posso usar isto em aplicações comerciais?

Sim. Pode construir aplicações comerciais sobre a API da Victualia. Cada utilizador final precisará da sua própria subscrição Premium.

Existe um ambiente sandbox?

Atualmente não oferecemos uma sandbox separada. Recomendamos criar uma casa de teste na sua conta.

Como reporto bugs ou peço funcionalidades?

Abra uma issue no nosso repositório GitHub ou contacte o suporte através da app.

---

Artigos relacionados

• MCP Server for Home Management - Integração com assistentes de IA via Model Context Protocol
• Pantry Inventory App - Acompanhe o inventário do lar
• Family Organizer App - Organize a casa em conjunto

---

Pronto para construir? Obtenha a sua API key e comece a integrar gestão doméstica na sua aplicação.