Manual de Integração Consulta Automática de DANFE

Transcrição

1 Manual de Integração Consulta Automática de DANFE Versão 2.0 Junho de

2 Controle de Alterações Nome Data Versão Observação Thaís Oliveira 03/01/ Atualização do documento Thaís Oliveira 18/06/ Atualização do Documento 2

3 Índice 1. Introdução Considerações Iniciais Objetivos do Serviço Descrição simplificada do processo Arquitetura de Comunicação com o Cliente Modelo conceitual Padrões Técnicos Padrão de Documento XML Padrão de Comunicação Padrões de Mensagens dos Web Services Consultas com problemas Consulta com sucesso Web Services Leiaute da Mensagem de Requisição Leiaute da Mensagem de Retorno com Erro Leiaute da Mensagem de Retorno com Sucesso Impressão de DANFE incorporada no XML Fluxo Operacional Etapas Operacionais Cadastramento Notificação de Ocorrências Contato ANEXOS

4 1. Introdução Este documento tem por objetivo informar a definição das especificações e critérios técnicos necessários para a integração entre o Web Service da SIM>Consultas e os sistemas de nossos clientes para utilização do XML de conteúdo da NF-e recuperado através da chave do DANFE. 2. Considerações Iniciais A SIM>Consultas, utilizando as mais avançadas tecnologias de robotização web, disponibiliza o XML da NF-e, de maneira totalmente automática, através da consulta da chave de acesso da NF-e contida no DANFE, atendendo todas as regras definidas no Manual de Integração da NF-e versão NT Objetivos do Serviço Facilitar e agilizar o processo de entrada dos dados contidos na DANFE, fornecendo um arquivo XML da NF-e, não assinado digitalmente, nos padrões de geração da NFe, possibilitando a entrada automatizada destes dados nos sistemas dos clientes, garantindo velocidade, segurança e confiabilidade ao processo. 2.2 Descrição simplificada do processo O cliente através de seus sistemas ou através da página web da SIM>Consultas, captura o número da chave de acesso da NF-e, por digitação no campo indicado ou através da leitura do código de barras do DANFE com equipamento apropriado. A informação é transmitida para o Servidor da SIM>Consultas por conexão de WebService ou acionamento do botão consulta na página da SIM>Consultas especificamente destinada a este fim. O Servidor da SIM>Consultas localiza a NF-e através de um programa robô que faz a leitura, estruturando os dados retornados, e gerando um arquivo no formato XML, no mesmo padrão da NFe oficial. Estando o Portal Nacional fora do ar ou apresentando problemas, ou ainda se a NF-e não estiver disponível no Ambiente Nacional, indicando algum problema na sincronização entre os servidores do portal Nacional e dos Sefaz de cada estado, o programa robô automaticamente desvia a consulta para os sites dos Sefaz de cada 4

5 Estado buscando os dados da NFe na origem onde foram geradas. Somente, quando não houver retorno nos dois ambientes ocorrerá a indicação de NF-e inexistente. 3. Arquitetura de Comunicação com o Cliente 3.1 Modelo conceitual A SIM>Consultas disponibilizará os seguintes tipos de consulta Consulta Completa Consulta Simplificada (Transportadoras) Consulta Resumida Estas formas de consulta serão oferecidas através do Web Service da SIM>Consultas. O Fluxo de comunicação é iniciado pelo aplicativo do cliente através do envio de uma mensagem ao Web Service contendo o número da Chave de Acesso da NFe, o tipo de consulta (de acordo com a tabela do item 4.1 instrução S4) e a chave de acesso exclusiva fornecida para cada cliente. O Web Service sempre devolve uma mensagem de resposta no formato XML contendo, no caso de falhas, as informações sobre a ocorrência e em caso de sucesso os dados em XML no formato padrão da NFe. O Serviço é síncrono, ou seja, o processamento da solicitação de consulta é concluído na mesma conexão, com a devolução imediata da resposta. O diagrama a seguir ilustra o fluxo conceitual de comunicação entre o aplicativo do cliente e o servidor da SIM>Consultas. 5

