API DE INTEGRAÇÃO / NFS-e (Web Service NFS-e) MANUAL DE COMUNICAÇÃO / INTEGRAÇÃO API DE INTEGRAÇÃO / NFS-e Versão 1.4
HISTÓRICO DE REVISÕES Revisão Data Descrição Autor 1.0 01/11/17 1.1 05/12/17 1.2 12/12/17 1.3 15/08/18 1.4 14/12/18 Elaboração da versão inicial do documento. Especificações dos itens 3.1, 3.2, 3.3, 3.4 e 3.5. Priscila Pereira Inclusão e especificação dos itens 3.6 e 3.7. Priscila Pereira Inclusão do item 4 (Tabela de mensagens personalizadas) de L1 à L7. Alteração do item 4 (Tabela de mensagens personalizadas) de L8 e L9. Inclusão do item 3.8 e alterações no item 2 indicando a URL para consumir o WSDL de Homologação e Produção. João Paulo Cordenunzi Alexandre R. dos Reis João Paulo Cordenunzi API DE INTEGRAÇÃO / NFS-e 2 Versão 1.4
Sumário 1 Introdução... 4 1.1 Propósito e escopo... 4 1.2 Público Alvo... 4 2 Pré-requisitos... 4 WSDL Homologação... 4 WSDL Produção... 4 3 Funcionalidades disponíveis... 5 3.1 Geração de NFS-e... 5 3.2 Cancelamento de NFS-e... 5 3.3 Substituição de NFS-e... 5 3.4 Consulta de NFS-e por RPS... 5 3.5 Consulta por faixa de NFS-e... 5 3.6 Recepcionar Lote Rps Síncrono... 6 3.7 Consultar Lote Rps... 6 3.8 Impressão/Visualização do documento de NFSe (link direto do documento)... 6 4 Tabela de mensagens personalizadas... 7 API DE INTEGRAÇÃO / NFS-e 3 Versão 1.4
1 Introdução 1.1 Propósito e escopo O objetivo deste manual é abordar a lógica de comunicação com a API/Web Service NFS-e da Città, a fim de esclarecer e descrever todo o processo de integração e o feedback das chamadas à API. A versão disponível do Web Service é compatível com a versão 2.0.3 conforme Manual de Integração da ABRASF. Através das funcionalidades disponibilizadas os contribuintes terão a possibilidade de gerar, cancelar e consultar Notas Fiscais de forma automatizada. Nesta primeira versão, apenas alguns métodos encontram-se disponíveis para serem consumidos, os mesmos serão descritos no item 3. 1.2 Público Alvo Este manual se destina a terceiros (third party) que desejam efetuar Emissão de NFS-e. 2 Pré-requisitos Os requisitos mínimos para a comunicação são: (QUANDO EM HOMOLOGAÇÃO) Possuir acesso ao link do WSDL de Homologação, citado abaixo; (QUANDO EM PRODUÇÃO) Possuir acesso ao link do WSDL de PRODUÇÃO, como citado no exemplo abaixo; WSDL Homologação http://citta.inf.br:888/nfse/services/nfsesoap?wsdl WSDL Produção https://[subdominio_cliente].cittaweb.com.br/nfse/services/nfsesoap?wsdl O link deve ser solicitado junto a Città, caso haja dúvidas. ATENDIMENTO E SUPORTE Vinicius Pagnussat ou Eduardo Debiasi suporte@cittainformatica.com.br (54) 3371-1700 ou (54) 3371-1720 (Atendimento das 08:00 às 17:00) API DE INTEGRAÇÃO / NFS-e 4 Versão 1.4
3 Funcionalidades disponíveis Os métodos disponíveis para consumo na versão v1.0 do Web Service são: 3.1 Geração de NFS-e Esta funcionalidade é responsável pela geração de NFS-e através dos dados recebidos referentes a uma prestação de serviço, a Geração de NFS-e é um serviço síncrono. Caso exista alguma inconsistência nos dados enviados, serão retornados os erros encontrados, para que sejam realizados os ajustes necessários e realizado um novo envio. Anexo 01 Arquivo XML exemplo para Geração de NFS-e. 3.2 Cancelamento de NFS-e Esta funcionalidade é responsável pelo cancelamento das NFS-e. O serviço de cancelamento de notas é um serviço síncrono, ou seja, o sistema do prestador envia uma solicitação de cancelamento, contendo uma nota e o WebService processa este cancelamento e retorna as informações. Caso exista alguma inconsistência nos dados enviados, serão retornados os erros encontrados, para que sejam realizados os ajustes necessários e realizado um novo envio. Anexo 02 Arquivo XML exemplo para Cancelamento de NFS-e. 3.3 Substituição de NFS-e Esta funcionalidade é responsável pela substituição das NFS-e, este é um serviço síncrono. O mesmo é responsável pela substituição da nota antiga e incremento dos dados da nota a ser substituída, vinculando a nota substituta à nota substituída. Caso exista alguma inconsistência nos dados enviados, serão retornados os erros encontrados, para que sejam realizados os ajustes necessários e realizado um novo envio. Anexo 03 Arquivo XML exemplo para Substituição de NFS-e. 3.4 Consulta de NFS-e por RPS Esta funcionalidade permite recuperar as informações de um RPS convertido. Este é um serviço síncrono, ou seja, o sistema do prestador envia uma solicitação de consulta, passando a informação de um RPS a ser consultado e na mesma conexão o web service retorna todos os dados desta NFS-e. Anexo 04 Arquivo XML exemplo para Consulta de NFS-e por RPS. 3.5 Consulta por faixa de NFS-e Esta funcionalidade permite recuperar as informações de um ou mais NFS-e, conforme os parâmetros de pesquisa. Este é um serviço síncrono, ou seja, o sistema do prestador envia uma solicitação de consulta, passando as informações de pesquisa e na mesma conexão o web service retorna todas as NFS-e encontradas. Anexo 05 Arquivo XML exemplo para Consulta por faixa de NFS-e. API DE INTEGRAÇÃO / NFS-e 5 Versão 1.4
3.6 Recepcionar Lote Rps Síncrono Esta funcionalidade é responsável pela recepção de um lote de RPS, este é um serviço síncrono. Quando o lote é recepcionado com sucesso, o lote é processado e todas as validações serão realizadas, caso exista alguma inconsistência nos dados enviados, serão retornados os erros encontrados, para que sejam realizados os ajustes necessários e realizado um novo envio. Anexo 06 Arquivo XML exemplo para Recepcionar Lote Rps Síncrono. 3.7 Consultar Lote Rps Esta funcionalidade, permite recuperar as informações de um ou mais NFS-e geradas a partir de um Lote de Rps enviado, os parâmetros enviados para pesquisa são o prestador e o número do protocolo gerado para o lote no envio. Anexo 07 Arquivo XML exemplo para Consultar Lote Rps. 3.8 Impressão/Visualização do documento de NFSe (link direto do documento) Esta funcionalidade, permite as empresas integradoras a utilização do documento de NFSe gerado pela Città, dispensando a confecção de um novo relatório. A funcionalidade esta disponível utilizando o campo <CodigoVerificacao> da tag <InfNfse> retornado no XML de resposta no momento da geração de uma NFSe. O documento esta disponível acessando o link abaixo: (QUANDO EM HOMOLOGAÇÃO) http://citta.inf.br:888/nfse/api/public/documento/report/codigoverificacao (QUANDO EM PRODUÇÃO) https://[subdominio_cliente].cittaweb.com.br/nfse/api/public/documento/report/codigoverificacao API DE INTEGRAÇÃO / NFS-e 6 Versão 1.4
4 Tabela de mensagens personalizadas L01 L02 L03 L04 Mensagem Tomador é obrigatório para geração de NFSE. Nota gerada com sucesso. Nota substituída com sucesso Consulta selecionou mais de 50 NFS-e, mais do que o permitido. Observação Máximo permitido de retorno para os services de consulta é de 50 NFSe. Usuário deve refinar a busca. L05 L06 L07 L08 L09 Tomador não encontra-se em nossa base de dados, favor informar os dados: CPF/CNPJ, Razão Social, E-mail, Código do município, Endereço, Número, Bairro e CEP. Intermediário não encontra-se em nossa base de dados, favor informar os dados: CPF/CNPJ, Razão Social e Código do município. Serviço não está vinculado a lista de serviços do Prestador. CNPJ informado encontra-se duplicado no banco de dados. Por favor verifique junto ao município Outras informações inválido. Utilize no máximo 255 caracteres para descrever outras informações Quando enviada a tag <Tomador> e o mesmo, pelo número de documento <CpfCnpj> não existir na base de dados, devem ser informados os demais campos para que o mesmo seja incluído. Estrutura deve serguir: <Tomador> <IdentificacaoTomador> <CpfCnpj> <Cpf>00000000000</Cpf> </CpfCnpj> </IdentificacaoTomador> <RazaoSocial>NOME</RazaoSocial> <Endereco> <Endereco>RUA TESTE</Endereco> <Numero>000</Numero> <Bairro>BAIRRO TESTE</Bairro> <CodigoMunicipio>0000000</CodigoMunicipio> <Uf>UF</Uf> <Cep>00000000</Cep> </Endereco> <Contato> <Telefone>0000000000</Telefone> <Email>email@email.com</Email> </Contato> </Tomador> Serviço utilizado não está disponível para este Prestador Foi disponibilizada a tag, não obrigatória, <OutrasInformacoes>, sendo ela um elemento da tag <InfDeclaracaoPrestacaoServico>. Se necessário utilizá-la, deve ser informado no máximo 255 caracteres API DE INTEGRAÇÃO / NFS-e 7 Versão 1.4