Início rápido

A API da Vixpi é a mesma que o painel usa. Com uma chave ou um app OAuth você consulta e opera serviços, VPS, hospedagem, faturas, créditos e tickets da sua conta.

1. Crie uma chave

Entre no painel, abra Desenvolvedor > Chaves e crie uma chave pessoal. Marque só os escopos de que o seu código precisa: uma chave que só lê tickets leva tickets:read. A chave começa com vxp_ e aparece uma única vez, então guarde-a num cofre de segredos, nunca no código.

2. Faça a primeira chamada

Envie a chave em Authorization: Bearer. Este pedido lista os seus tickets e precisa do escopo tickets:read:

curl

curl -H "Authorization: Bearer vxp_..." \
  https://api.vixpi.host/api/v1/tickets

Para criar um app que age em nome de outras pessoas, use OAuth. O passo a passo está em Autenticação.

Formato de erro

Todo erro volta como JSON com error, code e message. Trate pelo code, que é estável; message é um texto em português para mostrar a uma pessoa.

403

{
  "error": "INSUFFICIENT_SCOPE",
  "code": "INSUFFICIENT_SCOPE",
  "message": "O token não tem o escopo necessário."
}

HTTP	code	Quando acontece
`401`	`INVALID_TOKEN`	Token ausente, inválido, expirado ou revogado.
`403`	`INSUFFICIENT_SCOPE`	O token não tem o escopo da rota. O cabeçalho WWW-Authenticate lista o que faltou em scope.
`403`	`TOKEN_NOT_ALLOWED`	A ação só existe no painel, com login (compra, pagamento por Pix ou cartão, exclusão de conta).
`404`	`NOT_FOUND`	O recurso não existe ou não é da sua conta.
`422`	`VALIDATION_ERROR`	Corpo ou parâmetros inválidos; details diz quais.
`429`	`RATE_LIMITED`	Limite de requisições excedido. Espere os segundos de Retry-After.

Limites

Cada token pode fazer 60 requisições por minuto. Toda resposta a uma chamada com token traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset (segundos até a janela renovar), para você se ajustar antes de bater no limite. Passou disso, a resposta é 429 RATE_LIMITED com o cabeçalho Retry-After em segundos. Além disso, a API limita as requisições por endereço IP. Se o seu uso precisa de mais, fale com a gente.

Idempotência

Nas escritas que criam algo ou mexem em dinheiro, envie Idempotency-Key com um valor único por operação (um UUID serve; 1 a 255 caracteres ASCII). Se a rede cair e você repetir o pedido com a mesma chave, a API devolve a mesma resposta, com o cabeçalho Idempotent-Replayed: true, em vez de repetir a ação. A resposta fica guardada por 24 horas e só respostas 2xx são guardadas.

400 IDEMPOTENCY_KEY_INVALID: chave vazia, longa demais ou com caracteres inválidos.
409 IDEMPOTENCY_KEY_REUSED: a mesma chave já foi usada com outro corpo ou outra rota.
409 IDEMPOTENCY_IN_PROGRESS: o primeiro pedido com essa chave ainda está rodando; espere e repita.
503 IDEMPOTENCY_UNAVAILABLE: não foi possível garantir a chave agora; repita em alguns segundos.

Aceitam a chave: abrir ticket e responder, pagar fatura com crédito, cancelar e pedir upgrade de serviço, ligar/desligar VPS, e disparar deploy, backup ou domínio de hospedagem. Cada operação aceita está marcada com o parâmetro na referência. Sem o cabeçalho nada muda.

Versão na URL

Toda rota começa em https://api.vixpi.host/api/v1. Dentro da v1 a Vixpi só acrescenta campos e rotas; uma mudança que quebre o seu código sai numa versão nova da URL, e a v1 continua no ar. O que muda fica registrado no changelog.

Próximos passos

Referência da API: cada rota, com o escopo que exige e exemplos de chamada.
Webhooks: receba avisos de fatura paga, serviço ativado e ticket respondido.
Servidor MCP: use a sua conta Vixpi dentro de um assistente de IA.

Baixar a especificação OpenAPI 3.1