6 3.2 Padrões Técnicos Padrão de Documento XML A especificação do documento XML adotada é a recomendação W3C para XML 1.0, disponível em e a codificação dos caracteres será em UTF-8, assim todos os documentos XML serão iniciados com a seguinte declaração: Padrão de Comunicação <?xml version= 1.0 encoding= UTF-8?> A comunicação será baseada em Web Services disponibilizados pela SIM>Consultas. A troca de mensagens entre o Web Service da SIM>Consultas e o aplicativo do cliente pode ser realizada utilizando o padrão SOAP, HTTP GET ou HTTP POST. Exemplo de uma mensagem requisição padrão SOAP: <?xml version="1.0" encoding="utf-8"?> <soap:envelope xmlns:xsi=" xmlns:xsd=" xmlns:soap=" <soap:body> <GetNfeTipo xmlns=" <chaveacesso>string</chaveacesso> <chavenfe>string</chavenfe> <Tipo>int</Tipo> </GetNfeTipo> </soap:body> </soap:envelope> Exemplo de requisição HTTP GET GET /service.asmx/getnfetipo?chaveacesso=string&chavenfe=string&tipo=string HTTP/1.1 Host: ws.simconsultas.com.br Exemplo de requisição HTTP POST POST /service.asmx/getnfetipo HTTP/1.1 Host: ws.simconsultas.com.br Content-Type: application/x-www-form-urlencoded Content-Length: length chaveacesso=string&chavenfe=string&tipo=string 6

7 3.3 Padrões de Mensagens dos Web Services As chamadas do Web Service da SIM>Consultas serão respondidas através de mensagens com o seguinte padrão: Consultas com problemas Quando ocorrer algum problema com a consulta (Site fora do ar, Nota inexistente, Dígito verificador inválido, etc), o padrão de retorno XML do Web Service será o seguinte: <?xml version="1.0" encoding="utf-8"?> <InfConsulta xmlns=" Service"> <StatusConsulta>25</StatusConsulta> <StatusDescricao>DV (dígito verificador) da chave de acesso inválido. Verificar o número da chave de acesso e digitá-lo novamente.</statusdescricao> </InfConsulta> Consulta com sucesso Nas condições normais será retornado um XML no padrão da NFe, descrito no Manual de Integração do Contribuinte disponível no portal da NF-e da Sefaz. <?xml version="1.0" encoding="utf-8"?> <NFe xmlns=" <infnfe Id="NFe " versao="1.10"> <OrigemNFe> <SefazOrigem>SP</SefazOrigem> </OrigemNFe> <ide> <cuf>35</cuf> <cnf> </cnf> <mod>55</mod> <serie>1</serie> <nnf> </nnf> <demi> </demi> <cmunfg> </cmunfg> <tpimp>1</tpimp> <cdv>0</cdv> <tpamb>1</tpamb> </ide> <emit> <CNPJ> </CNPJ> <xnome>sanofi-aventis COMERCIAL E LOGISTIC A</xNome> <enderemit> <xlgr>estrada DA CRUZ GRANDE</xLgr> <nro>1700</nro> <xbairro>santo ANTONIO</xBairro> <cmun> </cmun> <xmun>louveira</xmun> <UF>PB</UF> <CEP> </CEP> <cpais>1058</cpais> <xpais>brasil</xpais> <fone> </fone> </enderemit> <IE> </IE> </emit> 7

8 4. Web Services O Web Service da SIM>Consultas disponibiliza o serviço que será utilizado pelos aplicativos dos clientes. O mecanismo de utilização do Web Service segue as seguintes premissas: a) O envio da solicitação e a obtenção do retorno serão realizados na mesma conexão através de um único método. b) A URL do Web Service encontra-se no Anexo I deste manual. Acessando a URL pode ser obtido o WSDL (Web Services Description Language) do Web Service. c) O processo de utilização do Web Service sempre é iniciado pelo cliente enviando uma mensagem no padrão XML SOAP ou HTTP GET ou HTTP POST. 4.1 Leiaute da Mensagem de Requisição # Campo Ele Pai Tipo Ocor. Tam Dec Descrição/ Observação S1 GetNfeTipo Rai TAG Raiz z S2 ChaveAcess o E S1 C 1 36 Chave de acesso exclusiva do cliente fornecida previamente pela SIM>Consultas S3 ChaveNfe E S1 C 1 44 Número da chave de acesso da NF-e a ser consultada com 44 posições S4 Tipo E S1 C Consulta Completa 11 Consulta Completa apenas no SEFAZ 2 Consulta Transportadoras 21 Consulta Transportadoras apenas no SEFAZ 8

9 3 Consulta Resumida 31 Consulta Resumida apenas no SEFAZ 4 Consulta Completa com Impressão de DANFE PDF incorporada no XML da NFE 41 Consulta Completa apenas no SEFAZ com Impressão de DANFE PDF incorporada no XML da NFE. 4.2 Leiaute da Mensagem de Retorno com Erro # Campo Ele Pai Tipo Ocor. Tam Dec Descrição/ Observação R1 InfConsulta Raiz TAG Raiz R2 R3 StatusConsult a StatusDescric ao E R1 C 1 2 Código de Status informativo do erro ocorrido E R1 C Texto descritivo sobre o problema ocorrido 4.3 Leiaute da Mensagem de Retorno com Sucesso Acesse o manual de integração do contribuinte no portal da NF-e disponível em Documentos > Manuais do portal nacional e veja o Anexo I. 4.4 Impressão de DANFE incorporada no XML Utilizando o Tipo de consulta 4 é gerada a impressão do DANFE correspondente à NF-e consultada em formato PDF. Este arquivo PDF é convertido em formato String Base 64 (similar ao anexo de s) e incorporado no próprio XML de retorno. No ANEXO IV é possível encontrar as informações técnicas sobre como decodificar este conteúdo e gerar o arquivo PDF em disco. 9

