Billing via API

Billing via API é a caixa registradora remota: assinar plano, recarregar saldo e cadastrar cartão — igual ao painel, por HTTP.

Com a API key (ou sessionToken de login), a Platform API expõe billing do workspace em /v1/platform/workspaces/:id/*. Útil para agentes de IA que provisionam conta e já assinam plano ou recarregam saldo.

Autenticação

Authorization: Bearer sk_live_xxxxx

Com API key, rotas de billing exigem escopos billing:read ou billing:manage — veja Escopos. Com sessionToken, o membro OWNER/ADMIN do workspace pode operar sem escopos na chave.

Consultar assinatura

curl https://api.notifique.dev/v1/platform/workspaces/WORKSPACE_ID/subscription \
  -H "Authorization: Bearer sk_live_..."

Retorna plano atual, créditos do ciclo, status da assinatura no provedor de pagamento, próxima cobrança e snapshot de billing. Conceitos de créditos vs saldo: Cobrança.

Assinar plano

POST /v1/platform/workspaces/:id/subscription

{
  "tierIndex": 1,
  "billingType": "CREDIT_CARD",
  "cpfCnpj": "12345678901",
  "mobilePhone": "5511999999999",
  "paymentMethodId": "pm_xxx",
  "couponCode": "opcional"
}

tierIndex — índice do plano (0 = Free, 1 = Basic, …; máximo 10)
billingType — PIX ou CREDIT_CARD
Com cartão salvo, use paymentMethodId; com PIX, a resposta pode incluir dados de pagamento

Cancelar assinatura

DELETE /v1/platform/workspaces/:id/subscription — cancela renovação; acesso até o fim do ciclo conforme política do plano.

Saldo (pague pelo uso)

Método	Rota	Escopo
GET	`/v1/platform/workspaces/:id/balance`	`billing:read`
POST	`/v1/platform/workspaces/:id/balance/recharge`	`billing:manage`

Recarga mínima e validade do saldo seguem as regras do produto (mín. R$ 30, lotes com validade de 90 dias). billingType: PIX ou CREDIT_CARD.

Cartões de pagamento

Método	Rota	Escopo
GET	`/v1/platform/workspaces/:id/payment-methods`	`billing:read`
POST	`/v1/platform/workspaces/:id/payment-methods`	`billing:manage`
PATCH	`/v1/platform/workspaces/:id/payment-methods/:pmId`	`billing:manage`
DELETE	`/v1/platform/workspaces/:id/payment-methods/:pmId`	`billing:manage`

Tokenização envia creditCard e creditCardHolderInfo (nome, e-mail, CPF/CNPJ, endereço, telefone). Cartões ficam no provedor de pagamento; a API retorna IDs para reutilizar em assinatura e recarga.

Histórico de uso de créditos

GET /v1/platform/workspaces/:id/credits/usage — escopo billing:read. Retorna saldo atual de créditos, renovação do ciclo, saldo em reais e uma lista paginada de consumo (usage) com canal, valor cobrado, correlationId e apiKeyId. Útil para auditoria e para agentes que precisam explicar gastos ao cliente.

curl "https://api.notifique.dev/v1/platform/workspaces/WORKSPACE_ID/credits/usage?page=1&limit=20" \
  -H "Authorization: Bearer sk_live_..."

Erros comuns

402 INSUFFICIENT_CREDITS / WORKSPACE_BLOCKED — sem créditos ou saldo para enviar
403 — escopo billing:read ou billing:manage ausente na API key
503 — billing não configurado no ambiente (provedor de pagamento)

Alternativa somente leitura via API de mensageria: GET /v1/workspaces/:id?include=billing com escopo de workspace.

Guias simples

Conheça mais

Workspaces

OAuth 2.1

IA e no-code

BYOK

Changelog

Platform API

Conta

API Keys

Billing

Créditos

Equipe

Metadados

OAuth

Webhooks

Entregas

Logs

Workspaces

Autenticação

Consultar assinatura

Assinar plano

Cancelar assinatura

Saldo (pague pelo uso)

Cartões de pagamento

Histórico de uso de créditos

Erros comuns

​Autenticação

​Consultar assinatura

​Assinar plano

​Cancelar assinatura

​Saldo (pague pelo uso)

​Cartões de pagamento

​Histórico de uso de créditos

​Erros comuns

Autenticação

Consultar assinatura

Assinar plano

Cancelar assinatura

Saldo (pague pelo uso)

Cartões de pagamento

Histórico de uso de créditos

Erros comuns