Saltar para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.vmarea.com/llms.txt

Use this file to discover all available pages before exploring further.

A API pública da VMArea suporta retentativas idempotentes no estilo Stripe em todo endpoint de escrita — assim, uma queda de rede ou travamento do cliente nunca deixa você na dúvida se aquele POST realmente foi executado.

​
Como funciona

Envie um cabeçalho Idempotency-Key em qualquer requisição POST, PUT, PATCH ou DELETE para /api/public/v1/*. Reenvios da mesma chave pelo mesmo token de API retornam a resposta original — mesmo status, mesmo corpo — sem re-executar o endpoint.
AspectoDetalhe
CabeçalhoIdempotency-Key
Formato1–255 caracteres ASCII imprimíveis (UUID4 recomendado)
Aplica-se aRotas de escrita POST / PUT / PATCH / DELETE
Janela de cache24 horas a partir da resposta original
Marcador de reenvioResposta inclui Idempotency-Replayed: true
Reenvio simultâneo409 Conflict enquanto a primeira requisição ainda está em andamento
Respostas 5xxNÃO são cacheadas — seguro renviar com a mesma chave
GET/HEADCabeçalho ignorado (esses métodos já são idempotentes por natureza)

​
Escolhendo uma chave

Gere um novo valor por operação lógica — normalmente um UUID4 — e reutilize-o apenas ao reenviar exatamente aquela requisição. Use chaves diferentes para operações diferentes; use a mesma chave para retentativas da mesma operação.

​
Exemplo com curl

KEY=$(uuidgen)

curl -X POST https://api.vmarea.com/api/public/v1/vms \
  -H "x-api-key: $VMAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"name":"web-01","planId":"plan_xxx","regionId":"sin-1","osTemplateId":"tpl_ubuntu_24"}'

# Queda de rede? Reenvie a *mesma* chave — você receberá a resposta original
# de volta, com `Idempotency-Replayed: true` nos cabeçalhos.
curl -X POST https://api.vmarea.com/api/public/v1/vms \
  -H "x-api-key: $VMAREA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $KEY" \
  -d '{"name":"web-01","planId":"plan_xxx","regionId":"sin-1","osTemplateId":"tpl_ubuntu_24"}'

​
Ressalvas

A chave de cache é (usuário do token de API, Idempotency-Key). Um token diferente da mesma conta é tratado como um chamador diferente.
  • Os corpos das requisições não são verificados por checksum — enviar um corpo diferente com uma chave reutilizada ainda retorna a resposta original. Mantenha uma chave por operação.
  • Downloads binários (faturas em PDF etc.) estão fora do escopo: reenvios desses endpoints simplesmente re-executam a operação.
  • A idempotência é melhor esforço. Se o nosso cache ficar brevemente indisponível, deixamos as requisições passar em vez de falhar; nessa janela rara, uma retentativa pode produzir um efeito colateral duplicado. Combine este cabeçalho com padrões defensivos normais para semântica verdadeira de “no máximo uma vez”.