Integração Software ISS externo - Funcionamento da API (Boletos, Pagamentos, Cadastro)
Objetivo:
Documentação das credenciais e informações para a API de integração do ISS, para conhecimento do time e fornecimento de informações a terceiros que desejam se integrar ao ISS.
Serão 3 os tipos de integração disponíveis entre o Sistema Tributário (STM) e os sistemas de ISS Eletrônico e Escrituração externos:
- Recepção de boletos e cancelamentos de boletos registrados pelo terceiro, para inclusão nas carteiras dos contribuintes e possibilitar baixa nos pagamentos.
- Envio de cadastros e alterações de cadastro realizadas no sistema Tributário STM para o terceiro, de forma a possibilitar a atualização dos cadastros com base ao cadastro tibutário.
- Envio de Pagamentos realizados no ssitema STM para informação de compensação dos boletos encaminhados previamente.
As permissões para acesso aos serviços é dada pela CEBI, com expressa autorização da Prefeitura (Chamado Técnico e/ou documentação apropriada).
Os serviços utilizam-se de Webhook para envio, em tempo real, das informações e do conceito de Fila para registrar todas as transações realizadas e informações trafegadas, de forma a facilitar a solução de problemas.
Conjuntamente ao serviço é disponibilizado um Painel de Integração para que os técnicos (Prefeitura e Atendimento à Prefeitura) possam fazer a consulta de dados trafegados e, conforme permissão, permitir o reprocessamento das informações.
Autenticação:
Esse tópico trata da autenticação no servidor de Login do ambiente Cebi, realizada através de chamadas HTTP.
Dessa forma, o Usuário de Integração Envia Credenciais, que passam pelo sistema Integrador (CEBI) - o qual valida as credenciais - e por sua vez retorna com o token (expirável) para que as informações de integração sejam validadas pela integração desejada (Boletos, Cadastro, Pagamento, Dívida Ativa).
Endpoints:
| URL | Método |
|---|---|
| http://agenciavirtual.cebicloud.com.br/login/connect/token | POST |
Headers:
Content-Type: application/x-www-form-urlencoded
| Campo | Conteúdo |
|---|---|
| grant_type | client_credentials |
| client_id | Será informado pela CEBI |
| client_secret | Será informado pela CEBI |
| scope | Cebi.Api |
Emissão de Boletos:
Uma vez com as credenciais obtidas/autenticadas, o boleto deverá ser enviado para recebimento/processamento:
Cancelamentos de boletos devem ser feitos em endpoint específico.
Endpoints:
| URL | Método |
|---|---|
| http://agenciavirtual.cebicloud.com.br/integracao_iss/boletos | POST |
Conteúdo:
O Conteúdo deverá ser enviado no BODY da requisição como um objeto JSON, como nos campos descritos abaixo:
BOLETO CONTRIBUINTE CCM
Boletos emitidos para contribuintes do municipio (com CCM) deverão ser enviados dentro desta especificação, para criação do débito no nosso sistema.
| Nome | Tipo | Descrição |
|---|---|---|
| ChaveGuia | Numérico | Número do Boleto |
| ChaveGuiaOriginal | Numérico (OPCIONAL) | Utilizado para 2a via |
| TipoBoleto | Numérico | 1 - Avulso, 2 - Encerramento, 3 - SegundaVia, 4 - Complementar, *Boletos do tipo “Cancelamento” deverão ser enviados ao endpoint de cancelamentos. |
| TipoTributacao | Numérico | 0 - Tomado 1 - Prestado |
| Ccm | Alfa-Numérico | |
| CpfCnpj | Alfa-Numérico | 000.000.000-00 (CPF) // 00.000.000/0000-00 (CNPJ) |
| ExercicioBase | Numérico | |
| Mes | Numérico | |
| DataEmissao | Data | |
| DataVencimento | Data | |
| ValorImposto | Decimal | |
| ValorMulta | Decimal | |
| ValorJuros | Decimal | |
| ValorCorrecao | Decimal | |
| NossoNumero | Numérico | |
| CadastroEventual | Objeto | Obrigatório em boletos emitidos para contribuintes de fora do municipio |
CADASTRO EVENTUAL
Boletos emitidos para contribuintes de fora do municipio deverão, dentro do objeto do Boleto, ter um objeto chamado “Cadastro Eventual”, para criação no nosso sistema.
| Nome | Tipo | Descrição |
|---|---|---|
| Ccm | Numérico (OPCIONAL) | |
| CpfCnpj | Alfa-Numérico | 000.000.000-00 (CPF) // 00.000.000/0000-00 (CNPJ) |
| RazaoSocial | Alfa-Numérico | |
| NomeFantasia | Alfa-Numérico | |
| TipoLogradouro | Alfa-Numérico | |
| Logradouro | Alfa-Numérico | |
| Numero | Alfa-Numérico | |
| Bairro | Alfa-Numérico | |
| Cep | Alfa-Numérico | |
| Complemento | Alfa-Numérico | |
| Cidade | Alfa-Numérico | |
| Estado | Alfa-Numérico | |
| Telefone | Alfa-Numérico | |
| CodigoServico | Numérico (OPCIONAL) | |
| DataInicialServico | Data (Opcional) | |
| DataFinalServico | Data (Opcional) | |
| Regime | Alfa-Numérico |
Cancelamento de Boletos:
Uma vez com as credenciais obtidas/autenticadas, o boleto deverá ser enviado para recebimento/processamento:
Endpoints:
| URL | Método |
|---|---|
| http://agenciavirtual.cebicloud.com.br/integracao_iss/boletos/cancelamento | POST |
Conteúdo:
O Conteúdo deverá ser enviado no BODY da requisição como um objeto JSON, como nos campos descritos abaixo:
| Nome | Tipo | Descrição |
|---|---|---|
| ChaveGuia | Numérico | |
| Ccm | Alfa-Numérico | |
| CpfCnp | Alfa-Numérico | 000.000.000-00 (CPF) // 00.000.000/0000-00 (CNPJ) |
| DataCancelamento | Alfa-Numérico |
Retorno (Geral):
Em caso de sucesso, os endpoints retornaram um status code 200 e uma mensagem de operação concluída com sucesso.
Em caso de erros, retornará um status code 400, um código de erro (que poderá ser consultado a baixo) e uma breve descrição sobre o ocorrido.
| Código | Descrição | Ocorrência |
|---|---|---|
| 01 | Não foi possível encontrar o contribuinte informado | As informações fornecidas no que diz respeito ao contribuinte, não consistem com as que temos previamente cadastradas. Ou seja, recebemos CCM: 1 e CNPJ: X Mas na nossa base de dados não encontramos alguém com essa combinação de CCM e Documento |
| 02 | Data de Vencimento não informada | |
| 03 | Boleto não encontrado para cancelamento | |
| 04 | Boleto duplicado | O Boleto informado já se encontra na nossa base de dados |
| 05 | Boleto não processado | |
| 06 | Tipo de Boleto informado inválido | Tipo de Boleto informado inválido |
| 07 | Boleto já está pago | Não é possível cancelar um boleto que ja recebemos o pagamento |
Nenhum comentário