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.

Tributos.io

Remetente

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