Como configurar o Conectivo Desenvolvimento 1 para envio de NF-e
O Conectivo Desenvolvimento 1 é o serviço intermediário da Sefaz que permite que softwares emitam notas fiscais eletrônicas sem precisar implementar toda a lógica de assinatura, criptografia e comunicação SOAP do zero. Ele funciona como uma camada de abstração: seu sistema manda os dados brutos, o conectivo assina, valida e encaminha para a receita. Se você já tentou fazer tudo manualmente, sabe que o tempo de desenvolvimento cai drasticamente com essa abordagem.
Conectivo desenvolvimento 1: instalação e primeiros passos
Você precisa baixar o pacote de desenvolvimento no site da Sefaz do seu estado. Geralmente o link fica em "Download" ou "Desenvolvedor" dentro do portal da nota fiscal eletrônica. O arquivo costuma vir como um ZIP com o executável do serviço, arquivos de configuração em XML, certificados de teste e documentação técnica. Extraia tudo em um diretório que não tenha espaços no caminho — algo como C:\\Conectivo\\ é o mínimo que funciona sem dor de cabeça. Dentro da pasta, execute o instalador do serviço. Ele vai registrar um serviço do Windows chamado geralmente "ConectivoNF-e" ou similar. No painel de serviços (services.msc), verifique se ele está rodando. Se não estiver, inicie manualmente e defina o tipo de inicialização como Automático. Fique atento ao log que é gerado em C:\\ProgramData\\Conectivo\\logs ou em um caminho similar — é aí que você vai encontrar os erros antes que o sistema cliente reclame.
A configuração básica envolve editar o arquivo de configuração XML, normalmente chamado Conectivo.Config.xml ou algo parecido. Você vai inserir o CNPJ da empresa, o certificado digital A1 (não serve A3 com token nesse caso, o serviço precisa acessar o arquivo .pfx diretamente), a URL do webservice de homologação ou produção, e algumas configurações de timeout. O timeout padrão é 30 segundos, mas eu recomendo subir para 60. A Sefaz nem sempre responde rápido, especialmente em períodos de picos como fechamento de mês.
O que acontece na prática quando você chama o serviço
Seu ERP ou sistema contábil faz uma requisição HTTP POST para o endpoint local do conectivo, geralmente na porta 8080 ou 8443. O payload é um JSON ou XML com os dados da NF-e: campos do emitente, destinatário, produtos, impostos, etc. O conectivo pega esses dados, monta a XML da NF-e completa, aplica a assinatura digital usando o certificado que você configurou, valida contra a schema XSD oficial da SEFAZ, e encaminha para o webservice de recepção. A resposta volta com o status de aceite, o protocolo de autorização ou o erro detalhado. O formato exato da requisição varia conforme a versão do conectivo. Na versão 1, que é a mais comum, a entrada é um JSON com estrutura bem definida. Campos obrigatórios incluem infoNFe, ide, emit, dest, imposto, e itens como prod e det. Se faltar um campo obrigatório ou se o CPF/CNPJ estiver mal formatado, o conectivo rejeita antes mesmo de assinar — o que é bom, porque economiza uma rodada de comunicação com a Sefaz.
Eu passei duas semanas presa num problema onde as notas eram rejeitadas com erro "Falha no esquema XML" apenas em um cliente específico. O erro era sutil: o campo cProd do item continha caracteres especiais que pareciam inofensivos mas quebravam a validação XSD. A solução foi adicionar uma limpeza com regex antes de montar o JSON de entrada — replace de tudo que não for alfanumérico, hífen ou barra. Isso resolveu. O conectivo em si estava funcionando perfeitamente, o problema era na entrada de dados do sistema legado daquele cliente.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Pontos que ninguémConta
O primeiro problema que você vai enfrentar é o Certificado Digital. O conectivo lê o certificado do arquivo .pfx, então você precisa saber a senha do certificado e garantir que o serviço tenha permissão de leitura no arquivo. Em ambientes de rede com políticas de segurança restritivas, isso pode ser um pesadelo. Uma alternativa é usar o certificado A3 com container de hardware, mas aí você precisa configurar o conectivo para usar o Cryptographic Next Generation API, e a configuração muda completamente. Se o ambiente permitir, vá de A1 em arquivo mesmo. É muito mais simples. O segundo ponto é a fila de reprocessamento. Quando uma nota é enviada e a Sefaz responde com erro de comunicação ou tempo esgotado, o conectivo não abandona o documento. Ele coloca em uma fila interna e tenta novamente com backoff exponencial. Isso é bom, mas você precisa monitorar essa fila. Se ela acumular, significa que a Sefaz está com instabilidade ou que há um problema estrutural nas suas notas. Eu configuro um watcher simples que dispara um alerta quando a fila passa de 5 itens por mais de 10 minutos.
O terceiro ponto é a versão do conectivo. Existem variantes para NF-e, NFC-e, CT-e e MDF-e. Não adianta tentar enviar um CT-e pelo conectivo de NF-e. Cada um tem schema, campos e regras de negócio diferentes. Se sua empresa emite vários tipos de documento fiscal, você vai precisar instalar múltiplas instâncias do conectivo, cada uma com sua própria configuração de certificado e endpoint. Um detalhe importante sobre performance: o conectivo processa uma nota completa em cerca de 2 a 5 segundos em hardware razoável. Se você precisa emitir centenas de notas por hora, considere paralelizar as requisições. O serviço suporta múltiplas conexões simultâneas, mas cada una consome memória para manter o contexto de assinatura. Em testes, mais de 20 requisições concorrentes começaram a degradar o tempo de resposta. Um pool de 10 a 15 conexões parece ser o sweet spot.
Alternativas quando o conectivo nãoresolve
Em alguns casos, o Conectivo Desenvolvimento 1 simplesmente não é viável. Se sua empresa opera em múltiplos estados com regras de homologia diferentes, ou se você precisa de integrações customizadas que o conectivo não oferece, a abordagem direta via webservice SOAP pode ser mais adequada. Isso exige muito mais desenvolvimento — você precisa lidar com assinatura digital manualmente, validação de schema, retry logic, e tratamento de erros de rede. Mas dá controle total. Outra alternativa são bibliotecas de terceiros como o ACBR ou o FiscalBr, que oferecem camadas de abstração ainda mais altas. Eles encapsulam toda a complexidade e podem até substituir o conectivo em muitos cenários. O trade-off é dependência de um projeto Open Source cuja manutenção depende da comunidade. Se o projeto parar, você fica preso.
O conectivo em si tem limitações conhecidas. Ele não oferece log detalhado de cada passo da validação — apenas o resultado final. Se uma nota é rejeitada, você recebe o código de erro da Sefaz, mas não sabe exatamente qual campo gerou o problema sem analisara XML gerada. A solução é ativar o modo debug no arquivo de configuração, que gera um XML de saída em uma pasta específica para cada tentativa. Esse XML pode ser submetido manualmente no Validador NF-e da Sefaz para diagnóstico. Outra limitação é que o conectivo versão 1 não suporta eventos pós-emissão como cancelamento ou carta de correção da mesma forma que suporta o envio original. Para essas operações, você precisa chamar os webserviços diretamente ou usar um conectivo específico para eventos, que alguns estados oferecem separadamente. Planifique isso desde o início do projeto para não ter surpresas.
A instalação em produção também merece atenção. Nunca use o mesmo certificado de homologação em produção. O conectivo permite trocar o certificado dinamicamente editando o arquivo de configuração e reiniciando o serviço, mas o ideal é ter instâncias separadas. Homologação em uma máquina ou container, produção em outra. Isso evita que testes acidentais polluam o ambiente real e dificultam a auditoria.
Checklist prático para colocar em funcionamento
Certifique-se de que o serviço está rodando e respondendo na porta configurada. Teste com uma requisição simples de consulta de status do serviço antes de tentar enviar qualquer nota. Verifique o log do serviço após cada tentativa — erro ali é mais fácil de ler do que erro no sistema cliente. Tenha um certificado de homologação válido e testado. Confirme que o CNPJ configurado corresponde ao certificado. Valide uma nota de teste completa no ambiente de homologia antes de qualquer integração em produção. Monitore a fila de reprocessamento nos primeiros dias — ela deve estabilizar em zero rapidamente. Anote o tempo médio de resposta do conectivo no seu ambiente para ter baseline caso problemas futuros. O conectivo desenvolvimento 1 simplifica muito a integração com a SEFAZ, mas não elimina a necessidade de entender o que está acontecendo por baixo. Erros de configuração de certificado, timeouts mal ajustados, e dados mal formatados são os três culpados em 90% dos casos que eu vejo. Se você tratar esses pontos desde o início, o restante da implementação segue sem maiores complicações.