10 5. Fluxo Operacional A SIM>Consultas disponibiliza um canal direto com o departamento de operações que será responsável pelo suporte ao serviço de consulta da NFe, o objetivo é prestar todo apoio necessário para que o processo das consultas funcione corretamente, tanto nas etapas de testes e integração e na fase de operação dos serviços. 5.1 Etapas Operacionais Detalhamento das etapas necessárias para realização dos testes e implantação do serviço de consultas da NFe, após acordo previamente realizado com o departamento comercial Cadastramento O Cliente/Parceiro receberá junto à documentação completa necessária para configuração e implantação dos serviços contratados, suas informações de login, sendo um usuário e uma senha para acesso ao Portal de Clientes SIM>Consultas através do endereço portal.simconsultas.com.br. Através deste portal, será possível realizar consultas, visualizar o extrato das consultas realizadas, bem como exportá-las se necessário. E também recebe uma chave de acesso exclusiva para comunicação via Web Service, assim como créditos para a utilização das consultas liberados pelo departamento comercial após a negociação. Para conhecer mais sobre este Portal, solicite ao departamento de suporte o envio do manual de utilização do mesmo. A SIM Consultas conta com um serviço de notificações e comunicados quando necessário, em casos de instabilidade e outros fatores. Para receber essas notificações é necessário informar o e telefone dos responsáveis operacionais para a equipe de suporte para que sejam cadastradas as informações para o devido envio Notificação de Ocorrências De acordo com o ANEXO II, o cliente/parceiro deve criar uma rotina na sua operação interna para que as ocorrências do tipo: 3 NF-e Inexistente e 55 Chave informada não é de uma NF-e tenham suas DANFE digitalizadas e entregues ao responsável operacional do projeto, que por sua vez enviará para a análise da SIM>Consultas através do suporte@simconsultas.com.br. 10

11 6. Contato Dúvidas? Acesse nossa central de ajuda pelo endereço simconsultas.zendesk.com ou entre em contato com nosso setor de Suporte e Operações através do suporte@simconsultas.com.br. 11

12 ANEXOS Anexo I Tabela de informações técnicas # Tipo Conteúdo Descrição IT01 URL Endereço do Web Service IT02 URL Endereço para acessar o IT03 Endereços IP IT04 contato IT05 suporte Tabela de informações Gerais Favor entrar em contato, caso seja necessário a liberação dos IP utilizados. informativo@simconsultas.com.br suporte@simconsultas.com.br WSDL Endereços IP dos servidores da SIM>Consultas para liberação em Firewall utilizado em comunicações automáticas enviadas pelos serviços. Liberar no Anti-SPAM. utilizado para comunicação de problemas ou esclarecimento de dúvidas. # Tipo Conteúdo Descrição IG01 URL Portal para acompanhamento de consultas realizadas, estatísticas, avisos gerais, etc. ANEXO II Tabela Código Ocorrência que serão retornados # Código Ocorrência Mensagem Retornada Descrição RE01 3 NF-e Inexistente NF-e Inexistente no Portal Nacional e Fazenda Estadual. FAÇA UMA CÓPIA DO DANFE E ENTREGUE AO Ocorre quando o portal da NF-e retorna a seguinte mensagem: NF-e INEXISTENTE na base nacional, favor 12

13 RE02 4 Falha na Consulta RESPONSÁVEL. Ocorreu um problema ao consultar esta NF-e. Por favor tente novamente. Se o problema persistir contate o Responsável. consultar esta NF-e no site da SEFAZ de origem. Ao receber esta mensagem o programa faz automaticamente a consulta no Sefaz Estadual correspondente e neste caso a nota também é inexistente ou não temos ainda implementada a consulta para o Estado. Consulte Anexo III. Ocorre por falha geral no processo de consulta. (Timeout, falha na conexão, etc.) RE03 7 RE04 19 RE05 25 Portal Fora de funcionamento NF-e emitida em contingência. Chave de acesso informada Portal da NF-e indisponível. Nota Fiscal Eletrônica emitida em contingência e ainda não autorizada pela SEFAZ. Apenas é permitida a Consulta Resumida para esta NF-e. DV (dígito verificador) da chave de acesso digitada {Chave de Acesso} Ocorre quando o portal da NF-e retorna a seguinte mensagem: Não foi possível consultar dados da NFe. Ao receber esta mensagem o programa faz automaticamente a consulta no Sefaz Estadual correspondente e neste caso a consulta ao Sefaz falhou ou não temos ainda implementada a consulta para o Estado. Consulte Anexo III. Ocorre quando o portal da NF-e retorna a seguinte mensagem: Nota Fiscal Eletrônica emitida em contingência e ainda não autorizada pela SEFAZ. Apenas é permitida a Consulta Resumida para esta NFe. Ocorre quando a chave de acesso informada para consulta é inválida. O 13

