CTeDistribuicaoDFe: Acesse DF-e do CT-e via Web Service

O projeto Conhecimento de Transporte Eletrônico (CT-e) busca fornecer informações eficientes e confiáveis aos atores envolvidos em seus processos. A Nota Técnica 2015.002 apresenta o Web Service CTeDistribuicaoDFe, que disponibiliza informações e documentos fiscais eletrônicos (DF-e) de interesse desses atores.

A distribuição ocorre para emitentes, remetentes, destinatários, expedidores, recebedores, tomadores e terceiros autorizados no XML (tag: autXML). Para preservar o sigilo fiscal de documentos relacionados no CT-e (infDoc, docAntEle ou refCTe), as chaves de acesso de CT-e/NF-e são alteradas para o literal "999..." quando o solicitante está no grupo autXML. Para os demais atores, o XML retornado é o original.

O Web Service CTeDistribuicaoDFe e sua Finalidade

O CTeDistribuicaoDFe é um serviço assíncrono que distribui documentos e informações de interesse de um ator do CT-e, seja pessoa física ou jurídica. Ele permite o acesso a DF-e não gerados pelo ator solicitante, desde que sejam de seu interesse. O serviço pode ser consumido por qualquer ator de CT-e que possua certificado digital de PJ ou PF. No caso de Pessoa Jurídica, a autenticação ocorre pelo CNPJ base, e a consulta pode ser feita com qualquer CNPJ da empresa, desde que o CNPJ base consultado corresponda ao do certificado digital.

Os DF-e ficam disponíveis para distribuição por até 3 meses após sua recepção pelo Ambiente Nacional do CT-e. A distribuição abrange os papéis de emitente, destinatário, remetente, recebedor, expedidor, tomador e terceiros, conforme a seguir:

Documento	Emitente	Remetente, Destinatário, Recebedor, Expedidor, Tomador	Terceiros ¹
CT-e	Não	Sim	Sim
Evento de Cancelamento	Não	Sim	Sim
Evento de Carta de Correção	Não	Sim	Sim
EPEC	Não	Sim	Não
Eventos MDF-e Autorizado/Cancelado	Sim	Sim	Não
Evento Comprovante de Entrega	Sim	Sim	Sim

¹ Para terceiros, o CT-e está disponível somente se o CNPJ ou CPF estiverem informados no grupo autXML. Para esses usuários, todas as chaves de acesso de CT-e e NF-e relacionadas no CT-e são alteradas para o literal "999...", conforme decisão do ENCAT, para preservar o sigilo fiscal.

Estrutura da Mensagem de Entrada

A mensagem de entrada para o pedido de distribuição de DF-e é uma estrutura XML que utiliza o schema distDFeInt_v9.99.xsd. Ela suporta dois tipos de consultas, definidas pelas tags distNSU ou consNSU.

Campo	Tipo	Ocor.	Tam.	Descrição
distDFeInt	-	-	-	TAG raiz.
versao	N	1-1	2v2	Versão do leiaute.
tpAmb	N	1-1	1	Identificação do Ambiente: 1 = Produção / 2 = Homologação.
cUFAutor	N	1-1	2	Código da UF do Autor.
CNPJ	N	1-1	14	CNPJ do interessado no DF-e.
CPF	N	1-1	11	CPF do interessado no DF-e.
distNSU	-	1-1	-	Grupo para distribuir DF-e de interesse.
ultNSU	N		1-15	Último NSU recebido pelo ator. Se informado com zero ou um NSU antigo, a consulta retorna informações dos DF-e recepcionados pelo Ambiente Nacional nos últimos 3 meses.
consNSU	-	1-1	-	Grupo para consultar um DF-e a partir de um NSU específico.
NSU	N	1-1	1-15	Número Sequencial Único. Esta consulta é usada quando se identifica um NSU faltante, buscando o documento específico ou informando que o NSU não existe no Ambiente Nacional, fechando lacunas.

Estrutura da Mensagem de Retorno

A mensagem de retorno é uma estrutura XML que contém os documentos de interesse do ator, com uma quantidade máxima de 50 documentos. O schema XML utilizado é o retDistDFeInt_v9.99.xsd.

Campo	Tipo	Ocor.	Tam.	Descrição
retDistDFeInt	-	-	-	TAG raiz da Resposta.
versao	N	1-1	2v2	Versão do leiaute.
tpAmb	N	1-1	1	Identificação do Ambiente: 1 = Produção / 2 = Homologação.
verAplic	C	1-1	1-20	Versão do aplicativo que processou a consulta.
cStat	N	1-1	3	Código do status da resposta (conforme item 5 da NT).
xMotivo	C	1-1	1-255	Descrição literal do status da resposta.
dhResp	D	1-1		Data e hora da mensagem de Resposta.
ultNSU	N	0-1	1-15	Último NSU pesquisado no Ambiente Nacional, permitindo ao solicitante continuar a consulta a partir deste NSU.
maxNSU	N	0-1	1-15	Maior NSU existente no Ambiente Nacional para o CNPJ/CPF informado.
loteDistDFelnt	B64	0-1		Conjunto de informações de documentos fiscais eletrônicos de interesse da pessoa ou empresa.
docZip		1-50		Informação do documento fiscal eletrônico de interesse, compactado no padrão gZip. O tipo do campo é base64Binary.
NSU	N	1-1	1-15	NSU do documento fiscal.
schema	C	1-1		Identificação do Schema XML para validar o XML, indicando tipo e versão do documento (ex: procCTe_v2.00.xsd).

