Uma integração pode transmitir uma mensagem sem conseguir registrar o evento fiscal pretendido. Também pode montar um XML aparentemente coerente com uma tabela e descobrir, na validação, que o esquema publicado exige outro nome de campo. Na manifestação do adquirente da NFS-e Via, esses dois problemas merecem atenção antes de escrever a rotina de envio.

A NT SE/CGNFS-e nº 010, versão 1.00, acrescenta a modalidade de pagamento sem cobrança e os eventos de aceite e rejeição pelo adquirente. Este artigo se concentra na implementação desses eventos: contrato XML, identificação, validação, assinatura, comunicação e acompanhamento. O objetivo é transformar a documentação em um plano técnico verificável, sem repetir a análise normativa e o calendário geral do Ato nº 7.

A conferência considera os arquivos disponíveis em 14 de outubro de 2026, incluindo o pacote de esquemas versão 1.01 atualizado. Foram executados ensaios locais de estrutura e tipos, descritos adiante. Não houve assinatura com certificado real, transmissão à API nem homologação de um XML completo.

Separe os papéis antes de construir o cliente

A concessionária emite a NFS-e Via; o adquirente registra sua manifestação sobre o documento. Essa distinção precisa aparecer na arquitetura. Um sistema de gestão de frota que recebe documentos não deve assumir automaticamente as mesmas funções, permissões e restrições de um emissor de notas da concessionária.

A manifestação é um documento eletrônico assinado, vinculado à nota original. No contrato, e203202 identifica o aceite e e203204 identifica a rejeição. O esquema coloca esses grupos em uma escolha exclusiva: cada evento contém a alternativa correspondente à manifestação pretendida. Não se devem enviar os dois grupos para representar uma decisão ainda pendente.

Convém distinguir ainda dois usos da palavra rejeição. A rejeição manifestada pelo adquirente é uma informação de negócio sobre a nota; uma rejeição devolvida pelo serviço indica que a mensagem ou o documento não foi aceito tecnicamente. Armazenar ambos sob um único estado chamado “rejeitado” torna o diagnóstico ambíguo e pode levar o suporte a tratar uma falha de integração como contestação da passagem.

O contrato precisa incluir o XSD efetivamente utilizado

Para desenvolver essa integração, guarde a NT, o Anexo IV de leiautes e regras, o guia específico de manifestação, o guia de APIs e o pacote de esquemas. Registre a versão e o resumo criptográfico de cada arquivo. Esse resumo, ou hash, identifica o conteúdo exato utilizado nos testes e permite detectar uma substituição de arquivo mesmo quando o nome publicado permanece igual.

A comparação realizada encontrou diferenças que não devem ser resolvidas copiando apenas a primeira tabela disponível. A NT apresenta caminhos com infEvento; o pacote XSD consultado define infEventoVia. Para o motivo de rejeição, as tabelas usam cMotivo, enquanto o elemento declarado no esquema é cCodMotivoRejeicao. A sequência dos elementos também deve acompanhar o contrato selecionado.

Há outra diferença concreta: a tabela atribui tamanho de um dígito ao motivo, mas inclui o código 99. No esquema, o tipo TSCodMotivoRejeicaoManif contém expressamente esse código entre os valores permitidos. Portanto, uma propriedade definida como caractere único perderia uma possibilidade prevista no próprio conjunto documental.

O XSD permite testar compatibilidade estrutural com aquele pacote; isso não o transforma em resposta suficiente para toda divergência normativa ou operacional. A conduta prática é registrar a diferença, implementar e validar o contrato de destino e confirmar o comportamento em produção restrita. Não altere silenciosamente o esquema oficial para fazer um exemplo passar.

Modele a manifestação como um comando de negócio

Em vez de montar XML diretamente a partir da tela, mantenha um objeto interno com ambiente, chave da nota, tipo de manifestação, sequência, identificação do adquirente, data e motivo quando aplicável. Esse objeto representa a intenção do usuário. Uma camada específica o transforma no contrato exigido pelo serviço.

O destinatário dessa intenção precisa estar claro. A rejeição de uma nota por divergência de valor, por exemplo, não é um pedido automático de cancelamento. O sistema deve guardar o motivo manifestado e permitir acompanhar a solução com a concessionária. O evento registra a posição do adquirente e não substitui o XML original por uma versão editada localmente.

O motivo 99 exige justificativa segundo o guia de manifestação. Já o XSD declara xMotivoRejeita como elemento opcional. Isso mostra por que validação estrutural e regra de negócio devem ser etapas distintas: passar no esquema não demonstra que todas as condições de preenchimento foram atendidas. O controle interno precisa aplicar a condição documentada sem modificar o arquivo XSD.

No emissor da concessionária, a modalidade modPagamento = 6, sem cobrança, merece revisão de enumerações e telas. Ela não deve ser convertida artificialmente em dinheiro ou pagamento posterior apenas porque a biblioteca antiga desconhece o valor novo. Essa alteração da nota é uma tarefa separada da geração da manifestação pelo adquirente.

