MDFe: Distribuição DF-e via Web Service (NT 2015.002)

O Manifesto Eletrônico de Documentos Fiscais (MDF-e) possui um serviço específico para a distribuição de Documentos Fiscais Eletrônicos (DF-e) de interesse dos atores envolvidos. Este serviço visa prover informações de forma eficiente e confiável, conforme detalhado na Nota Técnica 2015.002 do Projeto Manifesto Eletrônico de Documentos Fiscais. O objetivo é disponibilizar a terceiros os DF-e a que têm direito, como pessoas autorizadas a acessar o XML, contratantes de serviço e proprietários de veículos.

Arquitetura de comunicação

O Web Service de distribuição de DF-e opera de forma síncrona. O aplicativo do contribuinte inicia a comunicação enviando uma mensagem com os parâmetros de pesquisa. Em resposta, o Web Service retorna uma mensagem confirmando o recebimento da solicitação na mesma conexão.

Padrões técnicos

A comunicação e o processamento dos documentos fiscais eletrônicos são padronizados para garantir integridade e interoperabilidade.

Padrão de documento XML

A especificação XML segue a recomendação W3C para XML 1.0, com codificação de caracteres em UTF-8. Assim, todos os documentos XML iniciam com a declaração <?xml version="1.0" encoding="UTF-8"?>.

A declaração de namespace deve ser única no elemento raiz do documento, utilizando o padrão xmlns='http://www.portalfiscal.inf.br/mdfe'. O uso de prefixos de namespace não é permitido para otimizar o tamanho do arquivo XML. Antes do envio, a mensagem XML precisa ser validada pelo Schema (XSD – XML Schema Definition) disponibilizado pelo Ambiente Autorizador, assegurando a formação correta dos arquivos.

Padrão de comunicação

A comunicação utiliza a Internet, empregando o protocolo TLS versão 1.2 ou superior com autenticação mútua. Este protocolo garante um canal seguro e identifica servidor e cliente por meio de certificados digitais, eliminando a necessidade de usuário e senha.

O modelo de comunicação segue o padrão de Web Services definido pelo WS-I Basic Profile. A troca de mensagens é realizada no padrão SOAP versão 1.2, com mensagens XML no padrão Style/Encoding: Document/Literal. A chamada do Web Service MDFeDistribuicaoDFe é feita com o envio de uma mensagem XML através do campo mdfeDadosMsg. A versão do leiaute da mensagem e o código da Unidade Federada (UF) requisitada são informados nos campos versaoDados e cUF, respectivamente, localizados no cabeçalho da mensagem (mdfeCabecMsg) do SOAP header.

Padrão de certificado digital

O certificado digital exigido deve ser emitido por Autoridade Certificadora credenciada pela Infraestrutura de Chaves Públicas Brasileira (ICP-Brasil), dos tipos A1 ou A3. Ele deve conter o CNPJ da pessoa jurídica ou CPF da pessoa física titular e possuir a extensão Extended Key Usage com permissão de "Autenticação Cliente", sendo utilizado na transmissão das mensagens entre o servidor do contribuinte e o Ambiente Autorizador.

Padrão de compactação

Para otimizar o uso da infraestrutura de rede, o padrão de compactação adotado é o Gzip (GNU zip), disponível em plataformas como Java e .NET framework 2.0. Cada documento na mensagem de retorno é compactado individualmente, e a aplicação cliente deve realizar a descompactação para o tratamento normal do documento. Estima-se uma redução de 60% no tamanho das mensagens de retorno.

Padrão de mensagens dos Web Services

As chamadas e retornos dos Web Services seguem um padrão com três componentes principais:
* cUF: código da UF de origem da mensagem.
* versaoDados: versão do leiaute da estrutura XML informada na área de dados.
* Área de Dados: estrutura XML variável definida na documentação do Web Service.

As informações de controle das chamadas (código da UF e versão do leiaute) são armazenadas no cabeçalho (mdfeCabecMsg) do SOAP Header. A área de dados contém o documento XML, que deve seguir o leiaute específico do Web Service acessado.

