v1.0 Manual de integração municipal ISSIntel

Transcrição

1 v1.0 Manual de integração municipal ISSIntel

2 1.Utilização 1.1 Cadastros Para utilização do webservice para integração municipal não é necessário que a empresa autorizada possua cadastro como contribuinte, porém, ainda é necessária a autorização prévia do CNPJ (da empresa consumidora do serviço) para conexão. Desta forma, é necessário que antes do uso do webservice tanto para homologação como produção a empresa contate a equipe de suporte solicitando permissão de uso do webservice para integração municipal. No ato da solicitação é necessário informar a razão social da empresa e o CNPJ - é necessário que o CNPJ seja exatamente o mesmo do certificado utilizado no processo de autenticação. 1.2 Homologação e Produção Para garantir a utilização dos recursos disponibilizados da forma correta, evitando uso de forma desnecessária, é necessário que toda empresa passe pelo processo de homologação em um ambiente a parte. Esta processo não possui tempo mínimo nem máximo, ficando a critério do cliente consumidor do serviço a forma como proceder com o desenvolvimento e testes necessários. O ambiente de homologação possui as mesmas funcionalidades que o ambiente de produção, sendo atualizada sempre nas mesmas datas com as mesmas versões - salvo exceções em que certas funcionalidades são colocadas em teste no ambiente de homologação. Uma vez que todo os serviços desejados foram implementados e testados, o cliente consumidor pode solicitar a conclusão do processo de homologação e autorização para uso do ambiente de produção. Para fazê-lo, basta contatar o suporte fornecendo uma cópia dos arquivos XML enviado e recebidos do webservice para os serviços que serão utilizados em ambiente de produção. Os mesmos serão analisados e caso não apresentem nenhuma situação anormal ou distoante do esperado, a autorização será dada para uso do webservice em produção. Este processo é necessário apenas uma vez para uma versão do sistema consumidor, por exemplo, caso o mesmo sistema seja utilizado em 2 prefeituras, é necessário que o processo de homologação aconteça apenas uma vez. Uma vez que se possua permissão para uso em produção, e caso outras permissões sejam necessárias para demais prefeituras, basta contatar o suporte já informando a utilização em produção e qual o CNPJ previamente autorizado. v1.0 2

3 1.3 Endereços Os endereços para uso do webservice são construídos usando o mesmo padrão de forma a facilitar a organização e a separação contextual por cidades. Utilizando os pontos abaixos para constituir o endereço a ser utilizado: 1.a Todos os endereços de homologação são do domínio treino-issintel.com.br e todos os endereços de produção são do domínio issintel.com.br 1.b O nome e estado da cidade determina o contexto, por exemplo, para a cidade de Porto Seguro, o prefixo deve ser portoseguro-ba, para a cidade de Pato de Minas em Minas Gerais, o prefixo deve ser patodeminas-mg. 1.c Todas as cidades possuem dois endereços para utilização do webservice, um endereço para descrição e schema (também chamado de WSDL) e um endereço como endpoint, utilizado para enviar mensagem ao serviço. Para o WSDL, o caminho deve ser /webservices/issintel/wsdl e para o endereço endpoint, o caminho deve ser /webservices/issintel/api. Todos os endereços necessários são construídos utilizando os 3 pontos determinados acima, segue abaixo alguns exemplos para entedimento: - Para o WSDL da cidade de Porto Seguro no servidor de homologação: - Para o Endpoint para a cidade de Passos no servidor de produção: - Para o Endpoint para a cidade de Alegrete no servidor de homologação: 2.Autenticação 2.1 SSL Para assegurar integridade dos dados, todas as conexões, sejam de requisição ou de retorno devem estar dentro do protocolo SSL, sendo esta re-estabelecida em cada conexão. Atualmente a versão utilizada é a SSLv Certificado Por questões de segurança, é necessário que ambos os lados, tanto cliente como servidor passem pelo processo de autenticação, e a metodologia escolhida para este processo é a autenticação através de certificados X509. v1.0 3

4 Desta forma, no ato de criação da conexão, o cliente de enviar junto com o cabeçalho da requisição o seu certificado público, sua chave pública e a hierarquia de emissão dos certificados - de acordo com demais padrões, foi determinado que apenas certificados que possuem sua hierarquia baseada na ICP-Brasil sejam aceitos. Por conta de legislação, todas as autoridades emissoras brasileiras respondem diretamente a ICP-Brasil, sendo assim todos os certificados emitidos pelas mesmas atendem os requisitos determinados para este processo. Dentre demais atributos do certificado X509, os seguintes pontos são vitais para o processo de autenticação 2.a o atributo OID possua o CNPJ da organização autorizada para uso do webservice. 2.b que o certificado esteja dentro do intervalo de data de autorização para uso e expiração do certificado. 2.c esteja de acordo com os padrões determinados pela ICP-Brasil em sua versão 1.0 ou Portas de comunicação Por conta das diferenças no processo de autenticação das assinaturas determinadas pela ICP-Brasil versão 1.0 e versão 2.0, para os certificados que se incluem no padrão 1.0 deverão utlizar a porta padrão E os certificados já dentro do padrão 2.0, deverão utilizar a porta alternativa Desta forma, os endereços de conexão variam da seguinte forma: - Para porta Para porta Estrutura de Dados 3.1 Tipos Simples O webservice utiliza como tipos simples todos os elementos declarados como válido no padrão SOAP 1.1, desta forma, todos os elementos complexos ou informações a parte são declaradas a partir dos tipos abaixo: 3.1.a String 3.1.b Integer 3.1.c Float v1.0 4