Preserve a chave e forme o identificador com cuidado

No pacote consultado, a chave da NFS-e Via possui 50 posições e seu tipo admite caracteres alfanuméricos em partes determinadas. Por isso, armazene-a como texto, preservando zeros e letras. Uma coluna numérica, uma conversão para inteiro ou a validação emprestada da chave de 44 posições da NF-e não representam adequadamente esse contrato.

O identificador do evento combina o prefixo EVT, a chave, o código do evento e a sequência representada com três posições, totalizando 62 caracteres. O trecho abaixo demonstra somente essa composição. Foi executado em Python para tornar o ensaio reproduzível; em Delphi, a mesma responsabilidade pode ficar em uma função independente do componente de comunicação.

import re

def formar_id(chave: str, evento: str, sequencia: int) -> str:
    # Não valida a chave, o dígito verificador ou a operação fiscal.
    if len(chave) != 50 or not re.fullmatch(r"[A-Z0-9]+", chave):
        raise ValueError("Chave deve ter 50 caracteres alfanuméricos maiúsculos")
    if evento not in ("203202", "203204"):
        raise ValueError("Tipo de manifestação inválido")
    if type(sequencia) is not int or not 1 <= sequencia <= 999:
        raise ValueError("Sequência deve ser um inteiro de 1 a 999")
    return f"EVT{chave}{evento}{sequencia:03d}"

A função não verifica as posições internas da chave nem seu dígito verificador. A faixa de sequência iniciada em 1 é uma política do exemplo, não uma conclusão extraída apenas do tipo simples. O ensaio separado confrontou valores sintéticos com os tipos oficiais; esse teste tem alcance menor que validar o documento completo e obter seu registro.

Como recomendação de arquitetura, aloque a sequência de forma persistente e com controle de concorrência. Duas tarefas não devem produzir identificadores diferentes para a mesma intenção apenas porque uma conexão demorou. Preserve a relação entre decisão, identificador, conteúdo e tentativa de envio, sem presumir uma garantia de idempotência da API que não tenha sido confirmada no contrato.

Assinar, transmitir e confirmar são etapas distintas

A assinatura XML protege o conteúdo do documento; a autenticação mútua da conexão identifica os participantes do transporte. Configurar um certificado no cliente HTTP não equivale a assinar o evento. Da mesma forma, possuir um XML assinado não resolve, por si só, a seleção do certificado e do ambiente de comunicação.

O guia de manifestação descreve HTTPS com TLS 1.2 ou superior e certificado ICP-Brasil para o adquirente. O guia geral de APIs contém trechos destinados à concessionária, inclusive uma tabela que rejeita e-CPF, e também uma referência mais ampla a versões antigas de TLS. Essas passagens não devem ser aplicadas indiscriminadamente ao fluxo do adquirente. Use a orientação específica e confira a documentação do serviço para o perfil e o ambiente pretendidos.

O guia de APIs descreve troca de mensagens em JSON, documentos XML e compactação GZip com representação Base64. Isso exige separar serialização do evento e montagem da mensagem de transporte. A documentação operacional do serviço deve confirmar os nomes e o formato do corpo; este artigo não apresenta um JSON presumido nem considera o endereço de produção um comando pronto para teste.

No desenho do cliente, mantenha parâmetros distintos para produção restrita e produção. A seleção do endereço precisa acompanhar a identificação de ambiente do evento. Uma configuração que troca somente a URL, mantendo o conteúdo e as credenciais sem conferência, pode produzir uma integração aparentemente conectada ao destino correto, mas inconsistente com a operação pretendida.

Recepção não é confirmação de registro

O processamento descrito no guia é assíncrono: a recepção da mensagem não garante a aceitação posterior do documento. Por isso, a interface não deve marcar a manifestação como registrada apenas porque o envio HTTP terminou com sucesso. É necessário interpretar o retorno e acompanhar o resultado pelo mecanismo disponível para o perfil e o serviço utilizados.

Uma proposta de estados internos é separar preparação, validação local, envio, recepção, resultado desconhecido e registro confirmado. Registre também os erros técnicos em campo próprio. Esses nomes são uma sugestão de modelagem do ERP, não códigos oficiais de resposta da API.

Se ocorrer um tempo limite após o envio, conserve a identidade da tentativa e trate o resultado como desconhecido. Investigue o processamento pelos recursos documentados antes de reenviar ou criar outro evento. A ausência de resposta não prova que o servidor deixou de receber o documento. Uma repetição automática sem reconciliação pode dificultar a interpretação do histórico.

Para a concessionária, o guia também prevê consulta das manifestações por NSU, uma sequência usada na distribuição dos registros. No adquirente, não se deve presumir disponibilidade dos mesmos métodos de consulta da concessionária: as seções de APIs distinguem os perfis. A estratégia de confirmação e recuperação precisa respeitar essa separação.

O que testar antes de liberar a integração

