Web Service — Distribuição de DF-e do CT-e

2.1. Resumo

Um dos grandes desafios do projeto Conhecimento de Transporte Eletrônico é prover para os atores envolvidos nos processos do CT-e informações de seu interesse de forma eficiente e confiável.

Esta nota técnica tem como objetivo a apresentação de um novo Web Service denominado CTeDistribuicaoDFe que disponibilizará para os atores do CT-e informações e documentos fiscais eletrônicos de seu interesse. A distribuição será realizada para emitentes, remetentes, destinatários, expedidores, recebedores, tomadores e terceiros informados no conteúdo do CT-e respectivamente no grupo do Emitente (tag: emit), nos grupos do Remetente (tag: rem), Destinatário (tag: dest), Expedidor (tag: exped), Recebedor (tag: receb), Tomador (tag: toma4) e no grupo de pessoas autorizadas a acessar o XML (tag:autXML).

Visando a preservação do sigilo fiscal dos documentos fiscais eletrônicos relacionados no CT-e no grupo de documentos originários (infDoc), documentos anteriores (docAntEle) ou refCTe, este webservice deverá manipular o XML retornado alterando as chaves de acesso de CT-e/NF-e relacionadas pelo literal 99999999999999999999999999999999999999999999 conforme decisão do ENCAT, somente quando o ator solicitante da requisição ao serviço for um dos autorizados no grupo autXML, para todos os demais atores, o XML retornado deverá ser o original sem alteração.

Prazos para entrada em vigência da Nota Técnica:

• Ambiente de Homologação (ambiente de testes das empresas): 01/07/2015;
• Ambiente de Produção: 01/08/2015; Nota Técnica 2015/002

2.2. Web Service CTeDistribuicaoDFe

O serviço permite a qualquer ator do CT-e, pessoa física ou jurídica com certificado digital válido, consultar DF-e de seu interesse. Para pessoa jurídica, a autenticação considera o CNPJ-base.

¹ Para terceiros informados em autXML, as chaves de CT-e e NF-e relacionadas são substituídas pelo literal de 44 algarismos 9, para preservação do sigilo fiscal.

2.3. Leiaute da Mensagem de Entrada

Entrada: Estrutura XML com o pedido de distribuição de DF-e de interesse do ator Schema XML: distDFeInt_v9.99.xsd

2.4. Leiaute da Mensagem de Retorno

Retorno: Estrutura XML com os documentos de interesse do ator (qtde máxima=50). Schema XML: retDistDFeInt _v9.99.xsd

• procCTe_v2.00.xsd
• procEventoCTe_v2.00.xsd Nota Técnica 2015/002

2.5. Mensagem de Retorno Compactada

O tamanho médio do CT-e é de aproximadamente 10 KB, necessitando de um dimensionamento correto da rede interna e do canal de Internet das empresas e do Ambiente Nacional.

Para minimizar necessidades de infraestrutura de rede cada documento contido na mensagem de retorno da solicitação será compactado (tag:docZip). Estima-se que a compactação reduzirá o tamanho da mensagem de retorno em aproximadamente 60%.

A aplicação do Ambiente Nacional irá compactar individualmente cada documento da mensagem de retorno e a aplicação cliente deverá descompactá-lo e seguir o procedimento normal do tratamento do documento descompactado.

O padrão de compactação adotado para o projeto será o Gzip (GNU zip) que é implementado nas plataformas Java e .NET.

2.6. Processo de Distribuição de DF-e de Interesse

Este serviço pode ser consumido por atores que desempenham papel no CT-e de emitente, remetente, destinatário, expedidor, recebedor, tomador ou terceiro, Pessoa Física ou Jurídica, que possua um certificado digital de PF com seu CPF ou PJ com seu CNPJ.

O Ambiente Nacional gera um número sequencial único (NSU) para cada interessado nos documentos fiscais. Os documentos recuperados deverão conter uma sequência de numeração sem intervalos em sua base de dados.

a) Geração do pedido de distribuição

