> ## 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 por API

> Consulta plan, saldo, suscripción, tarjetas y recargas sin abrir el panel.

<Tip>
  Billing por API es la **caja registradora remota**: suscribir plan, recargar saldo y registrar tarjetas — igual que el panel, por HTTP.
</Tip>

Con API key (o `sessionToken` de login), la Platform API expone billing del workspace en `/v1/platform/workspaces/:id/*`. Útil para agentes de IA que provisionan cuenta y ya suscriben plan o recargan saldo.

## Autenticación

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

Con API key, rutas de billing exigen scopes `billing:read` o `billing:manage` — ver [Scopes](/es/platform-api/como-funciona/escopos-api-key). Con `sessionToken`, miembros OWNER/ADMIN del workspace pueden operar sin scopes en la clave.

## Consultar suscripción

```bash theme={null}
curl https://api.notifique.dev/v1/platform/workspaces/WORKSPACE_ID/subscription \
  -H "Authorization: Bearer sk_live_..."
```

Devuelve plan actual, créditos del ciclo, estado de suscripción en el proveedor de pagos, próxima cobranza y snapshot de billing. Conceptos de créditos vs saldo: [Cobranza](/es/guides/introducao/cobranca-e-pague-pelo-uso).

## Suscribir plan

`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 del plan (0 = Free, 1 = Basic, …; máximo **10**)
* `billingType` — `PIX` o `CREDIT_CARD`
* Con tarjeta guardada, usa `paymentMethodId`; con PIX, la respuesta puede incluir datos de pago

## Cancelar suscripción

`DELETE /v1/platform/workspaces/:id/subscription` — cancela renovación; acceso hasta fin del ciclo según política del plan.

## Saldo (pago por uso)

| Método | Ruta                                           | Scope            |
| ------ | ---------------------------------------------- | ---------------- |
| GET    | `/v1/platform/workspaces/:id/balance`          | `billing:read`   |
| POST   | `/v1/platform/workspaces/:id/balance/recharge` | `billing:manage` |

Recarga mínima y vigencia del saldo siguen reglas del producto (mín. R\$ 30, lotes con 90 días). `billingType`: `PIX` o `CREDIT_CARD`.

## Tarjetas de pago

| Método | Ruta                                                | Scope            |
| ------ | --------------------------------------------------- | ---------------- |
| 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` |

Tokenización envía `creditCard` y `creditCardHolderInfo` (nombre, email, CPF/CNPJ, dirección, teléfono). Tarjetas quedan en el proveedor de pagos; la API devuelve IDs para reutilizar en suscripción y recarga.

## Historial de uso de créditos

`GET /v1/platform/workspaces/:id/credits/usage` — scope `billing:read`.

Devuelve saldo de créditos, renovación del ciclo, saldo en reales y lista paginada de consumo con canal, importe, `correlationId` y `apiKeyId`.

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

## Errores comunes

* **402** `INSUFFICIENT_CREDITS` / `WORKSPACE_BLOCKED` — sin créditos o saldo para enviar
* **403** — scope `billing:read` o `billing:manage` ausente en API key
* **503** — billing no configurado en el entorno (provedor de pagamento)

Alternativa solo lectura vía API de mensajería: `GET /v1/workspaces/:id?include=billing` con scope de workspace.