KernelHost API de Revenda

O que a API de Revenda faz

A API de Revenda da KernelHost expõe exatamente as ações de pedido e gestão que você executaria clicando no portal do cliente. Permite automatizar o seu negócio de revenda, integrar produtos KernelHost no seu próprio frontend ou sistema de faturamento, e manter controle total sobre escopos, limites de taxa e lista de IPs permitidos por chave API.

Cada chamada é assinada por HMAC-SHA256, protegida contra replay, processada de forma idempotente (obrigatório para pedidos), registrada em um log de auditoria à prova de adulteração e, opcionalmente, confirmada via webhook. Pagamentos são debitados primeiro do seu saldo de crédito e depois do cartão cadastrado. Novos cartões só podem ser adicionados no portal do cliente (3-D Secure 2 obrigatório).

https://www.kernelhost.com/cp/kh_reseller_api/v1

Sumário

• Início rápido em 5 minutos
• Autenticação (HMAC-SHA256)
• Referência de endpoints
• Códigos de erro (RFC 7807)
• SDKs: PHP, Node.js, Python, Go
• Segurança e boas práticas
• Changelog

O que você pode fazer

• Consultar produtos e preços (rootservers KVM, dedicados, webspace, Minecraft, VPN, tráfego ilimitado).
• Realizar pedidos (Idempotency-Key protege contra cobranças duplicadas em retentativas de rede).
• Listar seus próprios serviços, verificar status, executar ações (iniciar, parar, reiniciar, reinstalar, suspender, encerrar).
• Ler credenciais apenas dos seus próprios serviços (escopo separado, auditado, e-mail de confirmação opcional por acesso).
• Obter faturas, consultar saldo de crédito, baixar PDFs de faturas.
• Registrar um webhook por chave API para eventos de pedido, serviço e fatura (esquema de assinatura compatível com Stripe).

Design de segurança máxima

A API foi projetada partindo do pressuposto de que cada chamada tem impacto financeiro direto e pode expor credenciais sensíveis de servidor. A linha de base de segurança está, portanto, bem acima dos padrões REST habituais.

• Assinatura HMAC-SHA256 da requisição sobre método, caminho, timestamp, nonce e hash do corpo. Comparação em tempo constante.
• Proteção contra replay: janela de timestamp +-300s, cache de nonce de uso único por 600s.
• Segredos são persistidos exclusivamente como texto cifrado AES-256-GCM. O texto claro existe transitoriamente em memória apenas para verificação da assinatura. A chave mestra fica fora do banco de dados.
• Escopos granulares por chave API. Escopos perigosos (read:credentials, write:orders) precisam ser ativados explicitamente. O padrão é somente leitura.
• Isolamento de dados no nível do banco: cada consulta filtra rigidamente pelo id da sua conta. Acesso entre tenants é impossível por design.

Exemplo: consultar sua própria conta

A requisição é assinada por completo com o seu segredo. O segredo nunca sai da memória do cliente; apenas a assinatura é transmitida.

TS=$(date +%s)
NONCE=$(openssl rand -hex 16)
BODY_SHA256=$(printf '' | openssl dgst -sha256 -hex | awk '{print $2}')
SIG_INPUT=$(printf 'GET\n/v1/me\n%s\n%s\n%s' "$TS" "$NONCE" "$BODY_SHA256")
SIG=$(printf '%s' "$SIG_INPUT" | openssl dgst -sha256 -hmac "$KH_SECRET" -hex | awk '{print $2}')

curl https://www.kernelhost.com/cp/kh_reseller_api/v1/me \
  -H "KH-Key: $KH_KEY" \
  -H "KH-Timestamp: $TS" \
  -H "KH-Nonce: $NONCE" \
  -H "KH-Signature: $SIG"

Perguntas frequentes

Quem pode usar a API de Revenda?

Todo cliente KernelHost existente pode criar uma chave em "Minha Conta → API de Revenda" com rótulo, escopos e lista de IPs permitidos próprios. Nenhum contrato de revenda separado é exigido: todo produto listado publicamente está disponível via API.

Como os pedidos são pagos?

Pedido: primeiro o saldo de crédito, depois o método de pagamento cadastrado (cartão de crédito com 3-D Secure 2). Se o pagamento for recusado ou não houver cartão registrado, a API retorna HTTP 402 "Payment Required" com um motivo específico (insufficient_credit_and_no_card, card_declined, card_expired). O pedido fica em "pending payment" por 24h e depois é cancelado automaticamente.

Posso ler senhas de serviços pela API?

Sim, mas apenas dos seus próprios serviços e apenas com o escopo explícito read:credentials, que precisa ser habilitado na criação da chave API. Cada acesso gera uma entrada no log de auditoria credentials.read; sob solicitação, você ainda pode receber um e-mail de confirmação no endereço da sua conta, tornando impossível o uso indevido silencioso.

O que acontece se meu segredo for comprometido?

Você rotaciona o segredo com um único clique no portal do cliente. O segredo antigo é invalidado imediatamente, todas as sessões em execução são revogadas. Em falhas de autenticação suspeitas (5 em 10 minutos), o sistema bloqueia a chave automaticamente por 15 minutos e envia um e-mail.