Foram executadas 13 verificações locais nesta pesquisa. O esquema oficial completo de eventos compilou sem modificação. Os ensaios também verificaram a composição do identificador, uma chave sintética com letra em posição admitida, a aceitação do motivo 99 pelo tipo correspondente, a recusa de valores inválidos e a existência da escolha exclusiva entre aceite e rejeição.

Esses resultados verificam partes do contrato, não uma integração fiscal pronta. Não foi produzido um evento completo com assinatura criptográfica válida, e nenhum documento foi transmitido. Para transformar o trabalho em homologação do emissor, a equipe precisa ampliar os cenários e preservar as evidências de cada etapa:

1. Estrutura e conteúdo: validar o XML completo com o pacote selecionado, incluindo ordem, nomes, ambiente, identificação do adquirente e ramo correto do evento.
2. Regras condicionais: conferir motivo e justificativa, coerência entre identificação e documento e correspondência com a nota consultada.
3. Assinatura e transporte: verificar integridade após a assinatura, certificado adequado ao perfil, cadeia de confiança e configuração do ambiente.
4. Retornos e recuperação: simular falha local, recusa técnica, recepção sem resultado final, tempo limite e retomada sem criar eventos desnecessários.
5. Rastreabilidade: guardar versões, hashes, XML assinado, identidade da tentativa, retorno e confirmação efetivamente obtida, com acesso restrito aos dados necessários.

Na liberação, vincule o resultado à versão do produto, ao pacote XSD e ao ambiente usado. Uma compilação local bem-sucedida não comprova que o serviço já adotou o mesmo contrato. Diferenças documentais precisam permanecer visíveis até serem esclarecidas ou resolvidas por uma versão posterior, em vez de desaparecerem em comentários do código.

Conclusão

Implementar a manifestação da NFS-e Via exige mais do que acrescentar uma chamada HTTP. O sistema precisa representar a decisão do adquirente, produzir o evento conforme o contrato selecionado, assinar o conteúdo, transmitir pelo perfil correto e distinguir recepção de registro confirmado.

A contribuição mais útil da conferência é mostrar onde um detalhe documental pode virar defeito de software: nome de elemento, largura do motivo, tratamento da chave ou condição não coberta pelo XSD. Separar essas responsabilidades em componentes testáveis permite corrigir cada problema com evidências e acompanhar a evolução dos arquivos oficiais sem comprometer o histórico das manifestações.

Referências

BRASIL. Secretaria-Executiva do Comitê Gestor da Nota Fiscal de Serviço Eletrônica. Anexo II: guia para utilização das APIs. Versão 1.02. Portal da NFS-e, set. 2026. Disponível em: https://www.gov.br/nfse/pt-br/nfs-e-via/documentacao-tecnica/manuais-e-anexos/anexo-ii-guia-para-utilizacao-das-apis-v-1-02.pdf. Acesso em: 14 out. 2026.

BRASIL. Secretaria-Executiva do Comitê Gestor da Nota Fiscal de Serviço Eletrônica. Anexo IV: leiautes e regras de negócio ADN — NFS-e Via. Versão 1.00.05. Portal da NFS-e, [s. d.]. Disponível em: https://www.gov.br/nfse/pt-br/nfs-e-via/documentacao-tecnica/manuais-e-anexos/anexo-iv-leiautesrn_adn-snnfsevia_v1-00-05.xlsx. Acesso em: 14 out. 2026.

BRASIL. Secretaria-Executiva do Comitê Gestor da Nota Fiscal de Serviço Eletrônica. Anexo VI: guia para inclusão de evento de manifestação do adquirente. Versão 1.02. Portal da NFS-e, set. 2026. Disponível em: https://www.gov.br/nfse/pt-br/nfs-e-via/documentacao-tecnica/manuais-e-anexos/anexo-vi-guia-para-manifestacao-do-adquirente-v-01-02.pdf. Acesso em: 14 out. 2026.

BRASIL. Secretaria-Executiva do Comitê Gestor da Nota Fiscal de Serviço Eletrônica. Arquivos dos esquemas XSD: versão 1.01 atualizada. Portal da NFS-e, [s. d.]. Disponível em: https://www.gov.br/nfse/pt-br/nfs-e-via/documentacao-tecnica/arquivos-dos-esquemas-xsd/schemas_v1-01_atualizado.zip. Acesso em: 14 out. 2026.

BRASIL. Secretaria-Executiva do Comitê Gestor da Nota Fiscal de Serviço Eletrônica. Links: ambientes da NFS-e Via. Portal da NFS-e, atualizado em 13 out. 2026. Disponível em: https://www.gov.br/nfse/pt-br/nfs-e-via/links. Acesso em: 14 out. 2026.

BRASIL. Secretaria-Executiva do Comitê Gestor da Nota Fiscal de Serviço Eletrônica. Nota Técnica SE/CGNFS-e nº 010. Versão 1.00. Brasília, DF, 11 set. 2026. Disponível em: https://www.gov.br/nfse/pt-br/nfs-e-via/documentacao-tecnica/notas-tecnicas/nt-010-se-cgnfse-leiaute-nfse-via-v-1.00.pdf. Acesso em: 14 out. 2026.