API DE CLIENTE · V1 BETA
API REST para
VPS e servidores dedicados
Faça a gestão dos seus servidores a partir de código: encomende e destrua VPS à hora, execute ações de energia e reinstalações, capture e implemente as suas próprias imagens e pague faturas com crédito.
A API de Cliente da X-ZoneServers (v1, beta pública) disponibiliza 92 operações através de HTTPS, com especificação OpenAPI 3.0, chaves de API com âmbitos definidos e um limite predefinido de 1.000 pedidos por hora por chave. Está incluída em todas as contas sem custo adicional.
92 operações de API1.000 pedidos por hora por chave
A sua primeira chamada
Crie uma chave no painel de cliente em Profile → API Keys e depois pergunte à API quem é.
curl https://my.x-zoneservers.com/api/v1/ \
-H "Authorization: Bearer $XZ_API_KEY"
{ "success": true,
"data": {
"version": "1",
"key": { "scopes": ["read", "services"] },
"rate_limit": { "limit": 1000, "remaining": 999 }
} }01Recursos
O que pode automatizar
A API cobre todo o ciclo de vida de um servidor, da encomenda à fatura, com as mesmas permissões do painel de cliente.
Implementar e destruir
Encomende um VPS com faturação à hora ou mensal, passe user-data de cloud-init e chaves SSH para o primeiro arranque e elimine-o quando o trabalho estiver concluído. A faturação à hora para no momento em que o servidor deixa de existir.
Energia, reinstalação e estatísticas
Inicie, pare, reinicie e reinstale os seus VPS, reponha palavras-passe de root e consulte estatísticas de utilização e de tráfego a partir dos seus scripts de monitorização.
Imagens personalizadas
Capture um VPS como imagem (até 3 por conta) ou registe a sua própria imagem qcow2 ou raw (verificada por SHA-256) e implemente novos servidores a partir dela.
Faturação e utilização
Consulte o saldo de crédito e os custos horários deste mês, liste faturas e faturas pró-forma e pague-as com o crédito — útil para painéis de custos e alertas de orçamento.
Complementos e upgrades
Compre complementos para um serviço existente, como endereços IP adicionais, ou mude-o para um plano maior sem abrir o painel.
Projetos e chaves com âmbito
Agrupe servidores em projetos e emita chaves associadas a um único projeto, para que uma chave de staging nunca consiga ver nem mexer na produção.
02Como funciona
Exemplo: um VPS à hora para um único trabalho de CI
Crie uma máquina de build limpa, execute a pipeline, elimine-a — e pague as horas em que existiu.
Os serviços à hora são cobrados do crédito da sua conta em vez de faturados, por isso mantenha saldo na conta. Envie um cabeçalho Idempotency-Key com cada encomenda: assim, um pedido que tenha excedido o tempo limite pode ser repetido sem criar um segundo servidor.
1. Escolha um plano: liste os produtos com os respetivos preços à hora e mensais.
curl https://my.x-zoneservers.com/api/v1/products \
-H "Authorization: Bearer $XZ_API_KEY"2. Encomende-o com faturação à hora, com um script de primeiro arranque e a sua chave SSH.
curl -X POST https://my.x-zoneservers.com/api/v1/orders \
-H "Authorization: Bearer $XZ_API_KEY" \
-H "Idempotency-Key: ci-run-4812" \
-H "Content-Type: application/json" \
-d '{"productId": "<plan-id>", "billingCycle": "hourly",
"hostname": "ci-4812.example.com", "location": "<location>",
"configOptions": {"os_image_id": "<image-id>",
"ssh_keys": ["ssh-ed25519 AAAA... ci@runner"],
"user_data": "#!/bin/sh\n/opt/ci/run-pipeline.sh"}}'3. Quando o trabalho terminar, elimine o servidor. A faturação para de imediato.
curl -X DELETE https://my.x-zoneservers.com/api/v1/vps/<vps-id> \
-H "Authorization: Bearer $XZ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"immediate": true}'03API
Concebida para scripts e agentes de IA
Quando é um programa, e não uma pessoa, a carregar nos botões, um comportamento previsível conta mais do que o número de endpoints.
Chaves com âmbito
Cada chave tem apenas os âmbitos que conceder — read, services, orders, billing, destructive — além de uma lista opcional de IP autorizados e de uma data de expiração.
Limites de pedidos publicados
1.000 pedidos por hora por chave por predefinição, com o limite indicado nos cabeçalhos X-RateLimit e curtos períodos de espera por servidor nas ações de energia e de reinstalação.
Repetições seguras
As encomendas aceitam um Idempotency-Key e cada recusa devolve um código de erro legível por máquina, para que a automação distinga uma falha que pode ser repetida de uma falha real.
Documentação legível por máquina
Uma especificação OpenAPI 3.0 para geradores de clientes e um guia em Markdown simples que assistentes de programação e agentes de IA podem ler diretamente.
04Relacionado
Vende servidores aos seus próprios clientes?
Esta API de Cliente automatiza a sua própria conta. Para revender com a sua própria marca, adira ao programa de revenda e utilize antes a API de Revenda: preços grossistas com escalões de volume, pedidos assinados com HMAC, webhooks, chaves associadas a clientes e links de consola que os seus clientes abrem sem terem conta connosco.
05Perguntas
FAQ da API
Perguntas frequentes sobre a automatização da X-ZoneServers.
A X-ZoneServers tem uma API?
Sim. A API de Cliente (v1) é uma API REST sobre HTTPS em https://my.x-zoneservers.com/api/v1, com 92 operações que abrangem VPS, servidores dedicados, encomendas, complementos, upgrades, faturas, chaves SSH e imagens personalizadas. Está em beta pública: é suficientemente estável para desenvolver sobre ela, mas os endpoints e o formato das respostas ainda podem mudar.
O acesso à API é gratuito?
Sim. O acesso à API está incluído em todas as contas sem custo adicional; paga apenas os servidores e complementos que encomendar, aos mesmos preços do site e do painel de cliente.
Posso criar e eliminar VPS à hora através da API?
Sim. Faça uma encomenda com o ciclo de faturação à hora, opcionalmente com user-data de cloud-init e chaves SSH, e elimine o VPS quando já não precisar dele. Os serviços à hora são cobrados do crédito da conta e deixam de ser faturados assim que são eliminados.
A API funciona com servidores dedicados?
Em parte. Para servidores dedicados, a API abrange encomendas, complementos, faturas e detalhes do serviço. O controlo de energia, as reinstalações do sistema operativo e a reposição de palavras-passe não estão disponíveis para servidores dedicados, nem através da API nem no painel de cliente.
Como me autentico?
Crie uma chave de API no painel de cliente em Profile → API Keys e envie-a como token Bearer. Escolha os âmbitos ao criá-la e, opcionalmente, limite a sua utilização a endereços IP específicos ou atribua-lhe uma data de expiração. As chaves são mostradas uma única vez e podem ser revogadas a qualquer momento no painel.
Existe uma especificação OpenAPI ou Swagger?
Sim. A especificação OpenAPI 3.0 completa está publicada em https://my.x-zoneservers.com/api/v1/openapi.json, junto à documentação renderizada e a um guia de utilização em Markdown.
Começar
Crie a sua primeira chave de API
Inicie sessão no painel de cliente, abra Profile → API Keys e faça a sua primeira chamada em menos de um minuto. As questões sobre a API chegam diretamente às pessoas que constroem a plataforma.