O XML do pedido de distribuição suporta dois tipos de consultas que são definidas de acordo com a tag informada no XML. As tags são distNSU e consNSU.

a.1) distNSU – Distribuição de Conjunto de DF-e a Partir do NSU Informado

A aplicação cliente do WS deve informar o último número sequencial único (ultNSU) que possui.

Caso o NSU informado seja menor que o primeiro NSU disponível para distribuição, a aplicação do Ambiente Nacional deverá fornecer os documentos a partir do primeiro disponível para consulta.

a.2) consNSU – Distribuição de DF-e Vinculado ao NSU Informado

Este processo de consulta DF-e a partir de um NSU permite que o interessado nos documentos fiscais consulte de maneira pontual um NSU que foi identificado como faltante em sua base de dados.

A aplicação cliente do WS deve informar o número sequencial único (NSU) identificado como faltante em sua base de dados.

b) CNPJ ou CPF do interessado no DF-e

Informar o CPF da pessoa ou CNPJ da empresa para recuperação de DF-e de seu interesse. Este campo possibilita que uma empresa consiga recuperar os DF-e de qualquer um de seus estabelecimentos utilizando somente um certificado digital PJ.

3.1. Processamento da Requisição de Distribuição de Conjunto de DF-e a Partir do NSU Informado (distNSU)

O Web Service deverá gerar lotes com até 50 documentos ao interessado com informações dos documentos fiscais eletrônicos que tenham o número sequencial único (NSU) superior ao NSU informado.

Caso o NSU informado seja menor que o primeiro NSU disponível para distribuição, a aplicação do Ambiente Nacional deverá fornecer os documentos a partir do primeiro disponível para consulta.

A criação do lote de documentos deverá observar as seguintes regras:

• Ordem crescente de NSU
• O lote poderá conter qualquer tipo de documento válido e seu respectivo NSU
• Quantidade máxima de documentos no lote: 50 documentos

Documentos emitidos pela própria empresa não estarão disponíveis para consulta.

Importante ressaltar que o processo de recepção e sincronização não será realizado em ordem cronológica de emissão ou autorização de uso, uma vez que a geração do NSU dos documentos será organizada por ordem cronológica de recepção pelo Ambiente Nacional.

Não existe necessidade de o Ambiente Nacional estar sincronizado em tempo real com todos os documentos fiscais autorizados. Como a geração do NSU será organizada por ordem de inserção de documentos, a empresa ou pessoa conseguirá recuperar todos os documentos de seu interesse tão logo estes sejam recebidos pelo Ambiente Nacional do CT-e.

É conveniente manter um controle do primeiro NSU válido para consulta.

A resposta do WS do Ambiente Nacional poderá ser:

• Rejeição - com a devolução da mensagem com o motivo da falha informado no cStat;
• Nenhum documento localizado – não existe documentos fiscais para o CNPJ/CPF informado – cStat=”137-Nenhum documento localizado”;
• Documento localizado – com a devolução dos documentos fiscais encontrados – cStat=”138-Documento localizado”.

A empresa deverá aguardar um tempo mínimo de uma hora para efetuar uma nova solicitação de distribuição caso receba a indicação que não existem mais documentos a serem pesquisados na base de dados do Ambiente Nacional. Se o NSU informado (tag:ultNSU) for igual ao maior NSU do Ambiente Nacional (tag:maxNSU), então não existem mais documentos a serem pesquisados no momento.

3.2. Processamento da Requisição de DF-e Vinculado ao NSU Informado (consNSU)

Considerando que o Ambiente Nacional gera NSU sem lacunas, o processo de distribuição de conjunto de DF-e a partir do NSU informado (tag:distNSU) disponibiliza para o interessado uma sequência de numeração ordenada de forma ascendente. A identificação de alguma lacuna na base de dados do interessado indica que houve alguma falha no processo de distribuição dos documentos.

Neste caso, o interessado deve consultar pontualmente os NSU identificados como faltantes em sua base de dados através do método cteDistDFeInteresse do Web Service CTeDistribuicaoDFe informando o NSU desejado no conteúdo da tag consNSU no XML de requisição.

