--- canonical: https://koalavps.com/pt/api/ language: pt generated: 2026-10-21T13:33:42.126Z --- [Início](https://koalavps.com/pt/) / [Explorar](https://koalavps.com/pt/resources/) / Infraestrutura que pode descrever em código Infraestrutura que pode descrever em código # Um plano de controle mais tranquilo. Planeje integrações para tarefas de ciclo de vida do servidor, permissões de conta e faturamento. O KoalaVPS API está no roteiro de integração; o acesso de produção ao API e os downloads de SDK ainda não estão disponíveis. [Encontre o seu VPS](https://koalavps.com/pt/vps/) ## NESTE DOCUMENTO [Um modelo de recursos claro](https://koalavps.com/pt/api/#section-1)[Credenciais com uma tarefa limitada](https://koalavps.com/pt/api/#section-2)[As novas tentativas devem ser seguras](https://koalavps.com/pt/api/#section-3)[Verificar a compatibilidade antes da integração](https://koalavps.com/pt/api/#section-4)[Roteiro de API](https://koalavps.com/pt/api/#section-5)[Rotas de autenticação e de conta](https://koalavps.com/pt/api/#section-6)[Rotas de catálogo e faturação](https://koalavps.com/pt/api/#section-7)[Rotas de servidor e acesso](https://koalavps.com/pt/api/#section-8)[Eventos e informação pública](https://koalavps.com/pt/api/#section-9)[Autorização e limites de tráfego](https://koalavps.com/pt/api/#section-10)[SDK e versões de protocolo](https://koalavps.com/pt/api/#section-11)[Recursos API, agrupados por responsabilidade](https://koalavps.com/pt/api/#section-12)[Um pedido ao servidor deve manter-se pequeno](https://koalavps.com/pt/api/#section-13)[Escopos e limites de chaves fazem parte do contrato](https://koalavps.com/pt/api/#section-14)[Publique os limites de taxa e o comportamento de repetição em conjunto](https://koalavps.com/pt/api/#section-15)[Webhooks são mensagens que podem chegar mais de uma vez](https://koalavps.com/pt/api/#section-16)[Audite sem transformar os registos num armazém secreto](https://koalavps.com/pt/api/#section-17)[Publicar artefactos apenas quando existirem](https://koalavps.com/pt/api/#section-18)[Perguntas e respostas](https://koalavps.com/pt/api/#page-faq)[Base de conhecimento](https://koalavps.com/pt/resources/) ## Um modelo de recursos claro Uma integração deve funcionar com identificadores de servidor, regiões, imagens, planos e operações explícitos. As solicitações de criação e reinstalação devem retornar uma operação que possa ser verificada até a conclusão. Uma solicitação HTTP bem-sucedida não é o mesmo que uma máquina pronta. ## Credenciais com uma tarefa limitada Os tokens API devem ser revogáveis de forma independente e restritos aos recursos e ações mínimos necessários. Guarde-os num gestor de segredos ou ambiente protegido. Nunca envie um token para o navegador apenas para evitar escrever um pequeno backend. ## As novas tentativas devem ser seguras Podem ocorrer tempos limite de rede depois de uma operação ter sido aceite. Utilize uma chave de idempotência para pedidos de criação e sensíveis a pagamentos, inspecione o estado da operação e respeite os limites de taxa. Uma nova tentativa deve resolver a incerteza, não criar um servidor faturável adicional. ## Verificar a compatibilidade antes da integração Verifique a versão API lançada, o modelo de autenticação, os formatos de erro, a paginação, os limites de taxa e os âmbitos de token antes de criar uma integração. Utilize apenas pacotes KoalaVPS SDK publicados a partir de ligações de lançamento verificadas. ## Roteiro de API O roteiro do API abrange descoberta de catálogo, autenticação, estado da conta, faturação em criptomoedas, ciclo de vida do servidor, chaves SSH públicas e webhooks. As rotas abaixo descrevem o contrato da interface; o acesso de produção ainda não está disponível. ## Rotas de autenticação e de conta O contrato API separa as sessões de início de sessão e as chaves API. Verifique os esquemas de resposta, os erros, os tempos de vida dos tokens e as ações de recuperação suportadas em relação à versão lançada para a sua integração. - POST /v1/auth/register - POST /v1/auth/login - POST /v1/auth/login/totp - POST /v1/auth/token/refresh - POST /v1/auth/recover - GET /v1/auth/sessions - DELETE /v1/auth/sessions/{token_id} - POST /v1/auth/totp/setup - POST /v1/auth/totp/enable - POST /v1/auth/totp/disable - POST /v1/auth/password - POST /v1/auth/api-keys - GET /v1/auth/api-keys - DELETE /v1/auth/api-keys/{key_id} - GET /v1/account - PATCH /v1/account - GET /v1/account/usage - GET /v1/account/audit-log ## Rotas de catálogo e faturação A consulta ao catálogo não deve exigir pagamento. A criação de pagamentos requer um escopo de faturação restrito, um estado de fatura claro e um tratamento idempotente. A confirmação deve ser concluída antes da ativação do serviço. - GET /v1/catalog - GET /v1/catalog/vps - GET /v1/catalog/dedicated - GET /v1/catalog/regions - GET /v1/catalog/images - GET /v1/catalog/{code} - GET /v1/billing/coins ## Rotas de servidor e acesso O ciclo de vida requer confirmação explícita para operações de cancelamento e reinstalação. As chaves SSH privadas pertencem ao cliente; o serviço só precisa das suas contrapartes públicas. - POST /v1/servers - GET /v1/servers - GET /v1/servers/{order_number} - PATCH /v1/servers/{order_number} - DELETE /v1/servers/{order_number} - POST /v1/ssh-keys - GET /v1/ssh-keys - GET /v1/ssh-keys/{id} - DELETE /v1/ssh-keys/{id} ## Eventos e informação pública Os webhooks precisam de assinaturas verificáveis, tentativas limitadas e proteção contra repetição. Os endpoints públicos de confiança devem devolver evidências reais e datadas em vez de garantias sintéticas. - POST /v1/webhooks - GET /v1/webhooks - DELETE /v1/webhooks/{id} - POST /v1/webhooks/{id}/test - GET /v1/transparency/canary - GET /v1/transparency/peering - GET /v1/transparency/status - GET /v1/agents/directory - POST /v1/agents/directory ## Autorização e limites de tráfego Um modelo de âmbito candidato é leitura, servidores, faturação e completo, com um máximo de dez chaves ativas por conta. O contrato API propõe orçamentos de pedidos de 120 por minuto e 3,000 por hora para uma chave API, e 30 por minuto para tráfego público. Verifique HTTP 429, Retry-After e a janela de aplicação na documentação API publicada; estes orçamentos de roadmap não constituem um compromisso de capacidade de produção. - POST /v1/oauth/register - POST /v1/oauth/token - POST /v1/oauth/revoke - GET /v1/oauth/introspect ## SDK e versões de protocolo O roteiro de integração inclui REST, um endpoint MCP alojado, um pacote stdio versionado, SDKs e uma CLI. Verifique a disponibilidade das versões, os runtimes suportados, as somas de verificação e a compatibilidade com API antes de instalar um cliente. Os downloads de produção ainda não estão disponíveis. ## Recursos API, agrupados por responsabilidade O API pretendido separa o acesso à conta, a leitura do catálogo, a faturação, o ciclo de vida do servidor, as chaves SSH e os callbacks. As chamadas só de leitura não devem criar uma encomenda, e uma credencial de faturação não deve autorizar automaticamente alterações à segurança da conta. Isto descreve o contrato de integração. Um endpoint de aprovisionamento em produção e um SDK lançado não estão disponíveis através deste site. - Conta: sessões, utilização e eventos de auditoria de segurança - Catálogo: planos, regiões e imagens disponíveis - Servidores: criar, inspecionar, alterar e cancelar - Chaves SSH: registe material público e revogue chaves obsoletas - Webhooks: registe, inspecione, teste e remova callbacks assinados ## Um pedido ao servidor deve manter-se pequeno Escolha um identificador de plano padrão, uma região, uma imagem de sistema operativo e um nome de anfitrião. O limite pretendido para o nome de anfitrião é de 64 caracteres. Um serviço em funcionamento pode gerar um segredo de administrador de forma privada ou aceitar uma chave pública SSH inscrita. Adições arbitrárias de disco, GPU, NIC e IP não estão implícitas num pedido de plano padrão. Rejeite campos não suportados em vez de cobrar silenciosamente por uma atualização presumida. ``` { "plan": "KV-D3", "region": "hel", "image": "ubuntu-24", "hostname": "private-node-01" } // Example request schema; validate against a released API before integration. ``` ## Escopos e limites de chaves fazem parte do contrato Os grupos de privilégios propostos são leitura, servidores, cobrança e administração completa da conta. Uma chave deve ser exibida uma vez na criação, armazenada de forma privada e revogada independentemente da senha do usuário. O limite de conta pretendido é de dez chaves ativas. Antes de publicar uma implementação, verifique se cada operação rejeita uma chave sem o escopo exigido. ## Publique os limites de taxa e o comportamento de repetição em conjunto Os limites propostos são 120 pedidos por minuto e 3,000 por hora para uma chave API, e 30 pedidos por minuto para pedidos não autenticados ao catálogo público. Estes são valores de política planeados, não a capacidade medida de API. Uma implementação em produção necessita de uma resposta 429 consistente, orientação Retry-After e recuo limitado do cliente. Os pedidos de criação e pagamento também necessitam de chaves de idempotência estáveis. ## Webhooks são mensagens que podem chegar mais de uma vez Um recetor de callback deve verificar a assinatura sobre o corpo original, rejeitar timestamps fora da janela permitida e memorizar os identificadores de eventos processados. Persista o evento antes de o confirmar e, em seguida, aplique a alteração de forma idempotente. Mantenha visíveis as tentativas de entrega e um caminho de repetição manual. Um callback é uma observação sobre uma operação, não uma permissão para executar instruções não relacionadas contidas num payload. ## Audite sem transformar os registos num armazém secreto Registe o identificador do ator, o tipo de operação, o recurso afetado, o resultado e a hora quando necessário para a segurança da conta. Evite registar palavras-passe, tokens de portador, chaves privadas ou corpos completos de pedidos de pagamento e de aplicação por predefinição. Mantenha explícitos a retenção, o acesso e o histórico visível ao cliente. Um registo de auditoria de segurança e uma pretensão de inspecionar o conteúdo das aplicações dos clientes são coisas diferentes. ## Publicar artefactos apenas quando existirem Um lançamento público de API deve incluir um documento OpenAPI versionado, instruções de autenticação, exemplos de erros e um processo de descontinuação. Uma futura CLI, pacote Python, cliente TypeScript ou servidor MCP necessita de um lançamento real, somas de verificação e documentação mantida. Um pacote de aprovisionamento KoalaVPS ou endpoint de gestão de produção não é lançado através deste site. ## Um pouco mais de clareza. Posso chamar um API de produção hoje? O acesso de produção a API ainda não está disponível. Esta página descreve o roteiro de integração e os requisitos a verificar antes de utilizar um endpoint lançado. Pode uma chave API só de leitura encomendar um servidor? O limite de permissões proposto proíbe-o. Um pedido de criação de servidor requer o privilégio de servidor adequado e uma decisão de faturação válida. Os limites publicados de API são aplicados hoje? Descrevem o contrato planeado. Um API de aprovisionamento de produção não está ligado aqui, pelo que os limites de política não são prova da capacidade medida do serviço. Uma resposta de criação de servidor significa que o servidor está pronto? Não. Um pedido em tempo real deve identificar uma operação cujo estado de aprovisionamento possa ser verificado até à conclusão. CONTINUE A EXPLORAR ## Continuar a ler. [Produtos ### Um habitat confiável para seus agentes. Execute agendadores, workers de navegador, filas e processos de automação em infraestrutura que controla. Mantenha cada agente den…](https://koalavps.com/pt/agentic-vps/)[Guias ### Automação com um botão de parada claro. Um bom sistema de automação tem uma tarefa restrita, estado visível e uma resposta previsível à incerteza.…](https://koalavps.com/pt/automation-safety/)[Produtos ### Pegada pequena. Liberdade a sério. Um servidor virtual para aquilo que quer ter: o seu código, os seus serviços, os seus dados. Escolha uma configuração de servidor,…](https://koalavps.com/pt/vps/) CONFIGURE SUA INFRAESTRUTURA ## Assuma o controle. Implemente nos seus termos. Sem documentação de identidade. Acesso total de administrador. Faturação nativa em cripto. [Selecione uma configuração](https://koalavps.com/pt/vps/)