Cobrança

A Central de Cobranças (Billing) é o app da plataforma que fatura, em nome do seu app, as áreas de trabalho que o instalam. O seu app não emite boletos nem processa pagamentos: ele declara que emite cobrança, publica um plano com preços por evento e, a cada uso cobrável, envia um evento à Central de Cobranças. Ela agrupa os eventos por competência, gera as faturas, cobra e repassa. Esta página mostra o caminho do lado do Console e da API; a referência da Central de Cobranças está em Funcionalidades para Desenvolvedores.

Passo a passo

1. Marcar o app como “Emite cobrança”

Na aba Listagens, marque Emite cobrança e salve — ou, pela CLI, iugu app publish --billable true (é uma decisão de publicação: exige aprovação). A partir daí:

• a área de trabalho publicadora vê a pendência Aplicativos com cobrança devem ter um plano configurado e publicado até que o passo 2 esteja concluído;
• instalar o app passa a exigir que a área de trabalho tenha os dados de cobrança preenchidos na Central de Cobranças (o Console a encaminha para lá quando faltam);
• cada instalação cria uma assinatura do plano padrão, e a desinstalação a cancela;
• o app não pode mais ser descartado enquanto emitir cobrança.

2. Publicar um plano na Central de Cobranças

Um plano tem versões; cada versão tem preços que ligam um nome de evento a um valor (unitário, por faixas, mínimo…). Só a versão publicada e definida como padrão é cobrada; uma versão publicada não muda mais — cria-se outra. Duas formas:

• Pela interface, em https://billing.iugu.com/apps/<id do app> — o roteiro está em Planos de cobrança.
• Pela CLI ou por um agente, com as ações que a Central de Cobranças expõe como provedora (veja Expor ações):

iugu call billing create_plan     --arg app_id=<id do app> --arg name="Pro"        # idempotente: cria o plano com a versão 1 em rascunho
iugu call billing add_price       --arg plan_version_id=<id da versão> \
     --arg name="Fatura emitida" --arg event=invoice.created --arg model=unit --arg 'config={"amount":"1.50"}'
iugu call billing preview_pricing --arg plan_version_id=<id da versão> --arg 'quantities={"invoice.created":230}'
iugu call billing publish_version --arg plan_version_id=<id da versão> --arg set_as_default=true   # a pessoa confirma no navegador

Os preços ligam um nome de evento (exatamente o que o seu app vai enviar) a um modelo — unit (por unidade), package (por pacote), tiered ou bulk (por faixas) — com valores em reais como texto ("1.50"). set_prices substitui a lista inteira de uma versão em rascunho; create_plan_version abre a próxima versão clonando os preços da atual.

3. Consumir billing:event.create

Na aba Permissões do seu app, adicione billing:event.create às Ações Consumidas (e billing:event.show, billing:event.list_failed se quiser consultar e reenviar eventos). Como a Central de Cobranças está instalada em todas as áreas de trabalho, a política gerenciada concede essas ações ao seu app em cada instalação.

4. Enviar eventos de uso

O seu backend obtém um token do próprio app dirigido à Central de Cobranças e envia os eventos em lotes:

# token do app, com audiência da Central de Cobranças
# (33qqIXOLGKohFVkWBN1Apf é o id público e fixo do app Central de Cobranças, o mesmo em todos os ambientes)
curl -X POST https://identity.iugu.com/token \
  -u "<client_id>:<client_secret>" \
  -d grant_type=client_credentials \
  -d audience=Iugu.Platform.33qqIXOLGKohFVkWBN1Apf

# eventos (até 1000 por requisição)
curl -X POST https://billing.iugu.com/api/events \
  -H "Authorization: Bearer <token>" \
  -H "Workspace-Id: <id curto da área de trabalho cobrada>" \
  -H "Content-Type: application/json" \
  -d '{
        "events": [{
          "name": "invoice.created",
          "idempotency_key": "acme-invoices:inv_8f2a:created",
          "timestamp": "2026-09-20T15:04:05Z",
          "entity_name": "invoice",
          "entity_id": "inv_8f2a",
          "custom_unit_quantity": 1,
          "metadata": { "customer": "ACME Ltda" }
        }]
      }'

A resposta 201 traz created com as chaves aceitas e, quando algum evento falhou na validação, errors por chave; 422 quando nenhum foi aceito.

Para acompanhar: GET https://billing.iugu.com/api/events/<idempotency_key> mostra um evento e seu estado; GET https://billing.iugu.com/api/events/list_failed lista os que falharam nas últimas 23 h, para correção e reenvio. A referência completa está no API Explorer da Central de Cobranças.

Faturas, valores em aberto e relatórios

As áreas de trabalho que instalaram o seu app acompanham as faturas na Central de Cobranças; quem tem billing:invoices.show e billing:reports.read também as vê no painel do Console, nos widgets Receita, Em aberto e Faturas pendentes que a Central de Cobranças oferece como provedora de ações — e pode consultá-las por um assistente conectado ao Iugu for AI (billing__list_invoices, billing__get_pending_amount, billing__get_revenue) ou pela CLI (iugu call billing list_invoices --workspace <id>).

Resumo do modelo