Como integrar o Cotejar ao seu sistema de importação

Se a sua empresa já mantém os produtos em um ERP ou sistema de comércio exterior, a integração com o Cotejar deve começar por uma pergunta prática: como levar a mesma identidade e os mesmos dados para a conferência, e devolver o resultado para quem pode agir?

Essa conversa costuma render mais do que começar por uma chamada de API isolada. Ela define a origem dos dados, o momento da atualização e o caminho da pendência até o responsável pelo cadastro.

Neste guia, vamos organizar o fluxo e apontar a documentação pública para cada etapa. A conexão depende do sistema utilizado, dos campos disponíveis e das permissões da empresa; não presumimos um conector pronto para qualquer ERP.

Um fluxo para discutir com a equipe de sistemas

Pense em quatro etapas: obter uma base identificável, atualizar os dados no Cotejar, acompanhar a análise até o resultado e direcionar os achados para a equipe responsável.

O sistema de origem precisa preservar a referência do produto. O resultado precisa permitir localizar esse mesmo item. Entre essas pontas, a integração deve distinguir recebimento de dados, conclusão do processamento e resultado da comparação.

Antes de automatizar, uma exportação revisada pode ajudar a validar o mapeamento. Veja também o guia de preparação do Catálogo de Produtos da DUIMP.

Passo 1: mapeie os dados e suas identidades

Registre qual campo identifica o produto no ERP, onde está a NCM informada e como os atributos são representados. Preserve códigos como texto e documente transformações que possam alterar seu significado.

Se o sistema usa rótulos próprios para atributos ou listas de valores, crie uma correspondência explícita com os códigos utilizados no fluxo. Uma tradução informal entre nomes pode funcionar na conversa e falhar na automação.

Defina ainda como a integração trata produtos novos, alterados ou retirados de uso. As referências de produtos e de catálogos descrevem os recursos; use o contrato atual para decidir quais operações fazem sentido.

Passo 2: prepare a autenticação da empresa

Siga o guia de autenticação da API Cotejar. A chave pertence a uma empresa e suas permissões devem corresponder às operações da integração.

Mantenha a credencial no servidor ou no mecanismo seguro utilizado pela equipe de sistemas. Evite colocá-la em planilhas de trabalho, código entregue ao navegador ou mensagens de suporte.

O guia da primeira requisição permite começar pela consulta do contexto autorizado. Essa conferência ajuda a confirmar que o fluxo está associado à empresa correta antes de qualquer escrita.

Passo 3: escolha como atualizar a base

A API oferece recursos de gestão de produtos e um fluxo de ingestão. A escolha depende de como o sistema de origem organiza e entrega os dados.

Antes de aplicar uma atualização, confira o alcance da operação, o conteúdo enviado e as validações exigidas. Uma substituição integral e uma alteração pontual têm consequências diferentes para a base.

As escritas usam mecanismos de repetição segura e, quando previsto no recurso, controle de concorrência. Siga a documentação sobre erros e idempotência e os limites e paginação. Isso permite tratar uma interrupção sem criar atualizações duplicadas ou confirmar uma mudança sobre dados que já foram alterados.

Passo 4: acompanhe a análise até o estado final

Atualizar o cadastro e concluir uma análise são etapas distintas. O fluxo de análises e resultados explica como solicitar, acompanhar e consultar os achados.

Quando a API retorna um aceite assíncrono, a integração precisa acompanhar o recurso indicado até a conclusão. Uma resposta de recebimento confirma que o pedido foi aceito; o resultado só pode ser tratado quando estiver disponível no estado correspondente.

Registre situações de espera e falha de forma visível para a equipe. Se o processamento não terminou, o sistema de origem não deve mostrar “sem divergências”.

Ao consumir resultados paginados, percorra as páginas indicadas pelo contrato. Para o CSV, siga as verificações de integridade descritas na documentação antes de importar o arquivo. O objetivo é garantir que a equipe está olhando o resultado inteiro daquela execução.

Passo 5: organize o retorno à operação

Combine com o responsável pelo cadastro quais informações chegam na tarefa: produto, referência da execução, exigência apontada e próxima ação de conferência. Evite mandar um aviso genérico que obrigue a equipe a procurar novamente todo o contexto.

Se a integração utilizar webhooks do Cotejar, implemente as verificações de assinatura, o tratamento de repetições e o acompanhamento das entregas descritos no guia. Um evento é uma forma de comunicar o andamento; os detalhes da execução continuam no recurso correspondente.

Para a continuidade, confira o fluxo de vigilância e os direitos de uso da empresa. Autenticação, permissão de uma operação e capacidade disponível precisam ser tratados conforme o contrato.

Casos que vale testar antes de usar o fluxo

• Produto com código interno contendo zeros iniciais.
• Atualização repetida depois de uma interrupção de rede.
• Alteração concorrente do mesmo cadastro.
• Pedido aceito cuja análise ainda não terminou.
• Falha de processamento e retorno posterior ao funcionamento.
• Resultado com mais de uma página ou CSV incompleto.
• Evento recebido novamente pelo sistema de origem.

Esses casos são propostas de teste do integrador. Eles ajudam a verificar se a conexão preserva os dados e informa o estado real do trabalho.

A integração acompanha a preparação para a DUIMP

O Cotejar compara o catálogo informado com as exigências publicadas pelo Portal Único. A integração pode levar essa conferência para a rotina da empresa, mantendo as pendências próximas de quem cuida do produto.

Ela não registra a DUIMP nem transfere ao Cotejar a decisão de classificação fiscal. Para organizar essas etapas, consulte o guia de NCM e classificação, a conferência dos atributos e o artigo sobre preparação para o desligamento da DI.

Quer avaliar a conexão com o seu sistema?

Fale com o Cotejar sobre integração. Leve o formato de exportação, os campos disponíveis, a frequência de atualização e o caminho atual das pendências. Não envie credenciais reais na conversa.

Com essas informações, é possível discutir o mapeamento e a forma de uso mais adequada. Para começar a pesquisa técnica, a documentação para desenvolvedores e a referência navegável da API são os pontos de partida.

Referências e atualização

Conteúdo conferido em 13 de outubro de 2026 com a documentação pública do Cotejar e a referência da API em produção. Os guias vinculados descrevem o contrato atual de cada operação; consulte-os durante a implementação, pois recursos e limites podem evoluir. O mapeamento do ERP e os casos de teste são propostas editoriais para planejar a integração.