Idempotência

Envie Idempotency-Key em POST, PUT, PATCH e DELETE para identificar uma operação de escrita. Gere a chave uma vez (UUID é uma boa opção), guarde-a com a operação e reutilize-a com o mesmo método, caminho, query e corpo. GET não usa o cabeçalho.

Operações financeiras transacionais

Criação/edição/cancelamento nas rotas /sales/operations, /expenses/operations e suas rotas de registro, recebimentos, baixas, pagamentos de fatura, transferências, estornos e abertura operacional exigem UUID em Idempotency-Key. O resultado e os efeitos são gravados na mesma transação do banco.

Repetir a mesma chave com a mesma operação devolve o recibo persistido em meta.command_id. Mesmo após perda da resposta, repita com esse UUID; o efeito não será executado novamente. Outro conteúdo com o mesmo UUID retorna 409. Os recibos financeiros não expiram em 24 horas. A autorização é revalidada antes de cada repetição. Falhas de transação podem retornar 503 com Retry-After.

Campos gerados pelo servidor, como datas de criação, ficam preservados no recibo. O request_id identifica cada tentativa e pode mudar. Esta proteção não é compartilhada entre credenciais diferentes.

As regras abaixo descrevem a proteção genérica dos demais cadastros.

OPERATION_KEY="$(uuidgen)"
curl -X POST "$LIGGA_BASE/v1/customers"   -H "Authorization: Bearer $LIGGA_API_KEY"   -H "Content-Type: application/json"   -H "Idempotency-Key: $OPERATION_KEY"   -d '{"full_name":"Cliente de exemplo"}'

Sem o cabeçalho, uma nova tentativa pode executar a escrita novamente. A chave deve ter de 1 a 255 caracteres e vale dentro da chave de API usada. Duas credenciais diferentes não compartilham a mesma reserva de idempotência.

Estados da operação

Situação	Comportamento
Primeira tentativa	Reserva a operação antes de executar o handler
Operação concluída	Guarda a resposta por 24 horas, incluindo erros 4xx
Mesma operação concluída	Devolve a resposta guardada com Idempotent-Replay: true
Mesma chave, requisição diferente	409 idempotency_conflict
Outra tentativa ainda em andamento	503 com Retry-After: 2; preserve a chave
Resultado indeterminado	503; a operação não é executada novamente automaticamente
Resposta concluída com mais de 24 horas	A proteção expirou; pode ser uma operação nova

Autorização, escopos e acesso são verificados também antes de uma repetição. Revogar acesso não permite recuperar respostas guardadas com a credencial.

Quando o resultado é indeterminado

Uma falha pode acontecer depois de gravar o registro e antes de persistir a resposta. Um erro 5xx, uma reserva abandonada ou uma falha ao guardar a resposta exige reconciliação. Nessas situações, não gere outra chave para repetir a escrita: verifique o registro de origem e procure o suporte com a chave da operação e o request_id.

O sistema bloqueia a reexecução automática de operações indeterminadas. Esse comportamento evita duplicação após falhas, mas não promete que a gravação aconteceu ou deixou de acontecer. Reservas indeterminadas não expiram como respostas concluídas.

Evitar duplicação

• Gere a chave antes do laço de tentativas e persista-a se o processo puder reiniciar.
• Use uma chave nova apenas para uma operação de negócio nova.
• Não derive a chave somente do corpo: duas operações legítimas podem ter conteúdo igual.
• Em 409, confirme qual pedido usou aquela chave antes de corrigir o cliente.

Veja Erros e Limites de requisições.