Manual de Integração Consulta Automática de NFS-e Versão 2.1 Junho de 2014 1
Controle de Alterações Nome Data Thaís Oliveira 10/11/2013 Thaís Oliveira 03/01/2014 Thaís Oliveira 18/06/2014 Versão Observação 1.0 Criação do Documento 2.0 Padronização do Documento 2.1 Atualização do Documento 2
Índice 1. Introdução... 4 2. Considerações Iniciais... 4 2.1 Objetivos do Serviço... 4 2.2 Descrição simplificada do processo... 4 3. Arquitetura de Comunicação com o Cliente... 5 3.1 Modelo conceitual... 5 3.2 Padrões Técnicos... 5 3.2.1 Padrão de Documento XML... 5 3.2.2 Padrão de Comunicação... 6 3.3 Padrão de Mensagens dos Web Services... 6 3.3.1 Consulta com problemas... 6 3.3.2 Consulta com sucesso... 7 4. Web Services... 7 4.1 Leiaute da Mensagem de Requisição... 8 4.1.1 Leiaute de Parâmetros por Município... 8 4.2 Leiaute da Mensagem de Retorno com Erro... 8 5. Fluxo Operacional... 9 5.1 Etapas Operacionais... 9 5.1.1 Cadastramento... 9 6. Contato... 9 ANEXO I... 10 Tabela de informações técnicas... 10 Tabela de informações Gerais... 10 ANEXO II... 10 Tabela Código Ocorrência que serão retornados... 10 3
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 NFS-e. 2. Considerações Iniciais A SIM>Consultas, utilizando as mais avançadas tecnologias de robotização web, disponibiliza o XML da NFS-e, de maneira totalmente automática, através da consulta dos portais da NFS regionais utilizando seus links/parâmetros. 2.1 Objetivos do Serviço Facilitar e agilizar o processo de entrada dos dados contidos no endereço, fornecendo um arquivo XML da NFS-e, não assinado digitalmente, nos padrões de geração da NFS-e, 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 endereço de acesso da NFS-e, por digitação no campo indicado ou através da leitura 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 NFS-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 NFS-e oficial. Estando o Portal fora do ar ou apresentando problemas, ou ainda se a NFS-e não estiver disponível, indicando algum problema na sincronização, e não houver retorno no ambiente ocorrerá a indicação de NFS-e inexistente. 4
3. Arquitetura de Comunicação com o Cliente 3.1 Modelo conceitual O Fluxo de comunicação é iniciado pelo aplicativo do cliente através do envio de uma mensagem ao Web Service contendo o endereço da NFS-e, 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 NFS-e. 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. 3.2 Padrões Técnicos 3.2.1 Padrão de Documento XML A especificação do documento XML adotada é a recomendação W3C para XML 1.0, disponível em www.w3.org/tr/rec-xml e a codificação dos caracteres será em UTF-8, assim todos os documentos XML serão iniciados com a seguinte declaração: <?xml version= 1.0 encoding= UTF-8?> 5
3.2.2 Padrão de Comunicação 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="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:body> <GetNfse xmlns="http://simconsultas.com.br/"> <ChaveAcesso>string</ChaveAcesso> <Parametros>string</Parametros> </GetNfse> </soap:body> </soap:envelope> Exemplo de requisição HTTP GET GET /service.asmx/getnfse?chaveacesso=string¶metros=string HTTP/1.1 Host: ws.simconsultas.com.br Exemplo de requisição HTTP POST POST /service.asmx/getnfse HTTP/1.1 Host: ws.simconsultas.com.br Content-Type: application/x-www-form-urlencoded Content-Length: length ChaveAcesso=string&Parametros= string 3.3 Padrão 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: 3.3.1 Consulta com problemas Quando ocorrer algum problema com a consulta (Nota inexistente, Nota Cancelada), o padrão de retorno XML da Web Service será o seguinte: <?xml version="1.0" encoding="utf-8"?> <InfConsulta xmlns="http://www.simconsultas.com.br/web Service"> <StatusConsulta>100</StatusConsulta> <StatusDescricao> CTe / NFe / NFSe Cancelada</StatusDescricao> </InfConsulta> 6
3.3.2 Consulta com sucesso Nas condições normais será retornado um XML baseado no padrão desenvolvido pela SIM>Consultas. <XMLNfse xmlns:xsi="http://www.w3.org/2001/xmlschema-instance" xmlns:xsd="http://www.w3.org/2001/xmlschema"> <CompNfse> <Nfse Versao="1.00(SIMConsultas)"> <InfNfse> <CodigoVerificacao>9a8d785c</CodigoVerificacao> <ValoresNfse> <BaseCalculo>600</BaseCalculo> <Aliquota>4,26</Aliquota> <ValorIss>25,56</ValorIss> <ValorLiquidoNfse>600</ValorLiquidoNfse> </ValoresNfse> <PrestadorServico> <IdentificacaoPrestador> <CpfCnpj> <cnpj>67992347000139</cnpj> </CpfCnpj> <InscricaoMunicipal>00023791-4</InscricaoMunicipal> </IdentificacaoPrestador> <RazaoSocial>xxxxxxxxxxxxxx.</RazaoSocial> <Endereco> <Endereco> xxxxxxxxxxxxxxxxx </Endereco> <NomeMunicipio>CAMPINAS</NomeMunicipio> <Uf>SP</Uf> </Endereco> </PrestadorServico> <DeclaracaoPrestacaoServico> <InfDeclaracaoPrestacaoServico> <Servico> <Valores> <ValorDeducoes>0</ValorDeducoes> <ValorPis>0</ValorPis> <ValorCofins>0</ValorCofins> <ValorIr>0</ValorIr> <ValorCsll>0</ValorCsll> </Valores> <Discriminacao>xxxxxxxxxxxxxxxxxxx</Discriminacao> <NomeMunicipioIncidencia>CAMPINAS/SP</NomeMunicipioIncidencia> <ItemsNota> <Item> <DescricaoItem>xxxxxxxxxxxxxxxxx</DescricaoItem> <Tributavel>1</Tributavel> <Qtde>1</Qtde> <ValorUnitario>300</ValorUnitario> <ValorTotal>300</ValorTotal> </Item> <Item> 4. Web Services <DescricaoItem> 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: 7
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 GetNfse Raiz - - - - - TAG Raiz S2 ChaveAcesso E S1 C 1 36 Chave de acesso exclusiva do cliente fornecida previamente pela SIM>Consultas S3 Parametros E S1 C 1 - Município de acesso da NFS-e e endereço da NFS-e. Ex: municipio=&url='url 4.1.1 Leiaute de Parâmetros por Município Município Parâmetro Campinas municipio= &url='url' Belo Cnpj=&numero=&verificacao= Horizonte Blumenau municipio= &url='url' Ribeirão municipio= &url='url' Preto Rio de municipio= &url='url' Janeiro São Paulo municipio= &url='url' 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 StatusConsulta E R1 C 1 2 Código de Status informativo do erro ocorrido R3 StatusDescricao E R1 C 1 256 Texto descritivo sobre o problema ocorrido 8
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 NFS-e, 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 NFS-e, após acordo previamente realizado com o departamento comercial. 5.1.1 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-mail e telefone dos responsáveis operacionais para a equipe de suporte para que sejam cadastradas as informações para o devido envio. 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 e-mail suporte@simconsultas.com.br. 9
ANEXO I Tabela de informações técnicas # Tipo Conteúdo Descrição IT0 1 URL http://ws.simconsultas.com.br/service.asmx Endereço do Web Service IT0 2 URL http://ws.simconsultas.com.br/service.asmx?wsd L Endereço para acessar o IT0 3 IT0 4 IT0 5 Endereço s IP E-mail contato E-mail suporte WSDL 189.5.233.125, 189.126.104.158, 187.45.213.83 Endereços IP dos servidores da SIM>Consulta s para liberação em Firewall informativo@simconsultas.com.br suporte@simconsultas.com.br E-mail utilizado em comunicações automáticas enviadas pelos serviços. Liberar no Anti-SPAM. E-mail utilizado para comunicação de problemas ou esclarecimento de dúvidas. Tabela de informações Gerais # Tipo Conteúdo Descrição IG01 URL http://www.simconsultas.com.br/clientes 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 NFS-e Inexistente NFS-e Inexistente. FAÇA UMA CÓPIA DOS PARAMETROS E Ocorre quando o portal da NFS-e retorna a seguinte mensagem: 10
ENTREGUE AO RESPONSÁVEL. NFS-e INEXISTENTE. RE11 100 NFS-e Cancelada Nota Fiscal Eletrônica Cancelada pelo Emitente. Apenas é permitida Consulta Resumida para esta NFS-e. Ocorre quando o portal da NFS-e retorna a seguinte mensagem: 11