Mensagem de Retorno Compactada

Para otimizar o uso da infraestrutura de rede, cada documento na mensagem de retorno é compactado utilizando o padrão Gzip (GNU zip), na tag docZip. A compactação reduz o tamanho da mensagem em aproximadamente 60%. A aplicação do Ambiente Nacional compacta cada documento individualmente, e a aplicação cliente deve descompactá-lo para processamento.

Descrição do Processo de Distribuição de DF-e de Interesse

O serviço pode ser consumido por atores do CT-e (emitente, remetente, destinatário, expedidor, recebedor, tomador ou terceiro), pessoa física ou jurídica, utilizando um certificado digital de PF ou PJ. O Ambiente Nacional gera um Número Sequencial Único (NSU) para cada interessado nos documentos fiscais, garantindo uma sequência sem intervalos na base de dados.

Geração do Pedido de Distribuição

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

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

A aplicação cliente do Web Service informa o ultNSU que possui. Se o NSU fornecido for menor que o primeiro NSU disponível, a aplicação do Ambiente Nacional entrega os documentos a partir do primeiro disponível para consulta.

O Web Service gera lotes de até 50 documentos, com informações de DF-e que tenham NSU superior ao informado. Os lotes seguem as regras:
* Contêm qualquer tipo de documento válido e seu respectivo NSU.
* Apresentam ordem crescente de NSU.
* Têm quantidade máxima de 50 documentos.

Documentos emitidos pela própria empresa não estão disponíveis para consulta. A geração do NSU ocorre por ordem cronológica de recepção pelo Ambiente Nacional, não de emissão ou autorização de uso. Isso permite que a empresa ou pessoa recupere os documentos logo após serem recebidos pelo Ambiente Nacional do CT-e.
É necessário manter um controle do primeiro NSU válido para consulta.

As possíveis respostas são:
* Rejeição, com o motivo da falha no cStat.
* Documento localizado (cStat = "138-Documento localizado").
* Nenhum documento localizado (cStat = "137-Nenhum documento localizado").

Se o ultNSU informado for igual ao maxNSU do Ambiente Nacional, não há mais documentos a serem pesquisados no momento. A empresa deve aguardar no mínimo uma hora antes de fazer uma nova solicitação de distribuição.

Distribuição de DF-e Vinculado ao NSU Informado (consNSU)

Este processo permite consultar um DF-e específico a partir de um NSU. O Ambiente Nacional gera NSUs sem lacunas, e a identificação de uma lacuna na base de dados do interessado indica uma falha no processo de distribuição. Nesse caso, o interessado pode consultar pontualmente os NSUs faltantes através do método cteDistDFeInteresse, informando o NSU desejado na tag consNSU.

As respostas possíveis são:
* Nenhum documento localizado (cStat = "137-Nenhum documento localizado"), indicando que o Ambiente Nacional não gerou o NSU.
* Rejeição, com o motivo da falha no cStat.
* Documento localizado (cStat = "138-Documento localizado").

CNPJ ou CPF do Interessado no DF-e

É necessário informar o CPF da pessoa ou CNPJ da empresa para recuperar os DF-e de seu interesse. Isso permite que uma empresa recupere DF-e de qualquer um de seus estabelecimentos usando um único certificado digital PJ. O pedido de distribuição é enviado via Web Service, exigindo um certificado digital de PJ ou PF válido.

Validações no Web Service CTeDistribuicaoDFe

O Ambiente Nacional realiza diversas validações nas requisições recebidas pelo Web Service CTeDistribuicaoDFe.

Validação do Certificado de Transmissão

As validações do certificado digital de transmissão incluem:
* Certificado inexistente, versão diferente de "3", ou Basic Constraint inválido.
* KeyUsage não definindo "Autenticação Cliente".
* Validade do certificado (data início e data fim).
* Verificação da cadeia de certificação (AC emissora não cadastrada, AC revogada, certificado não assinado).
* LCR (Lista de Certificados Revogados) do certificado de transmissor (endereço LCR faltante, LCR indisponível, LCR inválida).
* Certificado de transmissor revogado.
* Certificado Raiz diferente da "ICP-Brasil".
* Falta da extensão de CNPJ (OID=2.16.76.1.3.3) ou CPF (OID=2.16.76.1.3.1) no certificado.

As validações A01 a A05 são realizadas pelo protocolo SSL e não precisam ser implementadas no aplicativo. A validação A06 também pode ser feita pelo SSL, mas pode falhar se existirem outros certificados de AC Raiz que não sejam "ICP-Brasil" no repositório do servidor.