Validação da estrutura XML das mensagens

As mensagens trocadas com o Web Service são formatadas em XML, cuja estrutura é definida e controlada por um número de versão. A validação da estrutura XML é realizada por um analisador sintático (parser) que verifica a conformidade da mensagem com seu Schema XML (XSD). Qualquer divergência resulta em um erro de validação. A aplicação do contribuinte deve gerar mensagens no leiaute em vigor e informar a versão correta no campo versaoDados do cabeçalho da mensagem (mdfeCabecMsg).

Resumo dos padrões técnicos

Os padrões tecnológicos utilizados no serviço de distribuição incluem Web Services definidos pelo WS-I Basic Profile 1.1, meio lógico de comunicação via WebServices do Ambiente Autorizador do MDF-e, meio físico pela Internet, protocolo TLS 1.2 com autenticação mútua, padrão de troca de mensagens SOAP 1.2, mensagens XML Document/Literal, certificado digital X.509 versão 3 da ICP-Brasil (tipo A1 ou A3 com CNPJ/CPF), e compactação Gzip.

Serviço de distribuição MDF-e atores (MDFeDistribuicaoDFe)

Este serviço é responsável pela distribuição de informações de documentos fiscais eletrônicos para os atores do MDF-e, sejam pessoas físicas ou jurídicas. Ele permite acesso a DF-e não gerados pelo próprio ator, mas de seu interesse, utilizando certificado digital PJ ou PF. No caso de Pessoa Jurídica, a consulta pode ser feita com qualquer CNPJ da empresa, desde que o CNPJ base seja o mesmo do certificado digital.

Os documentos fiscais eletrônicos são disponibilizados para distribuição por até seis meses após sua recepção pelo Ambiente Nacional do MDF-e. Os tipos de documentos distribuídos para terceiros (identificados na tag de pessoas autorizadas a acessar o XML) incluem MDF-e, Evento de Cancelamento, Evento de Encerramento / Encerramento do Fisco, e Evento de Inclusão de Condutor.

Leiaute da mensagem de entrada

A mensagem de entrada é uma estrutura XML que contém a solicitação de consulta de MDF-e, seguindo o Schema XML distDFeInt_v9.99.xsd. Os principais campos são:

• distDFeInt: elemento raiz.
• versao: versão do leiaute.
• tpAmb: identificação do ambiente (1=Produção / 2=Homologação).
• CNPJ ou CPF: do interessado no DF-e.
• distNSU: grupo para distribuição de conjunto de DF-e a partir do Número Sequencial Único (NSU) informado.
  • ultNSU: último NSU recebido pelo ator. Se informado como zero ou muito antigo, a consulta retorna informações dos DF-e recepcionados nos últimos seis meses.
• consNSU: grupo para consultar um DF-e a partir de um NSU específico.
  • NSU: Número Sequencial Único. Utilizado para consultar um NSU faltante na base de dados do interessado.

Leiaute da mensagem de retorno

A mensagem de retorno é uma estrutura XML com o resultado da consulta, seguindo o Schema XML retDistDFeInt_v9.99.xsd. Contém:

• retDistDFeInt: elemento raiz da resposta.
• versao: versão do leiaute.
• tpAmb: identificação do ambiente.
• verAplic: versão do aplicativo que processou a consulta.
• cStat: código do status da resposta (ex: '137-Nenhum documento localizado', '138-Documento localizado').
• xMotivo: descrição literal do status.
• dhResp: data e hora da mensagem de resposta.
• ultNSU: último NSU pesquisado no Ambiente Nacional, permitindo ao solicitante continuar a busca.
• maxNSU: maior NSU existente no Ambiente Nacional para o CNPJ/CPF informado.
• loteDistDFeInt: conjunto de informações de documentos fiscais.
  • docZip: informação do documento fiscal eletrônico, compactada.
    • NSU: NSU do documento fiscal.
    • schema: identificação do Schema XML para validar o documento.

Mensagem de retorno compactada

