Agregados

Todos os recursos financeiros da API vivem dentro de um agregado e são endereçados em /households/:householdId/…. Uma pessoa pode pertencer a vários agregados com uma função diferente em cada um (proprietário, editor ou leitor), e é assim que uma casa partilhada, uma casa de família e um negócio paralelo se mantêm separados na mesma conta.

Os agregados nunca partilham dados. Não há leituras entre agregados, não há lista de categorias comum e não existe qualquer operação para copiar de um agregado para outro. A única coisa que atravessa a fronteira é a pessoa.

Uma chave é criada dentro de um agregado e só pode agir sobre esse; um pedido dirigido a outro agregado é rejeitado com 403, mesmo que a pessoa que criou a chave tenha acesso a esse outro agregado na aplicação. Não precisa de saber o id: o segmento literal current resolve sempre para o agregado da própria chave.

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"

O ciclo de vida do agregado e a gestão de membros são exclusivos de sessão: uma pessoa com sessão iniciada na aplicação, nunca uma chave de API. Estas devolvem 403 API_KEY_NOT_ALLOWED:

• POST /households: criar um agregado
• GET /households: listar os agregados a que pertence
• DELETE /households/{householdId}: eliminar um agregado
• Convites: enviar, aceitar e revogar
• Membros: listar, mudar a função, remover, sair
• Transferir a propriedade e repor o agregado no início

A razão é o raio de impacto: uma chave comprometida já é preocupação suficiente dentro de um agregado; pior seria se ainda pudesse criar agregados novos ou enumerar todos aqueles a que pertence quem a criou. GET /households/current é a exceção e exige read:households, é assim que uma integração descobre onde está.

{  "error": {    "code": "API_KEY_NOT_ALLOWED",    "message": "This endpoint is not available to API keys."  }}

Pode pertencer a um número ilimitado de agregados, mas só pode TER A PROPRIEDADE de um número limitado: 2 no plano gratuito e 10 no Pro. Criar acima do limite (a partir da aplicação, já que a criação é exclusiva de sessão) devolve 409. Precisa de um limite maior? Fale connosco e aumentamo-lo no seu plano.

{  "error": {    "code": "HOUSEHOLD_LIMIT_REACHED",    "message": "You already own 2 households, the maximum for your plan.",    "details": { "limit": 2, "owned": 2 }  }}

Um agregado novo é criado vazio, com um idioma de dados (`locale`, por omissão o idioma da interface de quem o cria). GET /meta/category-packs?locale=&dataLocale= lista os pacotes iniciais, com os grupos e as categorias que cada um cria (as designações em `locale`, os nomes em `dataLocale`) e POST /households/:householdId/starter-pack aplica um deles com write:categories, no idioma de dados do agregado. Aplicar um pacote é idempotente por nome, por isso repetir o pedido nunca duplica a estrutura.