Primeira nota direto em produção: o que dá errado e como montar a homologação

Quinta, 17h, a integração fiscal da loja de autopeças precisa estar pronta amanhã. O desenvolvedor aponta direto para produção "só para ver se passa", com um cliente inventado e um produto de R$ 1,00. A nota é autorizada. Agora existe um documento fiscal real, em nome da empresa, para um destinatário que não existe. A resposta curta: o ambiente de homologação existe para você errar sem que o erro valha. Toda nota de teste vai para homologação, com dados fictícios, e o sistema precisa ter uma trava que impeça trocar de ambiente por engano, nos dois sentidos.

Este guia mostra o que custa testar em produção, como montar a separação entre os ambientes e uma trava simples em C# que recusa a emissão quando configuração e ambiente não combinam. A diferença técnica entre os ambientes, que vai além do endereço, está em homologação não é produção com outro endereço.

Cancelamento, inutilização e correção de notas seguem regras e prazos definidos pela legislação e pelos autorizadores. Isto não substitui o contador da empresa.

Por que testar em produção sai caro

Na NF-e, o campo tpAmb diz o ambiente: 1 para produção, 2 para homologação. Uma nota autorizada com tpAmb igual a 1 é documento fiscal com validade jurídica. Não existe "apagar":

• Nota autorizada com dado de teste precisa ser cancelada, dentro do prazo e das regras de cancelamento. Passado o prazo, o caminho fica mais difícil e envolve o contador.
• Nota rejeitada em produção não vira documento, mas o número usado pode precisar ser inutilizado se ficar um buraco na sequência.
• A empresa aparece nos registros do fisco com documentos que não correspondem a operação nenhuma. Isso pode gerar pergunta numa fiscalização.
• Dados pessoais reais usados no teste (o CPF de um colega, de um cliente) ficam num documento fiscal que circula. Isso é problema de privacidade, não só fiscal.

Em homologação, nada disso acontece. A nota é processada pelas mesmas regras de validação, recebe autorização ou rejeição de verdade, e não tem valor fiscal. Na NF-e, a homologação ainda exige que o nome do destinatário seja o texto padrão NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL, justamente para que nenhum documento de teste se confunda com um real.

Como montar a separação entre os ambientes

1. Uma configuração por ambiente, com o ambiente fiscal explícito, o banco de dados e a pasta de XML. O certificado costuma ser o mesmo e-CNPJ da empresa nos dois ambientes; o que separa é o tpAmb, o endereço do serviço e os dados.
2. Banco separado. As notas de homologação não podem aparecer no relatório fiscal nem no SPED. A numeração de homologação também não conversa com a de produção.
3. Pasta de XML separada, longe do arquivo oficial que você guarda pelos prazos legais.
4. Dados fictícios. Clientes de teste com documento gerado para teste, nunca dado de cliente real. Produtos de teste identificados no nome.
5. Uma trava no código que compara o ambiente da aplicação com o ambiente fiscal configurado e com o tpAmb do XML, e recusa a emissão se algo não bater.
6. Um aviso visível na tela de emissão e no caixa quando o sistema está em homologação. Não uma URL enterrada num arquivo de configuração.

A configuração de cada ambiente

No appsettings.Homologacao.json:

{
  "Fiscal": {
    "Ambiente": "Homologacao",
    "PastaXml": "D:/fiscal/homologacao/xml"
  },
  "ConnectionStrings": {
    "Loja": "Server=db-homolog;Database=loja_homolog;Integrated Security=true;Encrypt=true"
  }
}

No appsettings.Production.json, o mesmo formato com "Ambiente": "Producao", outro banco e outra pasta. A aplicação sobe com ASPNETCORE_ENVIRONMENT definido como Homologacao ou Production, e cada ambiente lê o seu arquivo.

A trava que recusa a mistura

using System.Xml.Linq;
using Microsoft.Extensions.Hosting;

public enum AmbienteFiscal { Producao = 1, Homologacao = 2 }

public sealed class OpcoesFiscais
{
    public AmbienteFiscal Ambiente { get; init; }
    public string PastaXml { get; init; } = "";
}

public static class TravaDeAmbiente
{
    private static readonly XNamespace Nfe = "http://www.portalfiscal.inf.br/nfe";

    public static void ConferirNaInicializacao(OpcoesFiscais opcoes, IHostEnvironment host)
    {
        var aplicacaoEmProducao = host.IsProduction();
        var fiscalEmProducao = opcoes.Ambiente == AmbienteFiscal.Producao;
        if (aplicacaoEmProducao != fiscalEmProducao)
            throw new InvalidOperationException(
                "Ambiente fiscal " + opcoes.Ambiente + " não combina com a aplicação em " + host.EnvironmentName);
    }

    public static void ConferirAntesDeTransmitir(XDocument nota, OpcoesFiscais opcoes)
    {
        var tpAmb = nota.Descendants(Nfe + "tpAmb").Select(e => e.Value).FirstOrDefault();
        var esperado = ((int)opcoes.Ambiente).ToString();
        if (tpAmb != esperado)
            throw new InvalidOperationException(
                "tpAmb " + (tpAmb ?? "ausente") + " no XML, mas o ambiente configurado é " + esperado);
    }
}

A primeira verificação roda quando a aplicação sobe: um servidor de produção com configuração fiscal de homologação não inicia, e o contrário também não. A segunda roda antes de cada transmissão e pega o caso de um XML montado com o ambiente errado, por exemplo por um valor fixo esquecido no gerador. Os dois erros são barulhentos de propósito: melhor um sistema que não sobe do que um caixa que emite nota de teste em produção a manhã inteira.

Na tela, um componente simples resolve o aviso: se o ambiente fiscal é homologação, uma faixa fixa no topo com "HOMOLOGAÇÃO: notas sem valor fiscal". Quem está no caixa precisa ver isso sem procurar.

Erros comuns

• Emitir a primeira nota em produção "para ver se passa". Se passar, você tem um documento fiscal de teste para cancelar; se não passar, pode ter um número para inutilizar.
• Esquecer o caixa apontado para homologação depois do teste. As vendas do dia saem sem valor fiscal, e o problema só aparece quando o cliente reclama da nota.
• Usar o mesmo banco para os dois ambientes. Notas de teste entram no relatório fiscal e na conferência do contador.
• Testar com CPF de cliente ou de colega. Dado pessoal real num documento de teste, sem necessidade. O guia de LGPD em sistema pequeno trata disso.
• Misturar XML de teste com o arquivo oficial. Na hora de entregar os arquivos ao contador ou a uma fiscalização, ninguém sabe o que é real.
• Deixar o ambiente fixo no código do gerador. Um tpAmb fixo em 2 que chega à produção, ou o contrário, sem nenhuma trava para avisar.

Checklist

• Cada ambiente tem configuração própria, com o ambiente fiscal explícito.
• Homologação e produção usam bancos e pastas de XML diferentes.
• A aplicação não sobe se o ambiente fiscal não combina com o ambiente da aplicação.
• O tpAmb do XML é conferido antes de cada transmissão.
• A tela de emissão e o caixa mostram um aviso visível em homologação.
• Os dados de teste são fictícios, sem CPF ou nome de pessoa real.
• Toda mudança no emissor passa por homologação antes de ir para produção, como descrito em conferir o leiaute que vale hoje.

Abra o sistema que emite as suas notas e procure, sem olhar arquivo de configuração: existe algum lugar na tela que diz em qual ambiente fiscal ele está agora?