Plano e cotas

Consulta de plano, consumo, cota e mudança de plano.

Consulta exige billing.view; alteração exige billing.manage. Todas as operações usam full_access.

GET/v1/billing/plan200 OK

full_access

Consulta o plano atual e o consumo do período.

curl "$BASE_URL/billing/plan" -H "X-API-Key: $CORVO_API_KEY"

Resposta — 200 OK

{
  "data": {
    "plan": {
      "slug": "developer",
      "name": "Developer",
      "monthly_allowance": 250,
      "daily_limit": null,
      "max_active_companies": 999999,
      "monthly_price_cents": 2990
    },
    "usage": {
      "overage_units": 0,
      "overage_amount_cents": 0,
      "hard_limit": null,
      "credits_used": 10,
      "credits_reserved": 2,
      "credits_remaining": 238,
      "monthly_allowance": 250,
      "daily_usage": 3,
      "daily_limit": null,
      "active_companies": 1,
      "max_active_companies": 999999,
      "period_start": "2026-10-01T00:00:00.000Z",
      "period_end": "2026-10-31T23:59:59.000Z"
    },
    "subscription": {
      "status": "active",
      "paid_until": "2026-10-31T23:59:59.000Z",
      "cancel_at_period_end": false,
      "scheduled_plan": null,
      "blocked": false
    }
  }
}

Valores ilustrativos. Esta rota usa snake_case, diferentemente de billing/usage. Ausência de plano após resolução: 404.

GET/v1/billing/usage200 OK

full_access

Consulta a disponibilidade de emissão e as cotas do plano.

curl "$BASE_URL/billing/usage" -H "X-API-Key: $CORVO_API_KEY"

Resposta — 200 OK

{
  "data": {
    "canEmit": true,
    "creditsRemaining": 188,
    "creditsUsed": 10,
    "creditsReserved": 2,
    "monthlyAllowance": 200,
    "dailyUsage": 3,
    "dailyLimit": null,
    "activeCompanies": 1,
    "maxActiveCompanies": 10,
    "periodStart": "2026-10-01T00:00:00.000Z",
    "periodEnd": "2026-10-31T23:59:59.000Z"
  }
}

QuotaStatus: canEmit (boolean), reason?, creditsRemaining, creditsUsed, creditsReserved, monthlyAllowance, dailyUsage, dailyLimit (number ou null), activeCompanies, maxActiveCompanies, periodStart, periodEnd (datas ou null). Reasons definidos: no_credits, daily_limit_exceeded, company_limit_exceeded, plan_blocked.

A consulta atual determina canEmit com créditos, limite diário e atividade do plano; não é garantia de que os dados fiscais/certificado de uma empresa estejam prontos. As consultas de cota podem inicializar o plano padrão e atualizar um período expirado.

POST/v1/billing/upgrade200 OK

dashboard

Agenda a troca para o plano de destino na assinatura.

Campo	Tipo	Obrigatório	Descrição
plan_slug	string	✓	Slug do plano de destino, por exemplo `growth`.

curl -X POST "$BASE_URL/billing/upgrade" \
  -H "X-API-Key: $CORVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan_slug": "growth" }'

Resposta — 200 OK

{
  "data": {
    "scheduled_plan": "growth",
    "effective_at": "2026-11-01T00:00:00.000Z"
  }
}

Rota exclusiva do painel: chaves de API não têm acesso (403). Exige assinatura ativa (409 caso contrário) e retorna scheduled_plan e effective_at; o checkout e o portal de cobrança também ficam no painel.

POST/v1/billing/downgrade200 OK

dashboard

Agenda uma mudança de plano para o fim do período.

Campo	Tipo	Obrigatório	Descrição
plan_slug	string	✓	Slug do plano de destino, por exemplo `developer`.

curl -X POST "$BASE_URL/billing/downgrade" \
  -H "X-API-Key: $CORVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "plan_slug": "developer" }'

Resposta — 200 OK

{
  "data": {
    "scheduled_plan": "developer",
    "effective_at": "2026-11-01T00:00:00.000Z"
  }
}

Catálogo público de planos

Estas três rotas não exigem chave de API nem sessão: use-as para mostrar preços no seu site ou dimensionar um plano. Valores em centavos (...Cents) e o único ciclo é monthly; qualquer outro cycle retorna 400.

GET/v1/plans200 OK

public

Lista os planos com preço mensal e franquia.

Campo	Tipo	Descrição
cycle	string	Só `monthly` é aceito (padrão).
limit	integer	Padrão `50`; inteiro de 1 a 1000.
cursor	string	`nextCursor` da página anterior.

curl "$BASE_URL/plans"

Resposta — 200 OK

{
  "data": [
    {
      "slug": "developer",
      "name": "Developer",
      "monthlyAllowance": 250,
      "basePriceCents": 2990,
      "perCreditOverageCents": 12,
      "monthlyTotalCents": 2990,
      "currency": "BRL"
    }
  ],
  "pagination": {
    "limit": 50,
    "hasMore": false,
    "nextCursor": null
  }
}

Ordenados da menor para a maior franquia. monthlyAllowance é o total de créditos incluídos, perCreditOverageCents o preço de cada crédito acima dela e monthlyTotalCents o preço mensal. Esta é a visão de preços; GET /v1/credits/plans devolve os limites e recursos do plano.

GET/v1/plans/:slug200 OK

public

Consulta o preço de um plano.

Campo	Tipo	Obrigatório	Descrição
cycle	string		Só `monthly` é aceito (padrão).

curl "$BASE_URL/plans/growth"

Resposta — 200 OK

{
  "data": {
    "slug": "growth",
    "name": "Growth",
    "monthlyAllowance": 1500,
    "basePriceCents": 9990,
    "perCreditOverageCents": 8,
    "monthlyTotalCents": 9990,
    "currency": "BRL"
  }
}

slug é free, developer, growth, scale ou volume. Um plano desconhecido retorna 404.

GET/v1/plans/quote200 OK

public

Recomenda o plano para um volume mensal de notas e estima o custo total.

Campo	Tipo	Obrigatório	Descrição
volume	integer		Notas por mês. Obrigatório para gerar a cotação.
cycle	string		Só `monthly` é aceito (padrão).

curl "$BASE_URL/plans/quote?volume=20000"

Resposta — 200 OK

{
  "data": {
    "volume": 20000,
    "recommended_plan": "volume",
    "plan_name": "Volume",
    "monthly_allowance": 10000,
    "overage_credits": 10000,
    "overage_cost_cents": 90000,
    "base_price_cents": 89990,
    "total_estimated_cents": 179990,
    "currency": "BRL",
    "billing_cycle": "monthly"
  }
}

Esta rota usa snake_case. total_estimated_cents é o preço do plano mais o excedente estimado (overage_credits × o preço por crédito do plano). Um volume ausente, zero, negativo ou não numérico retorna 200 com { "data": null }, e não um erro.