Entendimento sobre a duplicidade de cadastro por CNPJ via API com cliente inativo

Visão geral

A verificação de duplicidade de CNPJ ocorre de forma nativa quando o cadastro é efetuado diretamente pela interface do sistema ou através da página de checkout. Nas integrações realizadas via API, o sistema permite a criação de novos registros mesmo que exista um cadastro prévio com o mesmo CNPJ em status inativo.

Quando usar este artigo

Utilize este guia para compreender o comportamento da plataforma em cadastros efetuados via API e orientar os ajustes necessários nas regras de validação da integração para evitar a duplicidade de documentos.

Sintoma ou cenário

Identificação de dois cadastros no sistema com o mesmo número de CNPJ, sendo o cadastro anterior mantido como inativo e o novo registro gerado a partir de uma chamada de API.

Benefício para o usuário ou operação

Compreensão clara das diferenças de validação entre cadastros manuais, checkout e requisições de API;
Orientação técnica para adequação da rotina de integração e prevenção de cadastros paralelos;
Manutenção do saneamento da base de dados e organização do histórico de clientes.

Onde acessar / contexto de uso

Logs de alteração do cadastro de clientes, painel de configurações de integração e documentação da API do Superlógica Assinaturas.

Pré-requisitos (Antes de começar)

Perfil Exato: Clientes - Alteração (1071), Logs - Consulta (1270) ou Configurações - Consulta (1060).
Recursos Sistêmicos: Acesso aos logs de alteração e ao ambiente de gerenciamento das chaves de API.
Insumos e Dados Técnicos: CNPJ do cliente, ID do cadastro antigo (inativo), ID do novo cadastro e documentação técnica da integração.

Causas prováveis

Envio de requisição de criação de cliente via API sem consulta prévia à base de dados, visto que a trava nativa do sistema para CNPJ em cadastro inativo abrange apenas cadastros efetuados na interface e no checkout.

Como fazer ou corrigir

O sistema valida a duplicidade de CNPJ automaticamente na interface e no checkout. Para chamadas via API, a responsabilidade de consultar a existência prévia do documento antes de disparar a criação do registro é da aplicação integradora.

Acesse o menu de consulta de clientes e pesquise pelo CNPJ para localizar o cadastro inativo e o novo cadastro gerado.
Acesse o histórico/log de alterações do cadastro para confirmar que a criação foi efetuada via API.
Consulte a documentação da API do Superlógica Assinaturas para identificar os endpoints de busca de clientes por CPF/CNPJ.
Ajuste a regra de negócio no código da sua integração para efetuar uma busca prévia na API antes de enviar uma requisição de novo cadastro.
Configure a integração para realizar a reativação ou atualização do cadastro existente caso a busca prévia retorne um cliente inativo.
Realize o saneamento da base no sistema, inativando ou ajustando o registro duplicado gerado indevidamente.

Resultado esperado

Lógica da integração ajustada para verificar o CNPJ antes do envio, impedindo a geração de cadastros duplicados via API.

Quando escalar

Escale ao suporte técnico caso a duplicidade de CNPJ em cliente inativo ocorra em cadastros efetuados manualmente na interface do sistema ou pelo checkout público.

Informações que devem ser reunidas antes do escalonamento

Nome da licença;
CNPJ associado aos cadastros;
ID do cliente inativo;
ID do cliente recém-criado;
Captura de tela (print) do log de alteração evidenciando o canal de criação.

Regras importantes / Observações

A restrição de duplicidade para CNPJ inativo é aplicada exclusivamente nos fluxos de entrada manual e checkout público. Requisições recebidas via API dependem do tratamento da aplicação integradora para verificar e gerenciar clientes inativos antes da inserção.

Problemas comuns e como resolver

Problema: A API cadastrou um cliente cujo CNPJ já constava no sistema. Causa provável: O registro antigo estava inativo e a chamada de API foi disparada sem realizar a checagem prévia de existência do documento. Ação recomendada: Atualize a rotina do sistema integrador para efetuar uma busca pelo CNPJ no endpoint de listagem antes de enviar os dados para criação.

Dúvidas relacionadas

P: Por que o sistema bloqueia o CNPJ no checkout e na interface, mas permite cadastrar pela API? R: A interface e o checkout possuem travas visuais nativas de tela, enquanto a API é estruturada para receber dados diretos da integração, cabendo à aplicação externa validar o documento antes de solicitar a criação.

P: Como tratar o cliente que já ficou duplicado na base? R: Faça a inativação ou ajuste do cadastro duplicado sobressalente no sistema e implemente a consulta prévia na sua integração para prevenir novas ocorrências.

Palavras-chave de busca

duplicidade de cadastro api, cnpj duplicado cliente inativo, validação cnpj api, cadastro duplicado superlogica, integracao api cnpj existente