Cobrança
O uso do mês de cada chatbot, o tamanho, o excedente e o crédito da conta, com as mesmas regras do painel. Para plataformas que cobram as lojas do jeito delas.
billing · só o dono da conta cria chave com ela; o crédito pede uma chave com escopo da conta inteiraPacoteIntegrações (R$ 49 por mês, por conta). Sem ele, a API responde 403 plan_not_allowed.| Rota | O que faz |
|---|---|
GET /v1/bots/{id}/usage | Tamanho, cota e uso do mês, projeção, tamanho sugerido, troca agendada e excedente. |
PATCH /v1/bots/{id} | Troca o tamanho e liga, desliga ou muda o teto do excedente. |
GET /v1/credit | O saldo, os lotes que ainda valem e a recarga automática. |
POST /v1/credit/purchases | Compra crédito no cartão da assinatura. |
GET/v1/bots/{id}/usage
status é a fase do mês: cota (dentro da cota), excedente (a cota acabou e o excedente está ligado, até o teto) ou parado (acabaram a cota e o excedente, ou ele está desligado). projection é a projeção até o fim do mês e average_3_months a média dos meses anteriores com atendimento. suggested_size aparece quando outro tamanho sairia mais barato; scheduled, quando há troca marcada para o dia 1º.
curl "https://boavoz.com/api/v1/bots/bot_7c9e6679-7425-40de-944b-e07fc1f90ae7/usage" \
-H "Authorization: Bearer $BOAVOZ_API_KEY"{
"bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"month": "2026-10",
"size": "M",
"volume_packs": null,
"custom_quota": null,
"quota": 340,
"used": 212,
"status": "cota",
"projection": 318,
"average_3_months": 287,
"suggested_size": null,
"scheduled": null,
"overage": {
"enabled": false,
"cap_brl": null,
"used": 0,
"max": 0,
"value_brl": 0,
"suspended": null
}
}PATCH/v1/bots/{id}
Com size, volume_packs e overage (permissão billing), a resposta é o uso do chatbot. O mesmo PATCH muda os dados do chatbot com a permissão provisioning (Lojas pela API), em outro pedido. A regra é a do painel. Subir de tamanho vale na hora e cobra a diferença proporcional até o dia 1º no cartão da assinatura (abaixo de R$ 1, ela vai para a fatura do dia 1º); descer ou tirar o tamanho fica agendado para o dia 1º (size_change.status scheduled), e mandar o tamanho atual cancela o agendado.
curl -X PATCH "https://boavoz.com/api/v1/bots/bot_7c9e6679-7425-40de-944b-e07fc1f90ae7" \
-H "Authorization: Bearer $BOAVOZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"overage": {
"enabled": true,
"cap_brl": 50
}
}'{
"bot_id": "bot_7c9e6679-7425-40de-944b-e07fc1f90ae7",
"month": "2026-10",
"size": "M",
"volume_packs": null,
"custom_quota": null,
"quota": 340,
"used": 212,
"status": "cota",
"projection": 318,
"average_3_months": 287,
"suggested_size": null,
"scheduled": null,
"overage": {
"enabled": true,
"cap_brl": 50,
"used": 0,
"max": 142,
"value_brl": 0,
"suspended": null
}
}PATCH /v1/bots/bot_7c9e6679-7425-40de-944b-e07fc1f90ae7
Idempotency-Key: troca-bar-do-ze-2026-10-19
{ "size": "G", "overage": { "enabled": true, "cap_brl": 150 } }
→ 200: o uso (como acima) e a troca
"size_change": { "status": "applied", "size": "G", "volume_packs": null, "charged_brl": 32.26, "next_invoice_brl": 0 }
→ 402 payment_required: o cartão recusou; details.invoice_url é a fatura para pagar
(o tamanho novo vale quando ela for paga)| Campo | Regra | Erro |
|---|---|---|
Idempotency-Key | Obrigatório com size (subir cobra na hora). | 400 Idempotency-Key |
size | atendimento (sem IA), P, M, G, volume ou null (sem tamanho). | 400 size |
volume_packs | Só com size: "volume": de 1 a 1.000. | 400 volume_packs |
overage | {enabled, cap_brl?}: enabled obrigatório; cap_brl de 10 a 100.000 reais por mês (null: sem teto; sem o campo, o teto fica como está). Só em chatbot com tamanho de IA. | 400 overage…; 422 overage_not_available |
| outros campos | Não são aceitos: mande size, volume_packs e/ou overage. | 400 com o campo |
| Erro | Quando |
|---|---|
402 payment_required | O cartão recusou a subida; details.invoice_url é a fatura (o tamanho novo vale quando ela for paga). |
402 payment_overdue | O último pagamento da assinatura está em aberto. |
409 conflict | Uma subida anterior deste chatbot acabou de ser paga e já valeu: confira o uso e mande de novo, se precisar. |
422 subscription_required | A conta ainda não tem assinatura (a primeira é feita no painel). |
422 custom_quota | O chatbot tem cota sob medida combinada com a BoaVoz. |
GET/v1/credit
O crédito é da conta e paga o excedente dos chatbots. Cada compra vira um lote que vale 12 meses; o que vence antes é usado primeiro.
curl "https://boavoz.com/api/v1/credit" \
-H "Authorization: Bearer $BOAVOZ_API_KEY"{
"balance_brl": 87.5,
"lots": [
{
"amount_brl": 100,
"remaining_brl": 87.5,
"source": "purchase",
"expires_at": "2027-10-02T13:00:00.000Z",
"created_at": "2026-10-02T13:00:00.000Z"
}
],
"auto_recharge": {
"enabled": false,
"below_brl": null,
"amount_brl": null,
"month_limit_brl": null
}
}POST/v1/credit/purchases
curl -X POST "https://boavoz.com/api/v1/credit/purchases" \
-H "Authorization: Bearer $BOAVOZ_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 3b9f2c8e-5a1d-4e7b-9c6f-2d8a4e1b7c90" \
-d '{
"amount_brl": 50
}'{
"status": "paid",
"amount_brl": 50,
"balance_brl": 137.5
}| Campo | Regra | Erro |
|---|---|---|
Idempotency-Key | Cabeçalho obrigatório (uma chave por compra: repetir não compra de novo). | 400 Idempotency-Key |
amount_brl | De 50 a 50.000, em reais inteiros. | 400 amount_brl |
Cartão recusado: 402 payment_required com details.invoice_url; o crédito entra quando a fatura for paga. O crédito não é reembolsável, salvo na desistência dos 7 dias. Na primeira semana da assinatura, as compras somam até R$ 100: passou disso, 422 first_week_credit_limit (no 8º dia, sem esse limite).
Numa plataforma, o restaurante liga o excedente no painel dela, ela liga pela API e cobra o restaurante como quiser a partir do fechamento do mês (bot.month_closed). O BoaVoz nunca cobra o restaurante: o crédito é da conta da plataforma.