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ção | Resposta |
|---|---|
| Primeira vez | processada normalmente |
| Mesma chave e mesmo corpo, depois de concluída | a mesma resposta da primeira vez, com o cabeçalho Idempotent-Replayed: true. Nada é criado de novo |
| Mesma chave, com a primeira ainda em processamento | 409 idempotency_in_progress, com Retry-After: 1 |
| Mesma chave com outro corpo ou outra rota | 422 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
5xxe429não são guardadas, então você pode repetir; - vale só para
POST.PATCHeDELETEjá 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:
- Ao ler um item (
GET /v1/.../{id}), guarde o cabeçalhoETagda resposta, por exemploW/"a1b2c3…".POSTePATCHtambém devolvem oETagnovo. - Ao alterar ou excluir, envie o valor no cabeçalho
If-Match. - Se o item mudou desde a leitura, a resposta é
412(precondition_failed), e o cabeçalhoETagtraz 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.