14 RE06 31 inválida. Dígito não confere. NFe emitida a mais de 180 dias. Dados indisponíveis inválido. Verificar o número da chave de acesso e digitá-lo novamente. A consulta a todos os dados da NF-e fica disponível por até 180 dias após a data de emissão da nota. dígito verificador não confere. Ocorre quando o portal da NF-e retorna a seguinte mensagem: A consulta a todos os dados da NF-e fica disponível por até 180 dias após a data de emissão da nota. RE07 55 Chave informada não é de uma NF-e O Número da Chave de Acesso digitado {Chave de Acesso} não corresponde a uma NF-e. A NF-e utiliza o Modelo 55. Verifique se o número foi digitado corretamente e tente novamente! Se o problema persistir FAÇA UMA CÓPIA DO DANFE E ENTREGUE AO RESPONSÁVEL. Ocorre quando ao verificar os caracteres nas posições 21 e 22 do número da chave de acesso informada, que representam o Modelo, é retornado um valor diferente de 55. RE08 56 RE09 57 RE10 98 RE A Data de Emissão informada na chave de acesso é inválida O Código UF informado na chave de acesso é inválido Falha na consulta NF-e Cancelada A Data de Emissão informada na chave de acesso é inválida O Código UF informado na chave de acesso é inválido Ocorreu um problema na sincronização dos dados da NF-e. Por favor tente novamente. Nota Fiscal Eletrônica Cancelada pelo Emitente. Apenas é permitida Consulta Resumida para esta NF-e. Ocorre quando a data de emissão, embutida na formação da chave da nota, não é uma data válida Ocorre quando o código da UF, embutido na formação da chave da nota, não é o código de uma UF válida Ocorre quando ocorre um erro no servidor do portal Nacional no momento do Parse de uma consulta. O Portal retorna os dados de uma nota Y na consulta de uma nota X. Ocorre quando o portal da NF-e retorna a seguinte mensagem: Nota Fiscal Eletrônica Cancelada pelo Emitente. Apenas é 14

15 ANEXO III permitida Consulta Resumida para esta NFe. Tabela Disponibilidade de Serviço SEFAZ Estadual UF Dados Gerais Itens da Nota Portal Utilizado URL AC SIM SIM SEFAZ AL SIM SIM SEFAZ A - - M AP SIM SIM SEFAZ BA Geral/NFENC_consulta_chave_acesso.aspx CE e.jsf DF SIM SIM SEFAZ ES nsulta/consultanfe.php GO pletanfe.html M A M G SIM SIM SEFAZ MG l MS SIM SIM SEFAZ M T ecompleta PA - - PB SIM SIM SEFAZ PE - - PI DePesquisa_Completa.jsp PR conteudo.php?conteudo=296 RJ SIM SIM SEFAZ RN _NFe/web/frm_consulta.aspx RO SIM SIM SEFAZ 15

16 RR SIM SIM SEFAZ RS SIM SIM SEFAZ SC SIM SIM SEFAZ SE SIM SIM SEFAZ SP SIM SIM SEFAZ SP TO SIM SIM SEFAZ ANEXO IV a/publica/consultarnfe.aspx Informações técnicas impressão DANFE PDF Leiaute do Retorno XML (Apenas parte referente ao anexo PDF. Para consultar todos os campos do retorno é necessário utilizar o Manual de Integração da NF-e disponível no portal nacional da Nota Fiscal Eletrônica em # Campo Ele Pai Tipo Ocor. Tam Dec Descrição/ Observação R0 1 NFE Rai z TAG Raiz R0 2 infnfe E R01 C 1 - R0 3 Base64StringP DFDanfe E R02 C 1 - R0 4 Content E R03 C 1 - Conteúdo do arquivo PDF Codificado em Base64String Exemplo C# Geração do arquivo PDF com base no retorno XML WS.SIMConsultasService s = new WSP.SIMConsultasService(); XmlNode n = s.getnfetipo("chaveacessosim", "NUMERONFE", 4); XmlDocument doc = new XmlDocument(); doc.loadxml(n.outerxml); byte[] pdf = Convert.FromBase64String(doc.GetElementByTagName("Content")[0].InnerTe xt); System.IO.File.WriteAllBytes("CaminhoArquivo.pdf",pdf); 16