A resposta do WS poderá ser:

• Rejeição - com a devolução da mensagem com o motivo da falha informado no cStat;
• Nenhum documento localizado – indicando 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”.

3.3. Validação do Certificado de Transmissão

A validação do certificado de transmissão segue o Grupo A da página Regras de Validação.

3.4. Validação Inicial da Mensagem no Web Service

A mensagem acima de 10 KB poderá ser descartada ou provocar a interrupção da conexão. As verificações 108 e 109 podem ser dispensadas se o Web Service ficar indisponível durante a paralisação.

3.5. Validação da Área de Dados

a) Validação de forma da área de dados

b) Validação de regras de negócio

3.6. Visão Geral do Modelo de Distribuição

O modelo de distribuição de documentos é baseado na geração de um número sequencial único (NSU) para cada CNPJ ou CPF. O fluxo abaixo exemplifica a geração do NSU para o emitente e destinatário do CT-e:

A consulta no Web Service CTeDistribuicaoDFe poderá ser realizada a qualquer instante pela empresa ou pessoa. O Ambiente Nacional disponibilizará para consulta os documentos de interesse de cada ator. Seguem os passos do fluxo exemplificado:

1. O emitente gera e transmite um CT-e que será autorizada pela Sefaz e compartilhada com o Ambiente Nacional;
2. O Ambiente Nacional gera um NSU para o emitente, um NSU para destinatário e um NSU para cada um dos papéis relacionados no CT-e e o disponibiliza para consulta;
3. O destinatário consulta o WS CTeDistribuicaoDFe a partir do último NSU recebido e recupera o XML do CT-e;
4. O emitente gera um evento de seu CT-e (ex.: evento de cancelamento de CT-e, caso não exista outro evento que impeça este cancelamento) que será compartilhado pela Sefaz com o Ambiente Nacional;
5. O Ambiente Nacional gera um NSU para o cada um dos papéis relacionados com o CT-e para o evento gerado pelo emitente e o disponibiliza para consulta;
6. O destinatário consulta o WS CTeDistribuicaoDFe a partir do último NSU recebido e recupera o evento gerado pelo emitente;
7. O Ambiente Nacional recebe um evento gerado pelo fisco e gera um NSU para o emitente, outro NSU para o destinatário (e tantos NSU quantos forem os papéis relacionados), disponibilizando-os para consulta;
8. Tanto o emitente quanto o destinatário consultam o WS CTeDistribuicaoDFe a partir do último NSU recebido e recuperam o evento gerado pelo fisco;

4.1. Recomendações Para Evitar o Uso Indevido

A análise do comportamento atual das aplicações das empresas (“aplicação cliente”) permite identificar algumas situações de “uso indevido” nos ambientes autorizadores.

Como exemplo maior do mau uso do ambiente, ressalta-se a falta de controle de algumas aplicações que entram em “loop”, consumindo recursos de forma indevida, sobrecarregando principalmente o canal de comunicação com a Internet.

Para este Web Service serão mantidos controles para identificar as situações de uso indevido de sucessivas tentativas de busca de registros já disponibilizados anteriormente.

As novas tentativas serão rejeitadas com o erro “656–Rejeição: Consumo Indevido”.

4.2. Endereço do Web Service

O endereço do Web Service de Distribuição do Ambiente Nacional está publicado no Portal do CT-e (http://www.cte.fazenda.gov.br/portal), no link “Serviços” / “Relação de Serviços Web”.

Idem para o ambiente de homologação, no Portal de Homologação (http://hom.cte.fazenda.gov.br/portal)

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

Resultados do Processamento da Solicitação

Motivos de Não Atendimento da Solicitação

OBS.:

• Recomendado a não utilização de caracteres especiais ou acentuação nos textos das mensagens de erro.
• Recomendado que o campo xMotivo da mensagem de erro para o código 999 seja informado com a mensagem de erro do aplicativo ou do sistema que gerou a exceção não prevista.