Manual de Integração Consulta Automática de NFS-e

Transcrição

1 Manual de Integração Consulta Automática de NFS-e Versão 2.1 Junho de

2 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

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ão de Mensagens dos Web Services Consulta com problemas Consulta com sucesso Web Services Leiaute da Mensagem de Requisição Leiaute de Parâmetros por Município Leiaute da Mensagem de Retorno com Erro Fluxo Operacional Etapas Operacionais Cadastramento Contato... 9 ANEXO I Tabela de informações técnicas Tabela de informações Gerais ANEXO II Tabela Código Ocorrência que serão retornados

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 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

5 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 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: <?xml version= 1.0 encoding= UTF-8?> 5

6 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=" xmlns:xsd=" xmlns:soap=" <soap:body> <GetNfse xmlns=" <ChaveAcesso>string</ChaveAcesso> <Parametros>string</Parametros> </GetNfse> </soap:body> </soap:envelope> Exemplo de requisição HTTP GET GET /service.asmx/getnfse?chaveacesso=string&parametros=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: 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=" Service"> <StatusConsulta>100</StatusConsulta> <StatusDescricao> CTe / NFe / NFSe Cancelada</StatusDescricao> </InfConsulta> 6

7 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=" xmlns:xsd=" <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> </cnpj> </CpfCnpj> <InscricaoMunicipal> </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

8 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 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 Texto descritivo sobre o problema ocorrido 8

9 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 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. 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. 9

10 ANEXO I Tabela de informações técnicas # Tipo Conteúdo Descrição IT0 1 URL Endereço do Web Service IT0 2 URL L Endereço para acessar o IT0 3 IT0 4 IT0 5 Endereço s IP contato suporte WSDL , , Endereços IP dos servidores da SIM>Consulta s para liberação em Firewall informativo@simconsultas.com.br suporte@simconsultas.com.br 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. Tabela de informações Gerais # 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 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

11 ENTREGUE AO RESPONSÁVEL. NFS-e INEXISTENTE. RE 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