Skip to main content
Quando uma chamada à API não responde, reenviar pode criar um registro duplicado. Esta página mostra quais operações você pode reenviar com segurança, por que a API não evita a duplicidade sozinha e como a sua integração pode evitá-la.

O que a API garante

A API não tem idempotência, ou seja, não reconhece uma requisição repetida para devolver o resultado da primeira. Na prática:
  • Não existe header Idempotency-Key. Se você enviar, ele é ignorado.
  • Não existe campo de correlação (external_id, reference, client_id ou equivalente) nos endpoints de criação.
  • Reenviar um POST de criação cria outro registro, mesmo que o corpo seja idêntico ao anterior.
Se uma criação der timeout, reenviar a mesma requisição é a forma mais comum de gerar registros duplicados. Consulte antes de recriar.

O que é seguro reenviar

A tabela mostra, para cada tipo de operação, se repetir a requisição muda o resultado: Atualização e exclusão por id podem ser repetidas porque o id já identifica o alvo. Na criação, o id só existe depois que a API responde.

Por que a deduplicação não acontece sozinha

Três características da API impedem que ela reconheça uma criação repetida.

Cliente e contato não têm chave natural

Clientes e contatos não têm unicidade por documento (CPF/CNPJ), e-mail ou telefone. Dois clientes com o mesmo CNPJ podem coexistir; dois contatos com o mesmo telefone também. A validação checa o formato do dado, não a duplicidade. Por isso, reenviar a criação de um cliente não devolve um erro de “já existe”: cria dois clientes.

O código do projeto é único, mas não serve de chave

O code de um projeto (P-1, P-2, …) é único dentro da empresa, mas é gerado pelo servidor no momento da criação. Você não escolhe o valor e não pode enviá-lo para dizer “crie só se este código ainda não existir”.

Criação rápida de projeto aceita poucos campos

POST /api/management/projects/quick-store aceita exatamente estes campos:
string
required
Nome do projeto.
string
Prefixo do código do projeto.
uuid
Cliente a ser vinculado.
integer
Contato a ser vinculado.
integer
Etapa de funil em que o projeto será criado.
uuid
Modelo de projeto a ser clonado. Quando informado, o projeto nasce como cópia do modelo.
A API descarta sem aviso qualquer outro campo enviado no corpo, inclusive um campo que você usaria para ligar a criação ao seu sistema. Por isso, não há como gravar um identificador seu no projeto durante a criação rápida: guarde essa correspondência do seu lado.

Evitar duplicidade na sua integração

O controle de duplicidade fica com a integração. Os passos abaixo resolvem o caso do timeout com os recursos que a API já oferece.
1

Mantenha uma tabela de correlação

Antes de chamar a API, grave no seu banco uma linha com a chave do seu sistema, o corpo que será enviado e o estado pendente. Você precisa saber que tentou, mesmo que a resposta nunca chegue.
2

Chame a API

Ao receber a resposta, grave o id (e o code, quando houver) devolvido pela Olie na mesma linha e marque como concluído.
3

Em caso de timeout, consulte antes de recriar

Um timeout não significa que a criação falhou: significa que você não sabe o resultado. Antes de reenviar, busque os dados que você acabou de enviar. Se o registro existir, guarde o id e encerre. Se não existir, reenvie.
4

Reconcilie periodicamente

Rode uma rotina que procure linhas pendentes antigas e as resolva pela consulta. Isso cobre o caso em que o próprio processo caiu antes de gravar a resposta.

Endpoints para a verificação

Use a busca avançada para procurar o registro antes de recriar: Exemplo de verificação por nome antes de recriar um projeto:
Se meta.total for maior que zero, o projeto já existe: não crie outro. O formato dos filtros e operadores está em Busca avançada.
Para a verificação ser confiável, busque por um campo que você controla e que não muda. Por exemplo, monte o nome do projeto a partir da sua chave interna.

Se a duplicidade acontecer

A API não desfaz a criação a mais. Trate o registro duplicado pela plataforma ou pela própria integração:
  • Projetos duplicados: mescle ou exclua o projeto a mais.
  • Clientes e contatos duplicados: exclua o registro a mais ou junte os dados em um só.
Antes de excluir, confira o que já foi vinculado ao registro duplicado. Projetos, anexos e respostas de formulário ligados a ele são excluídos junto.