> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing via API

> Consulte plano, saldo, assinatura, cartões e recargas sem abrir o painel.

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

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

```http theme={null}
Authorization: Bearer sk_live_xxxxx
```

Com API key, rotas de billing exigem escopos `billing:read` ou `billing:manage` — veja [Escopos](/platform-api/como-funciona/escopos-api-key). Com `sessionToken`, o membro OWNER/ADMIN do workspace pode operar sem escopos na chave.

## Consultar assinatura

```bash theme={null}
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](/guides/introducao/cobranca-e-pague-pelo-uso).

## Assinar plano

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

```json theme={null}
{
  "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.

```bash theme={null}
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.