Como automatizar a verificação de fornecedores via API

Verificação manual de fornecedor tem três problemas conhecidos: consome tempo de gente cara, varia de analista para analista e envelhece no dia seguinte. Automatizar não é só trocar a digitação por uma chamada HTTP — é escrever a regra de decisão uma vez e aplicá-la sempre da mesma forma. O roteiro abaixo é o que funciona na maioria das operações.

1. Escolha o momento certo da verificação

Existem quatro momentos úteis, e eles não competem entre si:

• No cadastro, antes de aprovar o fornecedor. Barreira mais barata que existe.
• Antes do pedido de compra, para contratos longos em que o cadastro é antigo.
• Em lote, periodicamente, para a carteira inteira.
• Por monitoramento contínuo, recebendo aviso quando algo muda.

Comece pelo cadastro: é onde o erro custa mais caro e onde a automação é mais simples de justificar.

2. Normalize a entrada antes de consultar

Metade dos erros de integração vem do formato do CNPJ. Antes de chamar a API, remova a máscara e valide os dígitos verificadores localmente — isso evita gastar consulta com número digitado errado:

function apenasDigitos(valor) {
  return String(valor).replace(/\D/g, "");
}

function cnpjValido(valor) {
  const numero = apenasDigitos(valor);
  if (numero.length !== 14 || /^(\d)\1{13}$/.test(numero)) return false;

  const digito = (base) => {
    let peso = base.length - 7;
    let soma = 0;
    for (let i = 0; i < base.length; i += 1) {
      soma += Number(base[i]) * peso;
      peso -= 1;
      if (peso < 2) peso = 9;
    }
    const resto = soma % 11;
    return resto < 2 ? 0 : 11 - resto;
  };

  const base = numero.slice(0, 12);
  return (
    digito(base) === Number(numero[12]) &&
    digito(base + numero[12]) === Number(numero[13])
  );
}

3. Faça a consulta autenticada

A chamada é um GET autenticado por chave. Guarde a chave em variável de ambiente — nunca no código do front-end.

curl -s "https://api.conectaregular.com.br/v1/cnpj/00000000000191" \
  -H "Authorization: Bearer $CONECTA_API_KEY"

A resposta traz o veredito consolidado, a pontuação de 0 a 100, a situação federal com data e motivo, as inscrições estaduais por UF, o regime tributário e a lista de pendências.

4. Escreva a regra de decisão uma única vez

O ponto que separa uma integração útil de um relatório que ninguém lê é ter a política escrita em código, em um lugar só:

function decidirFornecedor(relatorio, { exigeInscricaoEstadual }) {
  if (relatorio.situacao === "irregular") {
    return { acao: "bloquear", motivo: relatorio.pendencias[0]?.descricao };
  }

  if (relatorio.situacao === "indeterminado") {
    return { acao: "reconsultar", motivo: "base indisponível no momento da consulta" };
  }

  const pendenciaEstadual = relatorio.pendencias.some((p) => p.escopo === "estadual");
  if (exigeInscricaoEstadual && pendenciaEstadual) {
    return { acao: "analisar", motivo: "inscrição estadual não habilitada" };
  }

  return { acao: "aprovar" };
}

Repare no parâmetro exigeInscricaoEstadual: ele vem da categoria do fornecedor. Serviço puro não precisa de inscrição estadual, e tratar a ausência como pendência gera fila de exceção sem valor.

5. Sanear a base que já existe

Antes de ligar a automação no fluxo novo, rode a base atual em lote. É a etapa que produz o número que convence a diretoria: quantos fornecedores ativos no ERP já não estão regulares. Envie a lista de CNPJs, receba o resultado consolidado e priorize por valor contratado, não por ordem alfabética.

6. Mantenha a verificação viva

Cadastro verificado uma vez é cadastro verificado nunca. Duas práticas resolvem:

• Reconsulta periódica dos fornecedores ativos, com janela compatível com o risco — mensal para crítico, trimestral para o restante.
• Webhook de mudança de situação, para o seu sistema receber o evento no instante em que a situação muda e abrir a tarefa sozinho.

7. Registre tudo

Guarde, para cada verificação, a data, o CNPJ consultado, o veredito e a resposta completa. Auditoria interna, due diligence e discussões com o fiscal ficam muito mais curtas quando existe trilha. Vale também registrar a decisão tomada — aprovar, analisar ou bloquear — para medir depois quantas exceções a política está gerando.

O que esperar do resultado

Operações que fecham esse ciclo costumam relatar o mesmo padrão: a fila de exceção encolhe, o tempo de aprovação de fornecedor cai para minutos e as surpresas migram do momento da entrega para o momento do cadastro — que é onde elas custam pouco. E, como sempre, vale a ressalva: os dados vêm de bases oficiais, a consulta é informativa e não substitui certidão nem orientação contábil.