Hogares
Un hogar es la unidad de aislamiento: cuentas, transacciones, presupuestos, categorías, reglas y claves pertenecen exactamente a uno. Tu clave también pertenece a uno; aquí tienes lo que eso te permite y lo que no.
Un hogar, un espacio aislado
Todos los recursos financieros de la API viven dentro de un hogar y se direccionan bajo /households/:householdId/…. Una persona puede pertenecer a varios hogares con un rol distinto en cada uno (propietario, editor o lector): así conviven en una misma cuenta el piso compartido, la casa familiar y un negocio propio.
Los hogares nunca comparten datos. No hay lecturas entre hogares, ni lista de categorías común, ni una operación para copiar de otro hogar. Lo único que cruza es la persona.
Tu clave está ligada a un hogar
Una clave nace dentro de un hogar y solo puede actuar sobre ese; una petición dirigida a otro hogar se rechaza con 403 aunque su dueño sí pueda entrar en él desde la app. No necesitas saber el id: el segmento literal current siempre se resuelve al hogar de la clave.
curl -H "Authorization: Bearer vokse_sk_…" \ https://api.vokse.ai/households/current# every scoped route takes the alias in place of the idcurl -H "Authorization: Bearer vokse_sk_…" \ "https://api.vokse.ai/households/current/transactions?limit=50"Lo que una clave no puede hacer
El ciclo de vida del hogar y la pertenencia son solo de sesión: una persona identificada en la app, nunca una clave de API. Esto devuelve 403 API_KEY_NOT_ALLOWED:
- POST /households: crear un hogar
- GET /households: listar los hogares a los que perteneces
- DELETE /households/{householdId}: eliminar un hogar
- Invitaciones: enviar, aceptar y revocar
- Miembros: listar, cambiar rol, expulsar, salir
- Transferir la propiedad y reiniciar el onboarding
La razón es el radio de impacto: una clave filtrada ya preocupa bastante dentro de un hogar como para que además pueda crear hogares nuevos o enumerar todos los de su dueño. La excepción es GET /households/current, que requiere read:households y sirve para que una integración descubra dónde está.
{ "error": { "code": "API_KEY_NOT_ALLOWED", "message": "This endpoint is not available to API keys." }}Límites de propiedad
Puedes pertenecer a hogares sin límite, pero solo puedes SER PROPIETARIO de un número limitado: 2 en el plan gratuito y 10 en Pro. Crear por encima del tope (desde la app, porque la creación es solo de sesión) devuelve 409. ¿Necesitas más? Escríbenos y lo subimos en tu plan.
{ "error": { "code": "HOUSEHOLD_LIMIT_REACHED", "message": "You already own 2 households, the maximum for your plan.", "details": { "limit": 2, "owned": 2 } }}Arrancar un hogar
Un hogar nuevo se crea vacío, con un idioma de datos (`locale`, por defecto el idioma de la interfaz de quien lo crea). GET /meta/category-packs?locale=&dataLocale= lista los packs iniciales con los grupos y categorías exactos que crea cada uno (etiquetas en `locale`, nombres en `dataLocale`), y POST /households/:householdId/starter-pack aplica uno con write:categories en el idioma de datos del hogar. Aplicarlo es idempotente por nombre, así que reintentar nunca duplica la estructura.