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_idou equivalente) nos endpoints de criação. - Reenviar um
POSTde criação cria outro registro, mesmo que o corpo seja idêntico ao anterior.
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
Ocode 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:
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:
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.
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ó.