メインコンテンツまでスキップ

Concorrência e idempotência

Repetindo um POST sem criar duplicados: Idempotency-Key​

Quando uma requisição demora ou a conexão cai, você não sabe se o item foi criado. Para repetir com segurança, envie o cabeçalho Idempotency-Key nos POST:

curl -X POST https://api.validades.com/v1/batches \
-H "Authorization: Bearer vld_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1234-lote-1" \
-d '{"product_id": "…", "exp_date": "2026-12-31", "amount": 12}'
SituaçãoResposta
Primeira vezprocessada normalmente
Mesma chave e mesmo corpo, depois de concluídaa mesma resposta da primeira vez, com o cabeçalho Idempotent-Replayed: true. Nada é criado de novo
Mesma chave, com a primeira ainda em processamento409 idempotency_in_progress, com Retry-After: 1
Mesma chave com outro corpo ou outra rota422 idempotency_key_reused

Regras:

  • a chave tem até 255 caracteres: letras, números e _ - : .;
  • é guardada por 24 horas e vale só para a mesma chave de API;
  • respostas 5xx e 429 não são guardadas, então você pode repetir;
  • vale só para POST. PATCH e DELETE já podem ser repetidos sem efeito duplicado.

Use um valor que identifique a operação no seu sistema, por exemplo o id do pedido e do item.

Alternativa: envie o campo id (um UUID gerado por você) no POST. Se o item já existir, a resposta é 409 conflict, e nada é duplicado.

Não sobrescrevendo alterações: ETag e If-Match​

A mesma informação pode ser alterada ao mesmo tempo pela sua integração e por alguém da equipe no aplicativo. Para não apagar a alteração do outro sem perceber:

  1. Ao ler um item (GET /v1/.../{id}), guarde o cabeçalho ETag da resposta, por exemplo W/"a1b2c3…". POST e PATCH também devolvem o ETag novo.
  2. Ao alterar ou excluir, envie o valor no cabeçalho If-Match.
  3. Se o item mudou desde a leitura, a resposta é 412 (precondition_failed), e o cabeçalho ETag traz a versão atual. Leia o item de novo e decida o que fazer.
curl -X PATCH https://api.validades.com/v1/batches/ID_DO_LOTE \
-H "Authorization: Bearer vld_live_SUA_CHAVE" \
-H "Content-Type: application/json" \
-H 'If-Match: W/"a1b2c3d4e5"' \
-d '{"amount": 10}'

If-Match: * aceita qualquer versão. Sem If-Match, a alteração é sempre aplicada.

Economizando requisições: If-None-Match​

Ao consultar um item que você já tem, envie o ETag guardado em If-None-Match. Se nada mudou, a resposta é 304 Not Modified, sem corpo.

GET /v1/products/{id}?include=batches não tem ETag, porque a alteração de um lote não muda a versão do produto.

O aplicativo funciona offline​

Os aparelhos da equipe podem ficar sem internet e enviar as alterações depois. Quando a mesma informação é alterada pela API e por um aparelho antes da sincronização, pode prevalecer a última alteração recebida. Para dados que a equipe também altera no aplicativo, prefira usar If-Match.