API da Vixpi Portal de desenvolvedores, versão v1

Painel do desenvolvedor

Changelog da API

O que mudou na API. Dentro da v1 a Vixpi só acrescenta campos, rotas e escopos; uma mudança que quebre o seu código sai numa versão nova da URL.

Idempotência, limites visíveis e MCP 0.2

Repetir uma escrita com segurança, ver o limite em cada resposta e um servidor MCP bem maior. Só acrescenta; nada da v1 quebra.

  • Idempotency-Key: Escritas de tickets, pagamento com crédito, cancelamento, upgrade, energia de VPS e deploy/backup/domínio de hospedagem aceitam o cabeçalho. Mesma chave e mesmo corpo devolvem a mesma resposta por 24 horas (Idempotent-Replayed: true); corpo diferente dá 409 IDEMPOTENCY_KEY_REUSED e duplicata em andamento dá 409 IDEMPOTENCY_IN_PROGRESS.
  • RateLimit-*: Toda resposta a uma chamada com token traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset; o 429 também traz Retry-After.
  • GET /token: Mostra com qual conta, escopos e validade o token atual foi emitido. Nome e e-mail só aparecem com account:read.
  • GET /domains/: Lista os domínios registrados na conta, com o escopo domains:read.
  • MCP 0.2.0: De 20 para 32 ferramentas: whoami, pedidos, domínios, notificações, catálogo, detalhe de deploy com log, firewall da VPS, fechar e reabrir ticket, pagar fatura com crédito e deploy de hospedagem. Listas com limit/offset/hasMore, response_format markdown ou json e 3 prompts em português. Atenção: nas listas o resultado estruturado agora usa a chave items (antes servers, backups, domains ou deployments). vixpi_cancel_service cancela só ao fim do ciclo; o cancelamento imediato fica no painel.
  • Segurança do MCP: Origin conferido, corpo limitado a 1 MiB, lote de até 10 mensagens, desafio insufficient_scope quando falta permissão (só com escopos que o registro automático concede; hosting:deploy fica de fora) e texto de terceiros, inclusive mensagens de erro 4xx, marcado como dado.

Lançamento da API v1

A API que o painel usa passa a aceitar tokens de terceiros, com escopos e documentação pública.

  • OAuth 2.1: Fluxo authorization code com PKCE S256, refresh com rotação e revogação. O emissor publica o discovery em /.well-known/openid-configuration.
  • Chaves pessoais: Chaves vxp_ criadas no painel, com os escopos e a validade que você escolher.
  • Escopos: Cada rota exige um escopo (por exemplo tickets:read). Rota sem escopo na tabela não aceita token.
  • Webhooks: Eventos de serviços, faturas e tickets, assinados com HMAC-SHA256 e com retentativas por até 24 h.
  • Limite de uso: Cada token tem 60 requisições por minuto. Acima disso a API responde 429 com Retry-After.
  • Especificação: OpenAPI 3.1 em /api/v1/openapi.json e referência interativa no portal.