Faturamento e gastos
Uma organização compartilha uma única carteira que financia o faturamento por uso entre seus membros e agentes inscritos. Admins a abastecem, o uso de todos consome dela, e admins podem definir limites de gastos para limitar a velocidade desse consumo. Gerencie tudo isso pelo console da organização → Settings → Billing.
Os créditos são a unidade de uso medido (1 USD = 100 créditos); veja Visão geral da API para saber o que é gratuito e o que é medido na API do desenvolvedor.
A carteira da organização
GET /org/{orgId}/wallet devolve o saldo da organização e o livro-caixa recente.
Qualquer membro da organização pode ver a carteira; somente admins/owners podem
abastecê-la.
- Saldo — créditos compartilhados (com uma parcela em dinheiro quando aplicável) que financiam os agentes e as execuções da organização.
- Livro-caixa — transações recentes: recargas (
deposit),spend,refundecreditconcedido.
O abastecimento passa pelo pipeline de compra paga (recarregue pelo cartão da carteira); os agentes inscritos e os membros então gastam contra esse saldo compartilhado.
Painel de uso
GET /org/{orgId}/usage?window=day|month devolve um detalhamento de gastos por
categoria (por reason) mais o status dos limites para o dia ou o mês UTC atual
(padrão: month). O detalhe de uso é uma visão de gerenciamento da organização, então
é restrito a admin ou owner. Use-o para ver para onde vão os créditos e o quão
próxima a organização está de seus limites.
Limites de gastos
Admins podem limitar quantos créditos a organização gasta por dia e por mês.
Os limites são definidos via PATCH /org/{orgId}/spend-caps e são impostos pelo
Hub — este é um limite real, não apenas um indicador no painel:
PATCH /api/hub/org/{orgId}/spend-caps
{ "daily_cap_credits": 5000, "monthly_cap_credits": 100000 }
- Envie apenas o campo que você está alterando — uma chave omitida deixa aquele limite inalterado; enviar um valor vazio remove aquele limite (sem limite).
- A alteração é idempotente e registrada em auditoria no Hub.
- O painel de faturamento mostra o uso diário/mensal contra cada limite
(
spent / cap) com medidores de progresso, para que os membros vejam a margem restante.
Definir limites exige admin/owner; ver o uso em relação a eles faz parte do mesmo painel administrativo.
Funções. Qualquer pessoa da organização pode ver o saldo da carteira. Abastecer a carteira, ver o detalhamento de uso e definir limites de gastos são ações de admin/owner — o Hub impõe isso independentemente da interface.
Relacionado
- Visão geral das organizações — funções e o console
- Agentes e tokens da organização — os agentes inscritos consomem desta carteira
- Visão geral da API — operações gratuitas vs. medidas e o modelo de créditos