Considerando o tamanho médio dos MDF-e (cerca de 10 KB), a compactação é utilizada para reduzir a carga na rede. Cada documento na mensagem de retorno é individualmente compactado (tag docZip) utilizando o padrão Gzip. A aplicação cliente é responsável por descompactar o documento para seu processamento normal.

Processo de distribuição de DF-e de interesse

Este serviço é acessível a pessoas autorizadas ao XML, contratantes e proprietários de veículos em MDF-e (quando o Registro Nacional de Transportadores Rodoviários de Cargas - RNTRC do proprietário for diferente do RNTRC do emitente), sejam pessoas físicas ou jurídicas com certificado digital. O Ambiente Nacional gera um NSU para cada interessado nos documentos fiscais, assegurando uma sequência numérica sem intervalos.

Geração do pedido de distribuição

O XML do pedido de distribuição suporta dois tipos de consultas, definidas pelas tags distNSU e consNSU.

distNSU: Distribuição de conjunto de DF-e a partir do NSU informado

A aplicação cliente informa o último NSU que possui (ultNSU). Se o NSU informado for menor que o primeiro NSU disponível, o Ambiente Nacional fornece os documentos a partir do primeiro. Os lotes de documentos são gerados com até 50 itens, em ordem crescente de NSU, e podem conter qualquer tipo de documento válido e seu respectivo NSU. Documentos emitidos pela própria empresa não estão disponíveis para consulta.

O processo de recepção e sincronização ocorre em ordem cronológica de emissão ou autorização de uso. A geração do NSU no Ambiente Nacional é assíncrona, permitindo que a empresa ou pessoa recupere todos os documentos de interesse assim que forem processados para distribuição. É recomendado manter um controle do primeiro NSU válido para consulta.

A resposta do Web Service pode ser:
* Rejeição: mensagem com o motivo da falha no cStat.
* Nenhum documento localizado: cStat='137-Nenhum documento localizado'.
* Documento localizado: cStat='138-Documento localizado'.

Para evitar consumo indevido, a empresa deve aguardar pelo menos uma hora antes de fazer uma nova solicitação se ultNSU for igual a maxNSU, indicando que não há novos documentos.

consNSU: Distribuição de DF-e vinculado ao NSU informado

Quando uma lacuna é identificada na base de dados do interessado (indicando uma falha no processo de distribuição), este processo permite a consulta pontual de um NSU específico. A aplicação cliente informa o NSU identificado como faltante na tag consNSU.

A resposta do Web Service para esta consulta pode ser:
* Rejeição: mensagem com o motivo da falha no cStat.
* Nenhum documento localizado: indica que o Ambiente Nacional não gerou o NSU, e o interessado deve desconsiderá-lo (cStat='137-Nenhum documento localizado').
* Documento localizado: com a devolução do documento fiscal encontrado (cStat='138-Documento localizado').

CNPJ ou CPF do interessado no DF-e

É necessário informar o CPF da pessoa ou CNPJ da empresa para a recuperação dos DF-e. Este campo permite que uma empresa recupere DF-e de seus diversos estabelecimentos utilizando um único certificado digital de Pessoa Jurídica.

Envio das informações

O pedido de distribuição é enviado via Web Service, exigindo o uso de um certificado digital de PJ ou PF válido. A aplicação cliente aciona o Web Service do Ambiente Nacional, enviando uma mensagem que atenda aos padrões estabelecidos.

Regras de validação básicas do serviço

O serviço possui regras de validação para garantir a segurança e a integridade das operações.

Validações de certificado digital

As regras de validação incluem a verificação de:
* Certificado de Transmissor inválido (inexistente, versão diferente de "3", Basic Constraint falso, KeyUsage sem "Autenticação Cliente").
* Validade do certificado.
* Cadeia de Certificação (certificado da AC emissora não cadastrado, revogado, não assinado pela AC).
* Lista de Certificados Revogados (LCR) do certificado de Transmissor.
* Certificado Raiz diferente de "ICP-Brasil".
* Falta da extensão de CNPJ ou CPF no certificado.
Muitas dessas validações são tratadas pelo protocolo TLS.

