Construa sua própria superfície de controle

O contrato proposto da versão um separa recursos de catálogo de recursos de conta. Locais e planos suportam configuração. Serviços representam configurações aceitas e estado de cumprimento. Cobrança contém faturas e estado de pagamento. Tickets suportam uma conversa de suporte rastreável. O site implementa seus próprios formulários e espaço de trabalho; os exemplos abaixo são um contrato de design, não rotas para um API público.

O modelo de autenticação preparado usa um token Bearer no cabeçalho Authorization. Escopos somente leitura de catálogo ou serviço não devem poder criar, reconstruir ou cancelar um serviço. Escopos de escrita precisam de uma decisão distinta e de um caminho de revogação. Mantenha as credenciais em um ambiente de servidor privado e nunca incorpore um token secreto em uma página ou pacote do navegador.

GET /v1/services
Authorization: Bearer <private-token>
Accept: application/json

# Proposed scope: services:read

Use um identificador estável para cada recurso e um ID de solicitação para o suporte. Chamadas de mutação devem usar uma chave de idempotência para que uma nova tentativa possa ser reconciliada em vez de criar outro pedido.

POST /v1/services
Idempotency-Key: <one-key-per-request>

{
  "plan_id": "umbra-1",
  "location": "iceland",
  "billing_cycle": "monthly",
  "image": "Ubuntu"
}

Os limites de taxa propostos no nível da conta são 60 leituras por minuto e 20 gravações por minuto, com uma margem de pico de duas vezes esses valores. Uma solicitação rejeitada retorna HTTP 429 com Retry-After; a automação deve aguardar conforme instruído e aplicar backoff. Os erros devem incluir um código estável, uma mensagem legível por humanos e um request_id, com detalhes sensíveis removidos.

{
  "error": {
    "code": "unsupported_location",
    "message": "This plan is not listed in that region.",
    "request_id": "req_example"
  }
}

O modelo de webhook preparado cobre pagamento de fatura, prontidão do serviço, suspensão e atualizações de tickets. A entrega deve ter um ID de evento e um carimbo de data/hora, com uma assinatura HMAC-SHA256 verificada sobre o corpo original da solicitação usando um segredo de assinatura privado. Rejeite assinaturas obsoletas ou inválidas, elimine IDs de evento duplicados e confirme somente depois que o evento for aceito de forma durável. Os consumidores devem tolerar entregas fora de ordem e repetidas.

O caminho proposto do API inclui sua versão principal. Mudanças aditivas devem preservar os clientes existentes; mudanças incompatíveis precisam de uma nova versão e de um aviso de descontinuação de seis meses para a antiga. Disponibilidade, SDKs e um host API de produção devem ser publicados somente após integração e revisão de segurança.

A aplicação de conta tem solicitações de pagamento de endereço fixo e cotações de servidor USD com expiração. A observação de transações é uma integração confiável apenas do servidor; não há endpoint de confirmação público, monitor de blockchain conectado ou worker de provisionamento. A sondagem do navegador lê o estado de pagamento existente do cliente conectado e não pode atestar uma transação. O API público ilustrativo e o contrato de webhook acima permanecem trabalho de design futuro.

• Proteja a lógica de taxa e observação no servidor.
• Associe destinos de recebimento reutilizados a uma transação verificada e uma referência de pedido explícita.
• Mantenha pago e provisionado separados; uma transação verificada não deve criar hardware fictício.