Desenvolvedores · Confiabilidade
Retentativas seguras sem duplicar operações.
Idempotência faz requisições repetidas com a mesma intenção produzirem um único efeito. É essencial quando rede, timeout ou resposta incerta levam o cliente a tentar novamente.
Visão executiva
O essencial antes de operar
Intenção atendida: Implementar idempotência para repetir requisições após timeout sem duplicar cobranças, transferências ou reembolsos.
- Timeout não revela se o servidor executou.
- A mesma intenção reutiliza a mesma chave.
- Payload diferente com a mesma chave é conflito.
- Resultado original é recuperado durante a retenção.
- Idempotência não substitui autorização ou conciliação.
01
O que esta solução organiza
Idempotência faz requisições repetidas com a mesma intenção produzirem um único efeito. É essencial quando rede, timeout ou resposta incerta levam o cliente a tentar novamente. O desenho da jornada separa claramente solicitação, validação, confirmação e conciliação. Assim, cada participante sabe o que precisa ocorrer antes de avançar.
Proteção contra duplicidade acidental
Recuperação previsível após timeout
Rastreabilidade entre tentativa e resultado
02
Como funciona, etapa por etapa
- 01
Gere uma chave única por intenção
- 02
Reutilize a mesma chave somente na retentativa
- 03
Compare a resposta com a operação original
- 04
Crie nova chave para uma nova intenção
03
Qualidade operacional por padrão
Antes de confirmar qualquer operação, revise titularidade, valores, moeda ou ativo, rede quando aplicável, prazos, tarifas e destinatários. Dados enviados por canais não verificados não devem ser usados para transferências.
A Digittro apresenta estas informações para explicar o produto, e não como promessa de aprovação, rentabilidade, disponibilidade contínua ou aconselhamento financeiro, jurídico ou tributário.
03
Por que a repetição é inevitável
Em uma falha de rede, o cliente pode não saber se a requisição chegou, se foi executada ou se apenas a resposta se perdeu. Reenviar sem proteção pode criar duas cobranças, dois reembolsos ou duas transferências. Não reenviar pode deixar o pedido incompleto. A idempotência resolve essa ambiguidade para uma mesma intenção.
Antes da primeira tentativa, o integrador gera uma chave aleatória e a associa à ação de negócio. Se ocorrer timeout, repete método, rota, chave e payload. Uma ação realmente nova recebe outra chave, mesmo que valores sejam iguais.
04
Contrato da chave e do payload
O servidor registra chave, titular, endpoint, impressão do payload, estado e resultado. Repetição compatível recupera a resposta original ou informa processamento. A mesma chave com parâmetros diferentes produz conflito, pois não é seguro adivinhar qual intenção prevalece.
Escopo inclui credencial ou merchant para impedir colisão entre clientes. Retenção tem prazo documentado; após expirar, o integrador não presume que a chave antiga ainda protege. Chaves não carregam dados pessoais nem segredos em texto legível.
05
Concorrência, falhas e reconciliação
Duas chamadas simultâneas com a mesma chave exigem trava ou restrição única atômica. Uma vence a criação; a outra observa o mesmo registro. Gravar a chave depois do efeito financeiro abre uma janela de duplicidade e deve ser evitado por transação ou desenho equivalente.
Falhas de validação podem ser retornadas de modo determinístico; erros transitórios seguem regra documentada. Se o estado ficar indeterminado, o cliente consulta o recurso por referência antes de criar nova intenção.
Idempotência protege o comando, enquanto webhooks idempotentes protegem eventos e conciliação detecta diferenças. As três camadas trabalham juntas. Métricas monitoram conflitos, repetição, tempo em processamento e chaves expiradas para identificar integrações com comportamento inadequado.
A resposta recuperada mantém código, corpo e identificadores compatíveis com a primeira execução, deixando claro quando é replay. Dados temporais que mudariam naturalmente não devem induzir o cliente a interpretar uma nova operação. Suporte usa chave, request ID e referência do negócio para localizar o efeito sem solicitar credenciais ou payloads sensíveis.
Comparativo
Idempotência: repetição sem duplicidade
| Dimensão | Contrato necessário | Evidência |
|---|---|---|
| Requisição | Método, rota, campos e autenticação | Exemplo e schema |
| Resposta | Status, corpo e identificador | Contrato versionado |
| Falha | Código, detalhe e possibilidade de retry | Erro estruturado |
| Repetição | Idempotência e deduplicação | Chave e resultado original |
| Operação | Logs, métricas e correlação | Request ID e auditoria |
A documentação pública deve descrever somente recursos realmente implementados e disponíveis no ambiente correspondente.
Checklist
Antes de solicitar uma cotação
- 01
Definir caso de uso e ambiente.
- 02
Criar credencial com privilégio mínimo.
- 03
Validar contrato e exemplos oficiais.
- 04
Implementar timeout, retry e idempotência.
- 05
Tratar erros por código e estado.
- 06
Validar eventos e assinaturas no servidor.
- 07
Monitorar request IDs, latência e falhas.
Vocabulário
Termos usados nesta página
- API
- Interface programática com contrato documentado.
- Endpoint
- Combinação de método e rota para um recurso.
- Request ID
- Identificador usado para correlacionar uma requisição.
- Idempotência
- Repetição segura que preserva o efeito esperado.
- Webhook
- Evento enviado para um endpoint do integrador.
- Escopo
- Conjunto de permissões associado à credencial.
Fontes
Referências institucionais
Links externos usados para contextualização normativa e educação financeira. Nenhum direciona a concorrentes.
04
Perguntas frequentes
A chave é o ID do cliente?+
Não. Ela identifica uma intenção de operação específica e não deve ser reutilizada indefinidamente.
Quanto tempo a chave é guardada?+
A janela depende da política da API e deve ser considerada pela integração.
Idempotência substitui conciliação?+
Não. Ela evita efeitos duplicados, mas conciliação e webhooks continuam necessários.