Idempotência

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.

Aspecto	Detalhe
Cabeçalho	`Idempotency-Key`
Formato	1–255 caracteres ASCII imprimíveis (UUID4 recomendado)
Aplica-se a	Rotas de escrita `POST` / `PUT` / `PATCH` / `DELETE`
Janela de cache	24 horas a partir da resposta original
Marcador de reenvio	Resposta inclui `Idempotency-Replayed: true`
Reenvio simultâneo	`409 Conflict` enquanto a primeira requisição ainda está em andamento
Respostas `5xx`	NÃO são cacheadas — seguro renviar com a mesma chave
`GET`/`HEAD`	Cabeç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”.

Comece aqui

Autenticação

Convenções da API

Recursos

Como funciona

Escolhendo uma chave

Exemplo com curl

Ressalvas

​Como funciona

​Escolhendo uma chave

​Exemplo com curl

​Ressalvas

Como funciona

Escolhendo uma chave

Exemplo com curl

Ressalvas