Billing por API

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

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

Authorization: Bearer sk_live_xxxxx

Con API key, rutas de billing exigen scopes billing:read o billing:manage — ver Scopes. Con sessionToken, miembros OWNER/ADMIN del workspace pueden operar sin scopes en la clave.

Consultar suscripción

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.

Suscribir plan

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

{
  "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.

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.

Guías simples

Conoce más

Workspaces

OAuth 2.1

IA y no-code

BYOK

Changelog

Platform API

Cuenta

API Keys

Billing

Créditos

Equipo

Metadatos

OAuth

Webhooks

Entregas

Logs

Workspaces

Autenticación

Consultar suscripción

Suscribir plan

Cancelar suscripción

Saldo (pago por uso)

Tarjetas de pago

Historial de uso de créditos

Errores comunes

​Autenticación

​Consultar suscripción

​Suscribir plan

​Cancelar suscripción

​Saldo (pago por uso)

​Tarjetas de pago

​Historial de uso de créditos

​Errores comunes

Autenticación

Consultar suscripción

Suscribir plan

Cancelar suscripción

Saldo (pago por uso)

Tarjetas de pago

Historial de uso de créditos

Errores comunes