- 7. Web Services e API
7.1. Consulta situação do DF-e (NFe, NFC-e, CT-e ou MDF-e) - 7. Web Services e API
« Anterior - 7.2. WS da NF-e
Próximo »
7.1. Consulta situação do DF-e (NFe, NFC-e, CT-e ou MDF-e)
Consulta a situação de um DF-e (NFe, NFC-e, CT-e ou MDF-e)
Assinatura
int consStatusDFe(int tipoAmbiente, string nomeCertificado, out string msgDados, out string msgRetWS, out string msgResultado, string chaveDFe, string proxy, string usuario, string senha)
Descrição:
Consulta o status de um DF-e (NFe, NFC-e, CT-e ou MDF-e).
A consulta é realizada no Web Service "padrão", por isso, o resultado da consulta pode ser DF-e inexistente quando o documento fiscal tenha sido emitida em contingência OFF-LINE ou contingência da SEFAZ Virtual e ainda não tenha sido recepcionado ou sincronizado pela SEFAZ
Eventos do DF-e
A SEFAZ pode devolver os eventos vinculados no DF-e, assim esta funcionalidade pode ser útil para recuperar os eventos de cancelamento, carta de correção eletrônica, eventos da manifestação do destinatário, etc.
Preenchimento do nomeCertificado
informar o Nome do titular (campo Assunto) do certificado digital a ser utilizado na conexão SSL, formas possíveis:
1. uso de certificado digital existente no repositório MY do CSP do usuário corrente (currentuser)
É a forma de mais comum de uso, cabe ressaltar que é a única forma de uso de certificado digital do tipo A3 que a DLL oferece.
O usuário deve passar como parâmetro o campo assunto do certificado no parâmetro NomeCertificado para que a DLL localize um certificado digital com mesmo assunto no repositório MY do currentuser do equipamento.
Esta forma de uso requer a prévia instalação do certificado digital na conta do usuário do Windows (logon) que irá utilizar o certificado digital.2. uso de certificado digital em arquivo no formato pfx
Permite o de uso de certificado digital em arquivo formato pfx.
O caminho da localização (path) do arquivo pfx deve ser passado para a DLL no formato: ARQUIVO | [nome do arquivo pfx com caminho completo] | [senha do arquivo] no parâmetro NomeCertificado, ex.: "ARQUIVO|c:\certificado.pfx|senha".
Esta opção só funciona com certificado digital do tipo A1.3. uso de certificado digital em string base64
Permite uso o arquivo do certificado digital em formato pfx convertido em uma string base64. O certificado digital em string base64 deve ser passado para a DLL no formato: CERTIFICADO | [string base64 do arquivo pfx] | [senha do arquivo] no parâmetro NomeCertificado, ex.: "CERTIFICADO|MIIGoDCCBYigAwIBAgIQep(arquivo pfx do certificado digital convertido em base64...)QQDExNBQy|senha".
Esta opção só funciona com certificado digital do tipo A1. É uma opção de uso que oferece maior versatilidade, pois permite o armazenamento do certificado digital em banco de dados na aplicação. É a forma mais indicada para uso em ASP.NET.
Parâmetros:
| nome | tipo | fluxo | descrição |
|---|---|---|---|
| tipoAmbiente | inteiro | entrada | informar o código do ambiente desejado: 1- produção ou 2-homologação |
| NomeCertificado | string | entrada | informar o certificado digital que será utilizado para assinatura: 1. informar o assunto do certificado digital que deve existir no repositório MY do current user, ex.: "CN=NFe - Associacao NF-e:99999090910270, C=BR, L=PORTO ALEGRE, O=Teste Projeto NFe RS, OU=Teste Projeto NFe RS, S=RS". 2. informar: ARQUIVO | [nome do arquivo pfx com caminho completo] | [senha do arquivo] para uso do certificado digital em arquivo pfx, ex.: "ARQUIVO|c:\certificado.pfx|senha". 3. informar: CERTIFICADO | [string base64 do arquivo pfx] | [senha do arquivo] no parâmetro NomeCertificado para passar uma string contendo um certificado digital em base64, ex.:"CERTIFICADO|MIIGoDCCBYigAwIBAgIQep(arquivo pfx do certificado digital convertido em base64...)QQDExNBQy|senha". (novas opções) |
| msgDados | string | saída | retorna a mensagem XML enviada para o WS |
| msgRetWS | string | saída | retorna a mensagem XML de resposta do WS |
| msgResultado | string | saída | retorna a literal do resultado da chamada do WS |
| chaveDFe | string | entrada | informar a chave de acesso do DF-e que se deseja consultar |
| proxy | string | entrada | informar 'http://proxyserver:port' quando existir uso de proxy no ambiente. verificar com o cliente qual é o endereço do servidor proxy e a porta https, a porta padrão do https é 443, assim teríamos algo do tipo 'http://192.168.15.1:443' |
| usuario | string | entrada | informar o usuário para autenticação no proxy, se necessário |
| senha | string | entrada | informar a senha de autenticação no proxy, se necessário |
Retorno:
O resultado da chamada da Consulta Status de um DF-e é o código numérico com os seguintes significados:
| código | Mensagem | origem | regra |
|---|---|---|---|
| 5001 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: o certificado cliente: 1.não é ICP-Brasil; 2.fora do prazo de validade; 3.revogado; 4.certificado cliente não confiável para o Web Service acessado, contatar a SEFAZ) | DLL | - |
| 5002 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: a cadeia de certificação do Web Service acessado ou do certificado cliente inexistente no repositório de certificados do usuário corrente do Windows) | DLL | - |
| 5003 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: serviço inexistente, verifique se o nome do serviço da url acessada está correto no arquivo ws2.xml) | DLL | - |
| 5004 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: método não permitido) | DLL | - |
| 5005 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: a url não encontrada, verifique se o nome do domínio da url acessada está correto no arquivo ws2.xml) | DLL | - |
| 5006 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: Time-Out, o WS não respondeu a solicitação no tempo estabelecido: [{1:0}]) | DLL | - |
| 5007 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: mensagem maior que a permitida) | DLL | - |
| 5008 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: Servidor com problemas) | DLL | - |
| 5009 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: Serviço não implementado) | DLL | - |
| 5010 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: Serviço temporariamente indisponível, servidor sem recursos para atender a solicitação) | DLL | - |
| 5011 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: Causa provável da falha na conexão: Rede indisponível) | DLL | - |
| 5012 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: Versão do SOAP não suportada | DLL | - |
| 5013 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: Web Service não consumido, não houve nenhum retorno ou resposta) | DLL | - |
| 5014 | Erro: Falha na conexão: [MENSAGEM DE ERRO DO WINDOWS] (Causa provável: Web Service não consumido, falha desconhecida) | DLL | - |
| 5015 | Erro: Falha na conexão: Tempo limite de time-out alcançado [TEMPO DE TIME OUT UTILIZADO ms] - [MENSAGEM DE ERRO DO WINDOWS] | DLL | - |
| 5016 | Erro: Falha na conexão: Falha da Biblioteca Criptografica: [MENSAGEM DE ERRO DO WINDOWS] | DLL | - |
| 5017 | Erro: Falha ao tratar o XML de retorno do WS: [MENSAGEM DE ERRO DO WINDOWS] | DLL | - |
| 5101 | Erro: A mensagem de retorno do WS não é um XML válido: [MENSAGEM DE ERRO DO WINDOWS] | DLL | - |
| 5102 | Erro: Tag cStat inexistente na mensagem de retorno [MENSAGEM DE ERRO DO WINDOWS] | DLL | - |
| 5103 | Erro: Tag xMotivo inexistente na mensagem de retorno [MENSAGEM DE ERRO DO WINDOWS] | DLL | - |
| 5104 | Erro: Tag [NOME TAG] inexistente na mensagem de retorno [MENSAGEM DE ERRO DO WINDOWS] | DLL | - |
| 5105 | Erro: O WS não devolveu nenhum resultado | DLL | - |
| 5201 | Erro: O código do tipo de ambiente [CODIGO RECEBIDO PELA DLL] informado diferente de 1 - produção e 2 - homologação | DLL | - |
| 5202 | Erro: A sigla da UF [SIGLA RECEBIDA PELA DLL] informada é inválida | DLL | - |
| 5203 | Erro: Inexiste url para a UF [SIGLA UF] informada no ambiente [AMBIENTE] desejado, verifique se existe atualização do arquivo [NOME ARQUIVO] disponível. | DLL | - |
| 5204 | Erro: Arquivo que contem a URL do WS não localizado em [CAMINHO DA APLICACAO] | DLL | - |
| 5205 | Erro: Ocorreu um erro inesperado no processamento da URL (NOME URL) : [MENSAGEM DE ERRO DO WINDOWS] | DLL | - |
| 5206 | Erro: Ocorreu um erro de validação do XML (NOME XML) : [MENSAGEM DE ERRO DO WINDOWS] | DLL | - |
| 5403 | Erro: Falha ao acessar certificado digital [mensagem de ERRO DO WINDOWS] | DLL | - |
| 5404 | Erro: Nenhum certificado digital selecionado | DLL | |
| 5405 | Erro: Nenhum certificado válido foi encontrado com o nome [NomeCertificado] informado no repositório [MY do CurrentUser] | DLL | - |
| 5406 | Erro: Falha no tratamento do parâmetro nome: [nome informado] | DLL | - |
| 5407 | Erro: Quantidade de parâmetos inválido: [nome informado] | DLL | - |
| 5408 | Erro: Falha na criação do objeto certificate: [mensagem do ERRO DO WINDOWS] | DLL | - |
| 6104 | Erro: O parâmetro chaveDFe não informado | DLL | - |
| 6105 | Erro: O tamanho [TAMANHO DO PARAMETRO] do parâmetro chaveDFe informado não tem 44 caracteres | DLL | - |
| 6106 | Erro: As posições correspondentes (1,2) ao código da UF [POSIÇÃO DA CHAVE] do parâmetro chaveDFe não é um código de UF válido | DLL | - |
| 6107 | Erro: A chave de acesso deve ter 44 posições: [POSIÇÃO DA CHAVE] | DLL | - |
| 6110 | Erro: O nome do titular do certificado deve ser informado | DLL | - |
| 6123 | Erro: O parâmetro tipoAmbiente deve ser informado | DLL | - |
| 6124 | Erro: O parâmetro tipoAmbiente [CONTEUDO] deve ser 1 ou 2 | DLL | - |
| 100 | Autorizado o uso da NF-e | WS | - |
| 101 | Cancelamento de NF-e homologado | WS | - |
| 108 | Serviço Paralisado Momentaneamente (curto prazo) | WS | B03 |
| 109 | Serviço Paralisado sem Previsão | WS | B04 |
| 110 | Uso Denegado | WS | - |
| 214 | Rejeição: Tamanho da mensagem excedeu o limite estabelecido | WS | B01 |
| 215 | Rejeição: Falha no schema XML | WS | D01 |
| 216 | Rejeição: Chave de Acesso difere da cadastrada | WS | J04 |
| 217 | Rejeição: NF-e não consta na base de dados da SEFAZ | WS | J03 |
| 226 | Rejeição: Código da UF do Emitente diverge da UF autorizadora | WS | J02 |
| 236 | Rejeição: Chave de Acesso com dígito vereficador inválido | WS | J02a |
| 238 | Rejeição: Cabeçalho - Versão do arquivo XML superior a Versão vigente | WS | C05 |
| 239 | Rejeição: Cabeçalho - Versão do arquivo XML não suportada | WS | C06 |
| 242 | Rejeição: Cabeçalho - Falha no Schema XML | WS | C01 |
| 243 | Rejeição: XML Mal Formado | WS | B02 |
| 252 | Rejeição: Ambiente informado diverge do Ambiente de recebimento | WS | J01 |
| 280 | Rejeição: Certificado Transmissor inválido | WS | A01 |
| 281 | Rejeição: Certificado Transmissor Data Validade | WS | A02 |
| 282 | Rejeição: Certificado Transmissor sem CNPJ | WS | A07 |
| 283 | Rejeição: Certificado Transmissor - erro Cadeia de Certificação | WS | A03 |
| 284 | Rejeição: Certificado Transmissor revogado | WS | A05 |
| 285 | Rejeição: Certificado Transmissor difere ICP-Brasil | WS | A06 |
| 286 | Rejeição: Certificado Transmissor erro no acesso a LCR | WS | A04 |
| 299 | Rejeição: XML da área de cabeçalho com codificação diferente de UTF-8 | WS | C01a |
| 402 | Rejeição: XML da área de dados com codificação diferente de UTF-8 | WS | D03 |
| 404 | Rejeição: Uso de prefixo de namespace não permitido | WS | D02 |
| 410 | Rejeição: UF informada no campo cUF não é atendida pelo Web Service | WS | C03 |
| 411 | Rejeição: Campo versaoDados inexistente no elemento nfeCabecMsg do SOAP Header | WS | C04 |
| 516 | Rejeição: Falha no schema XML - inexiste a tag raiz esperada para a mensagem | WS | D01a |
| 561 | Rejeição: Mês de Emissão informado na Chave de Acesso difere do Mês de Emissão da NFe | WS | J05 |
| 562 | Rejeição: Código Numérico informado na Chave de Acesso difere do Código Numérico da NF-e | WS | J04 |
| 587 | Rejeição: Usar somente o namespace padrão da NF-e | WS | D01d |
| 588 | Rejeição: Não é permitida a presença de caracteres de edição no início/fim da mensagem ou entre as tags da mensagem | WS | D01e |
| 613 | Rejeição: Chave de Acesso diferente da existente em BD | WS | J06 |
| 614 | Rejeição: Chave de Acesso inválida (Código UF inválido) | WS | J02b |
| 615 | Rejeição: Chave de Acesso inválida (Ano < 05 ou Ano maior que Ano corrente) | WS | J02c |
| 616 | Rejeição: Chave de Acesso inválida (Mês < 1 ou Mês > 12) | WS | J02d |
| 617 | Rejeição: Chave de Acesso inválida (CNPJ zerado ou dígito inválido) | WS | J02e |
| 618 | Rejeição: Chave de Acesso inválida (modelo diferente que 55) | WS | J02f |
| 619 | Rejeição: Chave de Acesso inválida (número NF = 0) | WS | J02g |
| 656 | Rejeição: Consumo indevido | WS | - |
| 999 | Rejeição: Erro não catalogado (mensagem) | WS | - |
Histórico de atualização:
- 2026-10-12 - v1.00 - Versão beta preliminar.
Exemplos de uso:
Visual Basic 6.0
' declaração das variáveis que serão utilizadas na passagem de parâmetros da DLL ' Dim msgDados As String ' retorna a mensagem XML enviada para o WS Dim msgRetWS As String ' retorna a mensagem XML de resposta do WS Dim msgResultado As String ' retorna a literal do resultado da chamada do WS ' ' EXEMPLO para uso Nome do titular (campo Assunto) do certificado digital ' Dim nomeCertificado As String ' informar o Nome do titular (campo Assunto) do certificado digital a ser utilizado na conexão SSL. Ex.: "CN=NFe - Associacao NF-e:99999090910270, C=BR, L=PORTO ALEGRE, O=Teste Projeto NFe RS, OU=Teste Projeto NFe RS, S=RS" ' ' importante: indicar aqui assunto do certificado digital válido, este da associacao trata-se apenas de um exemplo para testes ' ' EXEMPLO PARA USO DE ARQUIVO PFX ' 'nomeCertificado = "ARQUIVO|c:\certificado.pfx|associacao" ' ' onde: ' ARQUIVO --> indica opção de uso de arquivo PFX ' c:\certificado.pfx --> nome e caminho do arquivo PFX ' associacao --> senha do arquivo PFX ' ' ' EXEMPLO PARA USO DE ARQUIVO PFX EM STRING BASE64 ' 'nomeCertificado = "CERTIFICADO|MIIGoDCCBYigAwIBAgIQep(arquivo pfx do certificado digital convertido em base64...)QQDExNBQy|senha" ' ' onde: ' CERTIFICADO --> indica opção de uso de arquivo PFX em base64 ' MIIGoDCCBYigAwIBAgIQep(arquivo pfx do certificado digital convertido em base64...)QQDExNBQy --> arquivo PFX em base64 ' senha --> senha do arquivo PFX ' Dim chaveNFe As String ' informar a chave de acesso da NF-e que se deseja consultar ' ' As variáveis do proxy devem ser informadas se necessário ' ' proxy deve ser informado com o endereço da url : porta, ex: 192.168.15.1:443 ' Dim proxy As String ' informar 'http://proxyserver:port' quando existir uso de proxy no ambiente. verificar com o cliente qual é o endereço do servidor proxy e a porta https, a porta padrão do https é 443, assim teríamos algo do tipo 'http://192.168.15.1:443' Dim usuario As String ' informar o usuário para autenticação no proxy, se necessário Dim senha As String ' informar a senha de autenticação no proxy, se necessário ' Dim tipoAmbiente As Integer ' informar o código do ambiente a ser consultado: 1- produção ou 2-homologação ' ' IMPORTANTE: todas as variáveis utilizadas como parâmetro da DLL devem ser inicializadas ' ' msgDados = "" ' retorna a mensagem XML enviada para o WS msgRetWS = "" ' retorna a mensagem XML de resposta do WS msgResultado = "" ' retorna a literal do resultado da chamada do WS ' ' prepara variáveis ' nomeCertificado = "CN=FLEXDOCS INFORMATICA LTDA:10142785000190, OU=presencial, OU=20085105000106, OU=RFB e-CNPJ A1, OU=Secretaria da Receita Federal do Brasil - RFB, L=OURINHOS, S=SP, O=ICP-Brasil, C=BR" tipoAmbiente = "1" ' informar o código do ambiente a ser consultado: 1- produção ou 2-homologação chaveDFe = "35100610142785000190550100000000018921770079" ' informar a chave de acesso do DF-e que deseja consultar" proxy = "" ' informar 'http://proxyserver:port' quando existir uso de proxy no ambiente. verificar com o cliente qual é o endereço do servidor proxy e a porta https, a porta padrão do https é 443, assim teríamos algo do tipo 'http://192.168.15.1:443' usuario = "" ' informar o usuário para autenticação no proxy, se necessário senha = "" ' informar a senha de autenticação no proxy, se necessário '/////////////////////////////////////////////////////////////////////////////////////// ' abre caixa de dialogo para informar a chave da DF-e '/////////////////////////////////////////////////////////////////////////////////////// Dim Message, Title, Default, MyValue Message = "Informe a chave do DF-e que será consultada" ' Set prompt. Title = "Consulta DF-e" ' Set title. Default = "35100610142785000190550100000000018921770079" ' Set default. ' Display message, title, and default value. chaveDFe = InputBox(Message, Title, Default) '/////////////////////////////////////////////////////////////////////////////////////// ' Dim cStat As Long Dim objNFeUtil As Object ' ' instancia a DLL (late binding) ' Set objdistDFe = CreateObject("distDFe.util") ' ' Screen.MousePointer = vbHourglass ' ampulheta cStat = objdistDFe.ConsStatusDFe(tipoAmbiente, _ nomeCertificado, _ msgDados, _ msgRetWS, _ msgResultado, _ chaveDFe, _ proxy, _ usuario, _ senha) ' ' Screen.MousePointer = vbDefault ' normal ' ' mostra mensagem XML enviada e a mensagem de retorno do WS ' MsgBox msgDados + Chr(13) + Chr(13) + msgResultado + Chr(13) + Chr(13) + msgRetWS, vbInformation, "Resultado da Consulta Status do DF-e"
- 7.1. Consulta situação do DF-e (NFe, NFC-e, CT-e ou MDF-e)
7. Web Services e API - « Anterior
7. Web Services e API - Próximo »
7.2. WS da NF-e