Sign inGet Started
Começar
Guias
Referência de API
SDKs
CLI
Base de conhecimento
Changelog

Cobrança e uso

A cobrança tem escopo de organização: seus planos de produto, sua carteira e seu fluxo de faturas pertencem à organização. Esta página explica como a cobrança influencia uma integração: como o uso é medido, como consultar a situação atual e como os seus planos afetam os limites operacionais. Para operações de conta (detalhes de preços, métodos de pagamento, impostos), consulte a Knowledge base: Planos e preços e Uso, gastos e faturas.

O faturamento é gerenciado por pessoas, não por integrações. Toda operação de faturamento exige o escopo org:billing, um escopo de função organizacional que não pode ser concedido a uma chave API de espaço de trabalho, então nenhuma chave bk_* consegue ler o consumo, recarregar a carteira ou alterar um plano. Owners e billing admins fazem isso na seção Billing and payments do dashboard; veja Usuários, equipes e funções para saber quem possui a função. Os catálogos de planos, produtos e preços são a exceção: não exigem autenticação, publicam os preços neste site, e os endpoints CLI e MCP podem ler o catálogo de planos diretamente. Este guia, portanto, explica o que o faturamento faz com a sua integração e nomeia a página do dashboard que mostra cada número. Essas páginas (Overview, Usage, Invoices, Spend e Settings) são cobertas nos artigos da Knowledge base linkados ao longo do texto.

Planos e níveis

Cada produto tem o seu próprio plano, escolhido de forma independente: uma organização pode ter ao mesmo tempo um plano SMS pago, um plano Realtime e o plano Email Free, e deixar o Voice no pay-as-you-go. Cada plano tem um nível (como free, startup, growth ou scale) e um de dois comportamentos financeiros. Um plano de financiamento adiciona um depósito mensal à carteira compartilhada e cobra o uso desde o primeiro envio; um plano de capacidade compra uso incluído e não adiciona nada à carteira. Planos e preços explica os dois, e a página Billing overview lista os planos atuais da sua organização.

Na operação, a sua integração sente o plano da seguinte forma:

  • Os limites de requisições aumentam com o nível. Cada plano define valores para as políticas do seu produto, como sms_send ou whatsapp_send, e níveis mais altos definem valores mais altos. Sem um plano, vale o padrão da política. Uma substituição ativa por organização tem precedência sobre qualquer plano. Veja como o seu limite é resolvido.
  • As cotas aumentam com o nível. Os planos definem quantidades como chamadas simultâneas no Voice, conexões Realtime, domínios de envio, IPs dedicados e endpoints de webhook. Quando você atinge uma cota, o novo recurso, chamada ou conexão é recusado com um erro próprio, diferente de uma resposta 429 de limitação de requisições.
  • As franquias terminam nos limites do plano. O plano Email Free para nos seus limites mensal e diário, e um plano Realtime para nos seus limites de conexões e de mensagens diárias. Os planos de Email pagos não têm franquia incluída: todo envio é cobrado da carteira.

Para consultar os valores publicados de qualquer plano sem autenticação, liste o catálogo de planos com bird billing plans list --commercial-product sms. Cada plano retorna financial_behavior, rate_limits e quotas. A tabela comparativa na página de preços de cada produto mostra esses valores ao lado dos padrões do pay-as-you-go, então compare os dois ali antes de fazer upgrade para ganhar capacidade.

Os upgrades entram em vigor assim que o pagamento é aprovado, então os novos limites chegam no meio do período sem alterar a data de renovação. Downgrades e cancelamentos entram em vigor no fim do período atual, e uma renovação não paga devolve o produto ao plano gratuito ou aos limites do pay-as-you-go. Veja Alterações de plano e renovações para as regras de prazo. Projete integrações para tratar erros de limite quando um plano mudar ou uma franquia se esgotar.

Medição de uso

Todo envio é medido contra o período de faturamento atual da sua organização. A página Usage do dashboard mostra o panorama em tempo real de cada produto, dentro da janela em que aquele produto é medido: o período do plano para e-mail com franquia, o mês calendário para pay-as-you-go. Produtos cobram de duas formas, e a diferença é o que a sua integração sente:

  • Produtos com franquia contam o uso em relação à franquia incluída em um plano (envios de e-mail no plano Email Free ou em um plano de Email legado). A página mostra quanto da franquia você já consumiu e, em um plano legado com excedente, quanto você já ultrapassou.
  • Produtos pay-as-you-go são cobrados por uso conforme uma tabela de preços (SMS, WhatsApp, Voice e e-mail em um plano de Email pago), com o preço do plano quando o plano tiver um. Uma mensagem pode debitar a carteira duas vezes: a taxa própria de Bird quando o envio é processado, e uma taxa de terceiros (sobretaxa da operadora em SMS, participação da Meta em WhatsApp) quando a mensagem é entregue. Leia a divisão por mensagem em cost na mensagem SMS ou WhatsApp: transaction_amount é a cobrança de Bird e passthrough_amount é a taxa de terceiros.

A página cobre todo produto com assinatura ou uso no período atual e exibe gráficos com a divisão por dia, por país e por domínio de envio para qualquer um deles.

A página Usage no dashboard Bird: gasto total com projeção, contagens de envio por canal e gráficos de uso diário

A carteira

Cada organização tem uma carteira: um saldo pré-pago compartilhado por onde passam as cobranças de uso. Envios pay-as-you-go, assinaturas de add-ons e renovações de planos de Email legados debitam a carteira. Os planos de funding a abastecem: cada depósito mensal pago é adicionado integralmente e pode pagar qualquer produto. Um cartão salvo também a abastece por meio de recargas e da recarga automática, e paga as renovações de plano diretamente. A página Spend do dashboard é o extrato completo de créditos e cobranças, de modo que toda movimentação da carteira fica registrada em um só lugar, e cada recarga liquidada gera um recibo permanente que você pode baixar como PDF na mesma seção.

Operacionalmente, a carteira é uma dependência do envio pay-as-you-go: envios SMS e WhatsApp são rejeitados quando o saldo não pode cobri-los. SMS é recusado no API com um 402; um envio WhatsApp é aceito e depois rejeitado quando Bird tenta cobrá-lo. Uma taxa no momento da entrega que o saldo não pode cobrir é ignorada em vez de rejeitada, então a mensagem ainda chega ao destinatário. Para volume transacional, configure recarga automática e um alerta de saldo baixo na página Billing overview, ou monitore e alerte pelo seu lado. Métodos de pagamento e carteira cobre ambos os controles do dashboard. Avisos de saldo baixo e notificações de falha de pagamento vão para os owners da organização. E-mails de fatura vão para a lista de notificações de faturamento da organização, quando configurada, e recaem para o owner da organização caso contrário. Configure essa lista em Settings > Organization. Use um alias de equipe monitorado para que e-mails de faturamento não dependam da caixa de entrada de uma única pessoa.

Faturas

As faturas são emitidas por organização, uma por mês calendário, e listadas na página Invoices do dashboard, onde você pode abrir uma para ver seus itens ou baixá-la como PDF. As faturas refletem a mesma medição que a página Usage mostra: as taxas dos planos de capacidade, as cobranças e o excedente dos planos legados e o gasto pay-as-you-go do período. O depósito de um plano de financiamento é uma recarga da carteira com recibo próprio; o uso que ele paga aparece na fatura. Para saber como as faturas são estruturadas, seus status e prazos de pagamento, veja Uso, gastos e faturas na Knowledge base.

Próximos passos