Validação inicial da mensagem no Web Service

A mensagem é rejeitada se o tamanho do XML de dados exceder 10 Kbytes (cStat='214-Rejeição: Tamanho da mensagem excedeu o limite estabelecido') ou se o XML estiver malformado (cStat='243-Rejeição: XML Malformado'). Também são feitas verificações se o serviço está paralisado momentaneamente (cStat='108-Serviço Paralisado Momentaneamente') ou sem previsão (cStat='109-Serviço Paralisado sem Previsão').

Validação das informações de controle da chamada

As informações no cabeçalho da mensagem (mdfeCabecMsg) são validadas. A ausência do elemento mdfeCabecMsg ou dos campos cUF e versaoDados, bem como a invalidade da UF ou versão dos dados, resultam na rejeição da solicitação.

Validação da área de dados da mensagem

A área de dados da mensagem é submetida a validações de forma, incluindo:
* Verificação do Schema XML.
* Ausência de namespaces diferentes do padrão.
* Ausência de caracteres de edição no início, fim ou entre as tags.
* Não uso de prefixo no namespace.
* Uso de codificação UTF-8.

Validações das regras de negócio

As regras de negócio validam a lógica da solicitação:
* Tipo de ambiente do MDF-e deve ser o mesmo do Web Service.
* CNPJ ou CPF do interessado na distribuição deve ser válido.
* CNPJ base do certificado digital deve ser o mesmo do CNPJ consultado (para PJ).
* CPF do certificado digital deve ser o mesmo do CPF consultado (para PF).
* NSU informado não pode ser superior ao maior NSU disponível para consulta.
* NSU informado não pode corresponder a documento autorizado há mais de seis meses, resultando na rejeição com cStat='730-Rejeição: NSU solicitado muito antigo'.

Recomendações para evitar o uso indevido

Para evitar a sobrecarga dos ambientes autorizadores, o sistema mantém controles contra o uso indevido, como tentativas sucessivas de buscar registros já disponibilizados. Aplicações que entram em "loop" e consomem recursos de forma excessiva serão rejeitadas com o erro cStat='678-Rejeição: Consumo indevido'.

Endereço do Web Service

O endereço do Web Service de Distribuição do Ambiente Nacional está disponível no Portal dos Documentos Fiscais Eletrônicos da SVRS (http://dfe-portal.svrs.gov.br/MDFe), na seção "Serviços" / "Relação de Serviços Web".

Os endereços para acesso são:
* Produção: https://mdfe.svrs.rs.gov.br/WS/MDFeDistribuicaoDFe/MDFeDistribuicaoDFe.asmx
* Homologação: https://mdfe-homologacao.svrs.rs.gov.br/WS/MDFeDistribuicaoDFe/MDFeDistribuicaoDFe.asmx

Tabela de códigos e descrições de mensagens de erros

A Nota Técnica 2015.002 inclui uma tabela com códigos e descrições detalhadas das mensagens de erro. Estes códigos indicam o resultado do processamento da solicitação (ex: Serviço Paralisado, Nenhum documento localizado, Documento localizado) ou os motivos de não atendimento (ex: Tamanho da mensagem excedido, XML Malformado, Certificado Transmissor inválido, Consumo indevido, NSU muito antigo). Esta tabela é uma referência para o tratamento de retornos do serviço.

Conclusão

O serviço de distribuição de DF-e para atores do MDF-e, regulamentado pela Nota Técnica 2015.002, estabelece uma arquitetura robusta para o acesso a documentos fiscais eletrônicos de interesse de terceiros. A padronização técnica, o uso de certificados digitais e as regras de validação garantem a segurança e a confiabilidade das informações. A capacidade de consultar por NSU específico ou por conjuntos de NSU, aliada à compactação de dados e controles de uso indevido, otimiza o fluxo de informações fiscais para empresas e contadores. A consulta aos códigos de erro permite o ajuste eficiente das aplicações clientes.