API de Registro Remoto

Faça login como admin, abra Configurações → 🔑 API de Registro Remoto e clique em "Gerar token".

O token em texto puro é mostrado apenas uma vez — copie imediatamente. O servidor só armazena o hash SHA-256, então um token perdido só pode ser substituído por rotação (o que invalida o anterior).

Formato do token: bb_<userId>_<secret>. Envie em cada requisição como Authorization: Bearer <token>.

O corpo da requisição é um objeto JSON com estes campos:

• title (string, obrigatório) — nome da transação
• amount (number, obrigatório) — deve ser positivo
• type (string, opcional, padrão expense) — um de expense / income / prepaid_expense / pending_income
• category (string, opcional) — nome da categoria
• note (string, opcional) — observação livre
• created_at (string, opcional) — ISO 8601; padrão é agora

curl -X POST https://billbook.me/api/ingest \
  -H "Authorization: Bearer bb_<userId>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Coffee","amount":120,"type":"expense","category":"Food"}'

# response: 201
{ "id": "...", "created_at": "..." }

Retorna os nomes das categorias do admin na ordem do dropdown do painel. A resposta contém apenas os nomes — sem ids, user ids ou dados de transação.

curl https://billbook.me/api/ingest/categories \
  -H "Authorization: Bearer bb_<userId>_<secret>"

# response: 200
{ "categories": ["Food", "Rent", "..."] }

Retorna os prefixos de tag atualizados mais recentemente (os marcadores #XXX embutidos nos títulos). Padrão 20; use ?limit= para sobrescrever (máx. 100).

Retorna um array vazio em vez de erro se a tabela tag_prefixes ainda não existir.

curl "https://billbook.me/api/ingest/tags?limit=20" \
  -H "Authorization: Bearer bb_<userId>_<secret>"

# response: 200
{ "tags": ["#management-fee", "#travel", "..."] }

Todos os erros são JSON: { "error": "mensagem" }.

• 401 — autorização ausente, token mal formado, revogado ou inconsistente
• 402 — assinatura expirada; renovação necessária para escrever
• 405 — método não suportado (ex.: GET em /api/ingest)
• 501 — SUPABASE_SERVICE_ROLE_KEY não configurada no servidor
• 500 — outro erro interno

Por design, o token só pode escrever na própria organização — não pode personificar outras orgs nem ler dados existentes:

• user_id é sempre o dono do token; não pode ser forjado
• org_id é sempre a org do dono; escritas entre orgs são impossíveis
• Tokens só são emitidos para a função admin (manager / staff recebem 403)
• As respostas nunca vazam outras linhas — apenas { id, created_at } é retornado
• A revogação é imediata; faça rotação a qualquer momento nas Configurações

Adicione uma ação "Obter Conteúdo de URL", URL https://billbook.me/api/ingest, método POST, cabeçalhos Authorization: Bearer bb_... e Content-Type: application/json, e corpo em JSON: {"title":"Café","amount":120,"type":"expense"}. Conecte title e amount à entrada do Atalho ou variáveis "Perguntar a cada execução".