{{:postgres:boto-nlp:tatodesk_marca_05.png?nolink&250 |}} \\ \\
\\ \\
====== API de Integração com os Serviços do Chatbot ======
Nosso objetivo é definir as características esperadas na **A.P.I** de cada serviço, possibilitando a integração com o Chatbot. A **A.P.I** deve utilizar o protocolo **REST** e respeitar o **TTL** (**Time To Live**) máximo de 5 segundos (exceto para **A.P.I** de verificação de débitos, onde a tolerância é de 15 segundos).
\\
====== Serviços ======
Escolha abaixo o serviço que deseja ver a **A.P.I** de integração:
- **[[=postgres:boto-nlp:api#validacao_integracao_-_status|Validação / Integração - Status]]**
- **[[=postgres:boto-nlp:api#login_autenticacao|Login/Autenticação]]**
- **[[=postgres:boto-nlp:api#segunda_via_de_contas|Segunda Via de Contas]]**
- **[[=postgres:boto-nlp:api#abrir_rafalta_d_agua_vazamento_e_religacao|Abrir RA: Falta D’Água, Vazamento e Religação]]**
\\
\\
===== Validação/Integração - Status =====
**A.P.I** responsável por informar se o sistema comercial está online e apto a receber requisições.
\\
==== GET /gsan/verificarBot ====
**A.P.I** para obter o status do serviço do sistema comercial.
\\
**Resposta esperada**:
- **body**: valor booleano
\\
Exemplo:
{{ :postgres:boto-nlp:11111.jpg?nolink |}}
Figura 1 exemplo de request para a rota /gsan/verificarBot
\\
===== Login/Autenticação =====
**A.P.I** responsável pela verificação e autenticação de clientes no sistema comercial. Veja abaixo as rotas necessárias para a realização deste serviço:
\\
==== GET /gsan/localidadeImovel ====
**A.P.I** para obter as informações de localidade, setor comercial e quadra de um imóvel. Parâmetros:
**Matricula**:
- Valor inteiro com a identificação do imóvel no sistema comercial.
\\
**Resposta esperada**:
- **body**: Objeto **JSON** com as seguintes informações:
- **localidade**: Identificador da localidade do imóvel.
- **setor**: Identificador do setor comercial do imóvel.
- **quadra**: Identificador da quadra do imóvel.
\\
Exemplo:
{{ :postgres:boto-nlp:figura_1.jpg?nolink |}}
Figura 2 Exemplo de request para a rota /gsan/localidadeImovel
\\
==== GET /gsan/buscarImoveis ====
**A.P.I** para obter imóveis associados a um CPF/CNPJ. Parâmetros:
**cpfCnpj**: valor inteiro com a identificação do imóvel no sistema comercial.
\\
**Resposta esperada**:
- **body**: Lista de objetos **JSON** com as seguintes informações:
- **matriculaImovel**: Identificador do imóvel no sistema comercial.
- **nomeCliente**: Nome do cliente.
- **enderecoImovel**: Endereço do imóvel.
- **idCliente**: Identificador do cliente.
- **diaVencimentoImovel**: Dia do vencimento das contas do imóvel.
\\
Exemplo:
{{ :postgres:boto-nlp:figura_2.jpg?nolink |}}
Figura 3 Exemplo de request para a rota /gsan/buscarImoveis
\\
==== GET /gsan/verificarMatriculaCpfCnpj ====
**A.P.I** para checar se um **CPF/CNPJ** está associado à matrícula informada. Parâmetros:
- **matricula**: valor inteiro com a identificação do imóvel no sistema comercial.
- **cpfCnpj**: string com o número do **CPF/CNPJ** sem formatação.
\\
**Resposta esperada**:
- **body**: Objeto **JSON** com os campos abaixo:
- **cpfCnpjValido**: Valor booleano, que indica se o CPF/CNPJ informado é válido ou não.
- **matriculaValida**: Valor booleano, o qual indica se a matrícula informada corresponde a um valor válido no sistema comercial.
- **matriculaExistente**: Valor booleano, com o indicativo se existe imóvel com a matrícula informada.
- **cpfCnpjVinculados**: Indica se o CPF/CNPJ e matrícula informados estão associados.
\\
Exemplo:
{{ :postgres:boto-nlp:figura_3.jpg?nolink |}}
Figura 4: Exemplo de request para a rota /gsan/verificarMatriculaCpfCnpj
\\
==== GET /gsan/chatbot/autenticarMatricula ====
**A.P.I** para checar se uma matrícula possui um valor válido no sistema comercial. Parâmetros:
**matricula**: valor inteiro com a identificação do imóvel no sistema comercial.
\\
**Resposta esperada 1**:
- **body**: Matrícula do imóvel:
\\
Exemplo:
{{ :postgres:boto-nlp:figura_4.1.jpg?nolink |}}
Figura 5.1: Exemplo de request para a rota /gsan/chatbot/autenticarMatricula
\\
**Resposta esperada 2**:
- **error**: objeto **JSON** com os campos definidos abaixo:
- **detailMessage**: mensagem do erro.
\\
Exemplo:
{{ :postgres:boto-nlp:figura_4.2.jpg?nolink |}}
Figura 5.2: Exemplo de request para a rota /gsan/chatbot/autenticarMatricula
**Observação**: No exemplo **5.2** o código de status da resposta é **422**.
\\
===== Segunda Via de Contas =====
**A.P.I's** responsáveis pela listagem das contas pendentes do cliente, bem como pela obtenção e emissão da conta. Para tanto, faz-se uso de quatro rotas **REST**. São elas:
\\
==== GET /gsan/segundaViaConta ====
**A.P.I** para listar as contas de uma matrícula. Parâmetros:
- **matricula**: valor inteiro com a identificação do imóvel no sistema comercial.
- **pagination**: valor inteiro referente à página do resultado da lista de contas. Opcional. Caso não seja informado, ou informado o valor **0**, são listados todos os débitos, sem paginação do resultado.
\\
**Resposta esperada**:
- **body**: Objeto **JSON** contendo uma lista de objetos **JSON** com os seguintes campos:
- **data**: Mês/ano de referência da conta.
- **valor**: Valor total da conta.
- **idConta**: Identificador da conta.
\\
Exemplo:
{{ :postgres:boto-nlp:figura_5.jpg?nolink |}}
Figura 6: Exemplo de request para a rota /gsan/segundaViaConta
\\
==== GET /gsan/segundaViaContaTotal ====
**A.P.I** para obter a quantidade e o valor total das contas de uma matrícula. Parâmetros:
**matricula**: valor inteiro com a identificação do imóvel no sistema comercial.
\\
**Resposta esperada**:
- **body**: Objeto **JSON** contendo os campos abaixo:
- **qntdContas**: Quantidade total de contas do imóvel.
- **valor**: Valor total das contas do imóvel.
\\
Exemplo:
{{ :postgres:boto-nlp:figura_6.jpg?nolink |}}
Figura 7: Exemplo de request para a rota /gsan/segundaViaContaTotal
\\
==== GET /gsan/segundaViaCodigoBarra ====
**A.P.I** para obter os códigos de barra das contas informadas. Parâmetros:
- **matricula**: valor inteiro com a identificação do imóvel no sistema comercial.
- **idConta**: lista de strings com a identificação das contas.
\\
**Resposta esperada**:
- **body**: Objeto **JSON** contendo os campos abaixo:
- **mesAno**: Lista com mês/ano de referência das contas, na ordem em que foram informadas.
- **valor**: Lista com os valores das contas, na ordem em que foram informadas.
- **codigoBarra**: Lista com os códigos de barra sem formatação, seguindo a ordem em que as contas foram informadas.
\\
Exemplo:
{{ :postgres:boto-nlp:figura_7.jpg?nolink |}}
Figura 8: Exemplo de request para a rota /gsan/segundaViaCodigoBarra
\\
==== GET /gsan/segundaViaContaRelatorio ====
**A.P.I** obter (ou enviar por e-mail) o PDF com as contas informadas. Parâmetros:
- **matricula**: valor inteiro com a identificação do imóvel no sistema comercial.
- **idConta**: lista de strings com a identificação das contas.
- **simplificada**: parâmetro opcional. Quando informado, emite a conta com o layout simplificado. Caso não seja informado, é emitido no layout padrão de conta.
- **email**: string opcional com o e-mail para o qual as contas serão enviadas. Caso não seja informado, é retornado o **BLOB** do arquivo PDF; caso contrário, os arquivos são enviados para o e-mail informado.
\\
**Resposta esperada 1**: com e-mail informado
- **body**: //string// informando que o e-mail foi enviado.
\\
Exemplo:
{{ :postgres:boto-nlp:figura_8.1.jpg?nolink |}}
Figura 9.1: Exemplo de request para a rota /gsan/segundaViaContaRelatorio com e-mail
\\
**Resposta esperada 2**: sem e-mail informado:
- **body**: **BLOB** do arquivo PDF com **content-type: aplication/pdf**.
\\
Exemplo:
{{ :postgres:boto-nlp:figura_8.2.jpg?nolink |}}
Figura 9.2: Exemplo de request para a rota /gsan/segundaViaContaRelatorio sem e-mail
\\
===== Abrir RA: Falta D’Água, Vazamento e Religação =====
**A.P.I’s** responsáveis pela verificação e cadastramento de Registros de Atendimento por Falta de Água, Vazamento e Religação da ligação de água. Segue abaixo as rotas **REST** para realização do fluxo:
\\
==== POST /gsan/verificarRAWS ====
**A.P.I** para checar a existência de registros de atendimento abertos para o imóvel.
**Campos do body**:
- **matricula**: valor inteiro com a identificação do imóvel no sistema comercial.
- **especificacao**: valor inteiro com a identificação da especificação do atendimento.
\\
**Resposta esperada 1** (caso exista registro de atendimento pendente para a matrícula informada):
- **body**: Objeto **JSON** com os campos abaixo citados:
- **protocolo**: Protocolo do registro de atendimento.
- **dataPrevistaAtendimentoRA**: A data em que o registro de atendimento está previsto para ser atendido.
- **status**: Texto informativo que a solicitação já se encontra cadastrada.
Exemplo:
\\
{{ :postgres:boto-nlp:figura_9.jpg?nolink |}}
Figura 10.1: Exemplo de request para a rota /gsan/verficarRAWS com RA pendente
\\
**Resposta esperada 2** (caso não exista registro de atendimento pendente para a matrícula informada):
- **error**: objeto **JSON** com os campos abaixo citados:
- **detailtMessage**: mensagem do erro.
\\
{{ :postgres:boto-nlp:9.2.jpg?nolink |}}
Figura 10.2: Exemplo de request para a rota /gsan/verficarRAWS sem RA pendente
\\
**Observação**: No exemplo **10.2** o código de status da resposta é **422**.
\\
==== GET /gsan/episodiosFaltaAgua ====
**A.P.I** para checar a existência de ocorrências de desabastecimento na região do imóvel. Parâmetros:
**matricula**: valor inteiro com a identificação do imóvel no sistema comercial.
\\
**Resposta esperada**
- **body**: lista de objetos **JSON** com os campos especificados abaixo:
- **idOcorrencia**: identificador da ocorrência operacional.
- **ocorrencia**: descrição da ocorrência operacional.
- **ocorrenciaAbreviada**: descrição da ocorrência com no máximo 30 caracteres.
- **dataHora**: data e hora da ocorrência, no formato DD/MM/YYYY HH:mi:ss.
- **previsão**: data e período da previsão de retomada do abastecimento.
- **areaAfetada**: descrição das áreas afetadas pela ocorrência.
- **areaAfetadaAbreviada**: descrição das áreas afetadas pela ocorrência, com no máximo 30 caracteres.
\\
Exemplo:
\\
{{ :postgres:boto-nlp:kaufman2.jpg?nolink |}}
Figura 11: Exemplo de request para a rota /gsan/episodiosFaltaAgua
\\
==== GET /gsan/tipoEspecificacaoRA ====
**A.P.I** para listar as especificações de um tipo de solicitação de atendimento. Parâmetros:
**tipoSolicitacao**: valor inteiro com a identificação do tipo de solicitação.
\\
**Resposta esperada**:
- **body**: lista de objetos **JSON** contendo os campos abaixo:
- **id**: identificador da especificação do atendimento.
- **descricao**: descrição da especificação.
\\
Exemplo:
\\
{{ :postgres:boto-nlp:kaufman3.jpg?nolink |}}
Figura 12: Exemplo de request para a rota /gsan/tipoEspecificacaoRA
\\
==== POST /gsan/verificarExistenciaRAReligacao ====
**A.P.I** para checar se existe registro de atendimento de religação para o imóvel. Campos do body:
**matricula**: valor inteiro com a identificação do imóvel no sistema comercial.
\\
**Resposta esperada 1**:
- **body**: objeto **JSON** com os campos abaixo citados:
- **protocolo**: protocolo do registro de atendimento.
- **dataPrevistaAtendimentoRA**: a data em que o registro de atendimento está previsto para ser atendido.
- **status**: texto informativo que a solicitação já se encontra cadastrada.
\\
Exemplo:
\\
{{ :postgres:boto-nlp:kaufman5.jpg?nolink |}}
Figura 13.1 – Exemplo de request para a rota /gsan/verificarExistenciaRAReligacao
\\
**Resposta esperada 2**:
- **error**: objeto **JSON** com os campos descritos abaixo:
- **mensagem**: mensagem indicando que não existe solicitação cadastrada para a matrícula.
\\
{{ :postgres:boto-nlp:kaufman13.jpg?nolink |}}
Figura 13.2 – Exemplo 2 de request para a rota /gsan/verificarExistenciaRAReligacao
\\
**Observação**: No exemplo **13.2** o código de status da resposta é **422**.
\\
==== GET /gsan/verificarDebitosImovel ====
**A.P.I** para checar se o imóvel ainda possui débito em atraso. Parâmetros:
**matrícula**: valor inteiro com a identificação do imóvel no sistema comercial.
\\
**Resposta esperada**:
- **message**: mensagens de validação dos fluxos conforme descritos nas árvores conversacionais (ver: **https://www.gsan.com.br/doku.php?id=postgres:boto-nlp:abrir-ra:religacao)**.
- **body**: objeto **JSON** com os campos abaixo:
- **matricula**: valor inteiro com a identificação do imóvel no sistema comercial.
- **endereco** endereço do imóvel.
- **cortado**: valor booleano indicador se o imóvel encontra-se cortado ou não.
- **débitos**: objeto **JSON** referente aos débitos originários do corte, caso possua, com os seguintes campos:
- **contas**: lista de objetos **JSON** com os valores:
- **id**: identificador da conta.
- **referência**: mês/ano de referência da conta.
- **valor**: valor total da conta.
- **guias**: lista de objetos **JSON** com os valores:
- **id**: identificador da guia de pagamento.
- **referência**: mês/ano de referência da guia de pagamento.
- **valor**: valor total da guia de pagamento.
- **débitos**: lista de objetos **JSON** com os valores:
- **id**: identificador do débito a cobrar.
- **referência**: mês/ano de referência do débito a cobrar.
- **valor**: valor total do débito a cobrar.
\\
Exemplo:
\\
{{ :postgres:boto-nlp:13.1.jpg?nolink |}}
Figura 14.1 – Exemplo de request para a rota /gsan/verificarDebitosImovel
\\
Exemplo 2:
\\
{{ :postgres:boto-nlp:13.2.jpg?nolink |}}
Figura 14.2 – Exemplo 2 de request para a rota /gsan/verificarDebitosImovel
==== GET /gsan/verificarEmailCadastrado ====
**A.P.I** para checar se o e-mail informado está vinculado ao cliente do imóvel. Parâmetros:
- **matrícula**: valor inteiro com a identificação do imóvel no sistema comercial.
- **email**: string com o e-mail para validação.
\\
**Resposta esperada**:
- **body**: valor booleano indicando se o e-mail informado está associado ao cliente do imóvel ou não.
\\
Exemplo:
\\
{{ :postgres:boto-nlp:14.jpg?nolink |}}
Figura 15 – Exemplo 2 de request para a rota /gsan/verificarEmailCadastrado
\\
==== POST /gsan/inserirRAWS ====
**A.P.I** para inserir o Registro de Atendimento.
**Campos do body**:
- **matrícula**: valor inteiro com a identificação do imóvel no sistema comercial.
- **solicitacaoTipo**: valor inteiro, referente ao identificador do tipo de solicitação do atendimento.
- **especificacao**: valor inteiro, referente ao identificador da especificação do atendimento.
- **pontoReferencia**: descrição do ponto de referência.
- **telefoneContato**: telefone de contato com o DDD, no formato (XX) DDDDD-DDDD.
- **observacoes**: descrição da observação a ser associada ao Registro de Atendimento.
- **nomeSolicitante**: nome do solicitante.
- **email**: email do solicitante.
\\
**Resposta esperada**
- **body**: objeto JSON com os campos abaixo:
- **protocolo**: número do protocolo de atendimento registrado.
- **dataPrevistaAtendimentoRA**: data prevista de realização do atendimento.
- **status**: texto informativo que a solicitação foi cadastrada.
\\
Exemplo:
\\
{{ :postgres:boto-nlp:15.jpg?nolink |}}
Figura 16 – Exemplo de request para a rota /gsan/inserirRAWS
\\
==== POST /gsan/inserirRAReligacao ====
**A.P.I** para inserir o Registro de Atendimento de religação da ligação de água.
**Campos do body**:
- **matricula**: valor inteiro com a identificação do imóvel no sistema comercial.
- **pontoReferencia**: descrição do ponto de referência.
- **telefoneContato**: telefone de contato com o DDD, no formato (XX) DDDDD-DDDD.
- **email**: email do solicitante.
- **tipoRegistroAtendimento**: valor constante 1.
\\
**Resposta esperada**
- **body**: objeto JSON com os campos abaixo:
- **protocolo**: número do protocolo de atendimento registrado.
- **dataPrevistaAtendimentoRA**: data prevista de realização do atendimento.
- **status**: texto informativo que a solicitação foi cadastrada.
\\
Exemplo:
\\
{{ :postgres:boto-nlp:16.jpg?nolink |}}
Figura 17 – Exemplo de request para a rota /gsan/inserirRAReligacao
\\
Clique **[[=postgres:tatodesk|AQUI]]** para retornar.
~~NOSIDEBAR~~
\\
~~ODT~~