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.

Na operação, a carteira é uma dependência do envio pay-as-you-go: envios SMS e WhatsApp são rejeitados quando o saldo não consegue cobri-los. SMS é recusado no API com um 402; um envio WhatsApp é aceito e depois rejeitado quando Bird tenta cobrá-lo. O e-mail em um plano de Email pago é cobrado logo após o envio, então o saldo pode ficar negativo por um breve período. Quando a carteira não tem mais saldo nem crédito, novos e-mails são recusados com um 402 até que você adicione fundos. Uma taxa cobrada no momento da entrega que o saldo não consegue cobrir é ignorada em vez de rejeitada, então a mensagem ainda chega ao destinatário. Para volume transacional, configure a recarga automática e um alerta de saldo baixo na página Billing overview, ou faça o monitoramento e os alertas do seu lado. Métodos de pagamento e carteira explica os dois controles do dashboard.

Avisos de saldo baixo, notificações de falha de pagamento e e-mails de fatura vão para a lista de notificações de faturamento da organização, quando ela está configurada, e, caso contrário, para todos os owners da organização. Em uma organização com um único espaço de trabalho, configure essa lista em Settings > Notifications > Billing; o dashboard ainda não a exibe para organizações com vários espaços de trabalho. O contato de faturamento em Billing and payments > Settings é uma configuração separada; veja Dados de faturamento. Use um alias de equipe monitorado para a lista de notificações, para que os 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