Homologação de NFS-e: teste a emissão sem valor fiscal

O que é a homologação, em uma frase:

É um segundo ambiente, separado da produção, onde a nota percorre o mesmo caminho de uma nota real (validação, assinatura, envio ao provedor, resposta) e no fim não vale nada para o fisco. Serve para o seu sistema errar à vontade enquanto a integração está sendo escrita, sem gerar documento que depois precise ser cancelado.

Quem integra emissão de nota sem passar pela homologação descobre os erros em produção, e em produção cada recusa da prefeitura pode consumir numeração e cada acerto errado vira um cancelamento com justificativa. A homologação existe para que esse aprendizado aconteça onde ele não custa nada.

Como os dois ambientes ficam separados no TexFiscal:

• Endereços diferentes. Produção responde em nfse.texfiscal.com.br e homologação em homologacao-nfse.texfiscal.com.br. As rotas, os campos e as respostas são os mesmos nos dois.
• Tokens diferentes. Cada token pertence a um emissor e a um ambiente, e é gerado no painel. Um token de homologação apresentado no endereço de produção recebe 401, e o contrário também. Ninguém emite nota de verdade por engano com a credencial de teste.
• Webhook diferente. Cada ambiente tem o seu endereço de aviso e o seu segredo. Os avisos das notas de teste vão para o webhook de homologação.
• Provedor de teste. Em homologação, o pedido vai ao endereço de homologação do provedor da prefeitura, que fica no cadastro do emissor ao lado do endereço de produção.

Na prática, virar a chave para a produção é trocar a URL base e o token no seu sistema. Se a integração funcionou na homologação com os mesmos dados, o código não precisa mudar.

# homologação
curl -u "TOKEN_DE_HOMOLOGACAO:" -X POST "https://homologacao-nfse.texfiscal.com.br/v2/nfse?ref=PED-4471" \
  -H "Content-Type: application/json" -d @nota.json

# produção (mesmo corpo, mesma ref de negócio)
curl -u "TOKEN_DE_PRODUCAO:" -X POST "https://nfse.texfiscal.com.br/v2/nfse?ref=PED-4471" \
  -H "Content-Type: application/json" -d @nota.json

Validar sem emitir: o passo antes da homologação:

Existe uma rota que roda a mesma validação da emissão e para antes de reservar numeração e de falar com a prefeitura. Ela responde se o pedido está pronto ou devolve a lista de erros no mesmo formato da emissão, campo por campo, com a correção de cada um. Nada é transmitido e nenhum número é consumido.

Ela é útil em dois momentos: enquanto você escreve o mapeamento dos campos do seu sistema, e como conferência antes de um lote grande. Uma ressalva honesta: a validação também confere o cadastro do emissor. Se faltar inscrição municipal, código do município, certificado digital A1 ou a senha dele, a resposta diz que o cadastro está incompleto e que não é nada no seu envio. Ou seja, ela não substitui o cadastro completo do emissor.

Passar na validação local também não garante a autorização: a prefeitura ainda pode recusar por regra própria dela. É por isso que a homologação continua sendo o teste de verdade.

curl -u "SEU_TOKEN:" -X POST https://homologacao-nfse.texfiscal.com.br/v2/nfse/validar \
  -H "Content-Type: application/json" -d @nota.json

200 {"valido": true, ...}                     pronto para emitir
422 {"codigo": "requisicao_invalida", "erros": [...]}   nada consumido

O roteiro de testes que vale a pena cumprir:

Uma nota autorizada não prova uma integração. O que prova é o seu sistema reagir certo a cada desfecho. Antes de pedir o token de produção, faça pelo menos isto na homologação:

1. Uma nota autorizada, guardando número, PDF e XML no lugar onde o seu sistema vai procurá-los.
2. Um pedido repetido com a mesma referência, para ver que ele devolve a nota que já existe em vez de emitir outra. A referência da venda é a chave que impede duas notas para a mesma venda.
3. Um pedido com erro de propósito, como uma discriminação curta demais, para o seu sistema mostrar a mensagem certa a quem emite.
4. Um aviso de webhook recebido e conferido, com a assinatura validada e o evento aplicado uma vez só.
5. Um cancelamento, do pedido até o aviso de cancelada, e a emissão da substituta com uma referência nova.

Cumprido esse roteiro, a produção costuma ser só a troca de base e de token.

O simulador do painel, para quem ainda não escreveu código:

O painel tem um simulador que monta o pedido a partir de um formulário e mostra, lado a lado, a requisição enviada e a resposta recebida. Ele emite só em homologação, e é a forma mais rápida de entender o formato antes de escrever a primeira linha de integração.

Ele não é uma tela de emissão. Em produção, quem emite é sempre o seu sistema, pela API, e nunca o TexFiscal por conta própria: a nota só sai quando o seu sistema pede.