API REST

Plano, moeda e faturamento

O plano da empresa, a moeda em que ela vê os preços e os dados de faturamento.

  • Plano e moeda (a tela Empresa → Plano; só admin e dono, para os outros 403). Durante o beta nada é cobrado. Cada empresa tem uma moeda (BRL, USD, EUR, GBP, MXN, ARS, CLP ou COP), que nasce pelo país de onde ela foi criada (sem ele, BRL), e cada plano tem um preço definido em cada moeda, mensal e anual, sem conversão. Os valores vêm em amount_minor, inteiro na unidade mínima da moeda (4990 é R$ 49,90; o peso chileno não tem casas), com amount e formatted (como a tela mostra) ao lado.
  • GET /billing (tracker:read): currency, currency_locked (com a cobrança ligada, só a equipe da Aquarela troca a moeda), currencies, plan (key, name, description, ai_credits_per_cycle, null para o padrão do servidor, features, o que o plano inclui, e prices na moeda da empresa), plan_source (subscription, ou default quando vale o plano padrão), price (o de agora), subscription (status: trialing, active, past_due ou canceled; interval: month ou year; current_period_start, current_period_end, trial_ends_at e billing_provider, null enquanto não há cobrança), plans (os que a empresa pode ter, com o preço na moeda dela), billing_details e plan_request (o pedido de plano pago esperando a equipe da Aquarela: plan, interval, requested_by e created_at; null sem pedido).
  • PATCH /billing (tracker:write), em JSON: {"currency": "USD"} troca a moeda; {"billing_details": {...}} muda os dados de faturamento, só os campos enviados (null apaga): kind (company ou individual), legal_name, email, country (ISO de duas letras), address_line1, address_line2, city, state, postal_code, tax_id_type e tax_id. O documento segue o país, com os tipos do Stripe: br_cnpj (empresa) e br_cpf (pessoa física), com os dígitos conferidos, us_ein, eu_vat, gb_vat, mx_rfc, ar_cuit, cl_tin e co_nit; sem tax_id_type, vale o do país. Devolve o mesmo que o GET; regra recusada volta 422.
  • POST /billing/plan (tracker:write), em JSON: {"plan": "pro", "interval": "year"} (plan é a key ou o id de um dos plans; interval, month por padrão). Plano gratuito na moeda da empresa muda na hora (outcome: changed); plano pago, ou sem preço na moeda, vira um pedido para a equipe da Aquarela (requested), que combina o pagamento e põe a empresa no plano; o de agora devolve unchanged. Pedir outro plano troca o pedido. Devolve outcome, plan, interval e billing (o mesmo do GET). DELETE /billing/plan-request (tracker:write) cancela o pedido ({"cancelled": true}; false sem pedido). No MCP: get_billing, update_billing, change_plan e cancel_plan_request.