Idempotência - Visor Personal API

Um erro de rede pode esconder se um registro chegou ao Visor. Envie o header Idempotency-Key em todo POST e envie a mesma chave quando repetir. Assim o Visor registra a transação uma única vez.

Idempotency-Key: 2026-10-01-padaria

Como o Visor usa a chave

O Visor guarda a chave na transação. Uma chave é única na conta dela.

Requisição	Resposta
Uma chave nova na conta	O Visor registra a transação e devolve `201` com `idempotent-replayed: false`.
A mesma chave de novo, na mesma conta	O Visor não registra nada e devolve a transação que já tem, com `idempotent-replayed: true`.
A mesma chave com outro `amount`, `type`, `description`, `transacted_at` ou `category_id`	`409 IDEMPOTENCY_CONFLICT`. O Visor não registra nada.
Duas requisições com a mesma chave ao mesmo tempo	O Visor registra uma transação. As duas requisições recebem essa transação.
Sem chave, ou uma chave que não tem de 1 a 128 letras, dígitos ou `-` `_` `.` `:`	`400 IDEMPOTENCY_KEY_INVALID`

Uma repetição devolve a transação como ela está agora. Se você editou a transação depois da primeira requisição, a resposta mostra a edição.
Uma requisição que falha na validação não registra nada, então você pode corrigir o corpo e repetir com a mesma chave.
A chave não expira. Depois que você exclui a transação, a mesma chave registra uma nova.

Escolha uma chave

Use um valor que identifique o evento no seu sistema, como o número de uma nota ou o ID de uma linha da sua planilha. Um UUID aleatório novo por registro também funciona, desde que o script guarde esse valor para as repetições.