5 3.1.d NegativeInteger 3.1.e Date 3.1.f Datetime 3.1.g Boolean 3.2 Tipos Complexos A partir de estruturas de dados simples ou de outros tipos complexos, objetos mais elaborados são utilizados para requisição e retorno de informações Underwritings Elemento utilizado para descrever uma lista de elementos Underwriting. underwriting Underwriting 1 - n Escrituração Underwriting Elemento utilizado para descrever uma escrituração. service_value Integer 1 Valor do serviço (em centavos) cpf_cnpj String 1 CPF ou CNPJ do contribuinte autor da escrituração taxed Boolean 1 Caso verdadeiro, significa que a escrituração teve seu valor tributado, caso falso, significa que a escrituraçnao teve seu valor retido. created_at Date 1 Data de criação da escrituração counterparty_cpf_cnpj String 1 CPF ou CNPJ da contraparte da escrituração deduction_value Integer 1 Valor total das deduções (em centavos) doc_type String 1 Tipo da escrituração service_date Date 1 Data de serviço da escrituração iss_value Integer 1 Valor do ISSQN (retido ou tributado - em centavos) v1.0 5

6 doc_series String 1 Série do documento doc_number String 1 Número do documento state String 1 Estado da escrituração Stubs Elemento utilizado para descrever uma lista de elementos Stub. stub Stub 1 - n Guia Stub Elemento utilizado para descrever uma guia. cpf_cnpj String 1 CPF ou CNPJ do contribuinte responsável pela guia fine_value Integer 1 Valor total da multa (em centavos) expires_at Date 1 Data de expiração da guia total_value Integer 1 Valor total da guia (em centavos) deduction_value Integer 1 Valor total de deduções (em centavos) id Integer 1 Identificar único da guia interest_value Integer 1 Valor total dos juros (em centavos) iss_value Integer 1 Valor total do ISSQN (em centavos) bank_code String 1 Código do banco paid_at Date 1 Data de pagamento da guia underwritings Underwritings 1 Listagem de escriturações vinculadas a guia v1.0 6

7 3.2.5 Taxpayer Elemento utilizado para descrever um contribuinte. cpf_cnpj String 1 CPF ou CNPJ official_name String 1 Razão Social city_registration String 1 Inscrição municipal address String 1 Logradouro de registro address_number String 1 Número do endereço address_district String 1 Bairro ou região do endereço address_zipcode Integer 1 CEP city String 1 Código IBGE da cidade phone String 1 Número de telefone String 1 Endereço de Timeframe Elemento utilizado para descrever intervalo de data. begin_at Date 1 Data de ínicio do período finish_at Date 1 Data de término do período Ulist Elemento utilizado para descrever uma lista de IDs de escriturações. uid integer 1 - n Identificador único da escrituração Pagination Elemento utilizado para informar e descrição páginação de resultados e informações disponíveis. v1.0 7

8 displaying_from Integer 1 Posição do primeiro objeto listado displaying_to Integer 1 Posição do último objeto listado total Integer 1 Quantidade total de objetos page Integer 1 Número da página exibida 4.Serviços 4.1 Guias Serviço utilizado para solicitar uma listagem de guias a partir de alguns filtros informados Requisição timeframe Timeframe Raiz filter String Raiz page Integer Raiz state String Raiz Retorno stubs Stubs Raiz pagination Pagination Raiz 4.2 Escriturações Serviço utilizado para solicitar uma listagem de escriturações a partir de alguns filtros informados Requisição timeframe Timeframe Raiz v1.0 8

9 filter String Raiz page Integer Raiz state String Raiz Retorno underwritings Underwritings Raiz pagination Pagination Raiz 4.3 Contribuintes Serviço utilizado para solicitar uma listagem informações de um contribuinte através do CPF ou CNPJ do mesmo. Requisição cpf_cnpj String Raiz Retorno taxpayer Taxpayer Raiz 5.Erros e mensagens de retornos Erros no processo de autenticação e conexão Código Descrição S01 S02 S03 S04 XML de requisição não é válido Emissor de certificado não autorizado Certificado expirado Certificado não autorizado como transmissor v1.0 9

10 S06 S12 Código Descrição Não foi possível interpretar certificado de transmissão. Cnpj do emissor não informado Erros de validação na requisição Código Descrição S26 S27 S28 S29 S66 Intervalo de data inválido CPF ou CNPJ inválido para consulta Status não é válido para o objeto em questão Filtro não é válido para o objeto em questão Erro interno no processamento v1.0 10