Validação Inicial da Mensagem

O tamanho do XML de dados não pode ser superior a 10 KB. Mensagens que excedam esse limite podem ser descartadas sem retorno de erro se o controle for feito por configuração de rede (firewall). Caso o controle seja via aplicativo, pode ocorrer a devolução da mensagem de erro "214-Rejeição: Tamanho da mensagem excedeu o limite estabelecido".

Também são verificados os estados do serviço:
* "108-Serviço Paralisado Momentaneamente (curto prazo)".
* "109-Serviço Paralisado sem Previsão".
Essas validações podem ser dispensadas se o Web Service não estiver disponível quando o serviço estiver paralisado.

Validação da Área de Dados

A área de dados da mensagem é validada quanto à sua forma e regras de negócio.

Validação de forma da área de dados

• Falha no schema XML (cStat 215).
• Uso de prefixo de namespace não permitido (cStat 404).
• XML com codificação diferente de UTF-8 (cStat 402).
• Versão dos dados informada superior à versão vigente (cStat 238).
• Versão dos dados não suportada (cStat 239).

Validação de regras de negócio

• Tipo do ambiente do CT-e diferente do ambiente do Web Service (cStat 252).
• CNPJ do interessado inválido (dígito verificador ou zeros) (cStat 489).
• CPF do interessado inválido (dígito verificador ou zeros) (cStat 490).
• CNPJ base do certificado digital diferente do CNPJ base consultado (cStat 593).
• CPF do certificado digital diferente do CPF consultado (cStat 472).
• Número do NSU informado superior ao maior NSU disponível para consulta (cStat 589).

Modelo de Distribuição e Recomendações

O modelo de distribuição de documentos é baseado na geração de um Número Sequencial Único (NSU) para cada CNPJ ou CPF. A consulta no Web Service CTeDistribuicaoDFe pode ser feita a qualquer momento.

O fluxo de distribuição e consulta é exemplificado em etapas:
1. O emitente gera e transmite um CT-e, que é autorizado pela Sefaz e compartilhado com o Ambiente Nacional.
2. O Ambiente Nacional gera um NSU para o emitente, um para o destinatário e um para cada papel relacionado no CT-e, disponibilizando-os 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 para seu CT-e (ex: cancelamento), compartilhado pela Sefaz com o Ambiente Nacional.
5. O Ambiente Nacional gera um NSU para cada papel relacionado ao CT-e para o evento gerado pelo emitente, disponibilizando-os 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 para o destinatário (e outros NSUs para 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.

Prevenção ao Uso Indevido

Controles são mantidos para identificar tentativas sucessivas e indevidas de busca de registros já disponibilizados. Aplicações que entram em "loop", consumindo recursos de forma indevida, são rejeitadas com o erro "656-Rejeição: Consumo Indevido".

Endereços do Web Service

Os endereços do Web Service de Distribuição do Ambiente Nacional estão publicados no Portal do CT-e, no link "Serviços" / "Relação de Serviços Web". O mesmo ocorre para o ambiente de homologação no Portal de Homologação.

Mensagens de Rejeição

O serviço retorna códigos de status (cStat) e descrições (xMotivo) para indicar o resultado do processamento da solicitação. Alguns exemplos incluem:

Código	Resultado do Processamento da Solicitação
108	Serviço Paralisado Momentaneamente (curto prazo)
109	Serviço Paralisado sem Previsão
137	Nenhum documento localizado
138	Documento localizado
214	Rejeição: Tamanho da mensagem excedeu o limite estabelecido
215	Rejeição: Falha no schema XML
238	Rejeição: Cabeçalho - Versão do arquivo XML superior à Versão vigente
239	Rejeição: Cabeçalho - Versão do arquivo XML não suportada
252	Rejeição: Ambiente informado diverge do Ambiente de recebimento
280	Rejeição: Certificado Transmissor inválido
472	Rejeição: CPF consultado difere do CPF do Certificado Digital
489	Rejeição: CNPJ informado inválido (DV ou zeros)
490	Rejeição: CPF informado inválido (DV ou zeros)
589	Rejeição: Número do NSU informado superior ao maior NSU da base de dados do Ambiente Nacional
593	Rejeição: CNPJ-Base consultado difere do CNPJ-Base do Certificado Digital
656	Rejeição: Consumo Indevido

Recomenda-se que o campo xMotivo para o código 999 seja preenchido com a mensagem de erro do aplicativo ou sistema que gerou a exceção não prevista. Não se deve usar caracteres especiais ou acentuação nos textos das mensagens de erro.

Conclusão

O Web Service CTeDistribuicaoDFe, detalhado na Nota Técnica 2015.002, é um recurso para a gestão de documentos fiscais eletrônicos relacionados ao CT-e. Ele oferece aos diversos atores fiscais um meio para acessar DF-e de seu interesse de forma padronizada. A estrutura de requisição e retorno, as regras de validação e o modelo de distribuição por NSU visam garantir a integridade e a segurança do processo de consulta e recuperação de documentos, ao mesmo tempo que buscam evitar o uso indevido do serviço.