Base de Conhecimento de Gestão Comercial de Saneamento

Você carregou uma revisão antiga desse documento! Se você salvá-la, irá criar uma nova versão com esses dados.

&lt;WRAP center round todo 60%>
Em obra
&lt;/WRAP>

<h1>API de Integração com os Serviços do Chatbot</h1>
<div class="level1">

&lt;columns>
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).
&lt;/columns>

</div>

<h1>Serviços</h1>
<div class="level1">

&lt;columns>
Escolha abaixo o serviço que deseja ver a A.P.I de integração:

<ol>
<li class="level1"> <a href="/doku.php?id=postgres:boto-nlp:api#login_autenticacao" class="wikilink1" title="postgres:boto-nlp:api" data-wiki-id="postgres:boto-nlp:api">Login/Autenticação</a></li>
<li class="level1"> <a href="/doku.php?id=postgres:boto-nlp:api#segunda_via_de_contas" class="wikilink1" title="postgres:boto-nlp:api" data-wiki-id="postgres:boto-nlp:api">Segunda Via de Contas</a></li>
<li class="level1"> <a href="/doku.php?id=postgres:boto-nlp:api#abrir_rafalta_d_agua_vazamento_e_religacao" class="wikilink1" title="postgres:boto-nlp:api" data-wiki-id="postgres:boto-nlp:api">Abrir RA: Falta D’Água, Vazamento e Religação</a></li>
</ol>

&lt;/columns>

</div>

<h2>Login/Autenticação</h2>
<div class="level2">

&lt;columns>
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:
&lt;/columns>

</div>

<h3>GET /gsan/localidadeImovel</h3>
<div class="level3">

&lt;columns>
A.P.I para obter as informações de localidade, setor comercial e quadra de um imóvel. Parâmetros:

Matricula:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

Resposta esperada:

<ol>
<li class="level1 node"> body: Objeto JSON com as seguintes informações:<ol>
<li class="level3"> localidade: Identificador da localidade do imóvel.</li>
<li class="level3"> setor: Identificador do setor comercial do imóvel.</li>
<li class="level3"> quadra: Identificador da quadra do imóvel.</li>
</ol>
</li>
</ol>

Exemplo:
&lt;/columns>

&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:figura_1.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 1 Exemplo de request para a rota /gsan/localidadeImovel&lt;/center>&lt;/html>
&lt;/WRAP>

</div>

<h3>GET /gsan/buscarImoveis</h3>
<div class="level3">

&lt;columns>
A.P.I para obter imóveis associados a um CPF/CNPJ. Parâmetros:

cpfCnpj:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

Resposta esperada:

<ol>
<li class="level1 node"> body: Lista de objetos JSON com as seguintes informações:<ol>
<li class="level3"> matriculaImovel: Identificador do imóvel no sistema comercial.</li>
<li class="level3"> nomeCliente: Nome do cliente.</li>
<li class="level3"> enderecoImovel: Endereço do imóvel.</li>
<li class="level3"> idCliente: Identificador do cliente.</li>
<li class="level3"> diaVencimentoImovel: Dia do vencimento das contas do imóvel.</li>
</ol>
</li>
</ol>

Exemplo:
&lt;/columns>
&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:figura_2.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 2 Exemplo de request para a rota /gsan/buscarImoveis&lt;/center>&lt;/html>
&lt;/WRAP>

</div>

<h3>GET /gsan/verificarMatriculaCpfCnpj</h3>
<div class="level3">

&lt;columns>
A.P.I para checar se um CPF/CNPJ está associado à matrícula informada. Parâmetros:

matricula:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

cpfCnpj:

<ol>
<li class="level1"> string com o número do CPF/CNPJ sem formatação.</li>
</ol>

Resposta esperada:

<ol>
<li class="level1 node"> body: Objeto JSON com os campos abaixo:<ol>
<li class="level2"> cpfCnpjValido: Valor booleano, que indica se o CPF/CNPJ informado é válido ou não.</li>
<li class="level2"> matriculaValida: Valor booleano, o qual indica se a matrícula informada corresponde a um valor válido no sistema comercial.</li>
<li class="level2"> matriculaExistente: Valor booleano, com o indicativo se existe imóvel com a matrícula informada.</li>
<li class="level2"> cpfCnpjVinculados: Indica se o CPF/CNPJ e matrícula informados estão associados.</li>
</ol>
</li>
</ol>

Exemplo:
&lt;/columns>
&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:figura_3.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 3: Exemplo de request para a rota /gsan/verificarMatriculaCpfCnpj&lt;/center>&lt;/html>
&lt;/WRAP>

</div>

<h3>GET /gsan/chatbot/autenticarMatricula</h3>
<div class="level3">

&lt;columns>
A.P.I para checar se uma matrícula possui um valor válido no sistema comercial. Parâmetros:

matricula:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

Resposta esperada 1:

<ol>
<li class="level1"> body: Matrícula do imóvel:</li>
</ol>

Exemplo:
&lt;/columns>
&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:figura_4.1.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 4.1: Exemplo de request para a rota /gsan/chatbot/autenticarMatricula&lt;/center>&lt;/html>
&lt;/WRAP>

&lt;columns>

Resposta esperada 2:

<ol>
<li class="level1 node"> error: objeto JSON com os campos definidos abaixo:<ol>
<li class="level2"> detailMessage: mensagem do erro.</li>
</ol>
</li>
</ol>

Exemplo:
&lt;/columns>
&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:figura_4.2.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 4.2: Exemplo de request para a rota /gsan/chatbot/autenticarMatricula&lt;/center>&lt;/html>
&lt;/WRAP>

Observação: No exemplo 4.2 o código de status da resposta é 422.

</div>

<h2>Segunda Via de Contas</h2>
<div class="level2">

&lt;columns>
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:
&lt;/columns>

</div>

<h3>GET /gsan/segundaViaConta</h3>
<div class="level3">

&lt;columns>
A.P.I para listar as contas de uma matrícula. Parâmetros:

matricula:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

pagination:

<ol>
<li class="level1"> 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.</li>
</ol>

Resposta esperada:

<ol>
<li class="level1 node"> body: Objeto JSON contendo uma lista de objetos JSON com os seguintes campos:<ol>
<li class="level2"> data: Mês/ano de referência da conta.</li>
<li class="level2"> valor: Valor total da conta.</li>
<li class="level2"> idConta: Identificador da conta.</li>
</ol>
</li>
</ol>

Exemplo:
&lt;/columns>
&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:figura_5.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 5: Exemplo de request para a rota /gsan/segundaViaConta&lt;/center>&lt;/html>
&lt;/WRAP>

</div>

<h3>GET /gsan/segundaViaContaTotal</h3>
<div class="level3">

&lt;columns>
A.P.I para obter a quantidade e o valor total das contas de uma matrícula. Parâmetros:

matricula:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

Resposta esperada:

<ol>
<li class="level1 node"> body: Objeto JSON contendo os campos abaixo:<ol>
<li class="level2"> qntdContas: Quantidade total de contas do imóvel.</li>
<li class="level2"> valor: Valor total das contas do imóvel.</li>
</ol>
</li>
</ol>

Exemplo:
&lt;/columns>
&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:figura_6.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 6: Exemplo de request para a rota /gsan/segundaViaContaTotal&lt;/center>&lt;/html>
&lt;/WRAP>

</div>

<h3>GET /gsan/segundaViaCodigoBarra</h3>
<div class="level3">

&lt;columns>
A.P.I para obter os códigos de barras das contas informadas. Parâmetros:

matricula:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

idConta:

<ol>
<li class="level1"> Lista de strings com a identificação das contas.</li>
</ol>

Resposta esperada:

<ol>
<li class="level1 node"> body: Objeto JSON contendo os campos abaixo:<ol>
<li class="level2"> mesAno: Lista com mês/ano de referência das contas, na ordem em que foram informadas.</li>
<li class="level2"> valor: Lista com os valores das contas, na ordem em que foram informadas.</li>
<li class="level2"> codigoBarra: Lista com os códigos de barra sem formatação, seguindo a ordem em que as contas foram informadas.</li>
</ol>
</li>
</ol>

Exemplo:
&lt;/columns>
&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:figura_7.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 7: Exemplo de request para a rota /gsan/segundaViaCodigoBarra&lt;/center>&lt;/html>
&lt;/WRAP>

</div>

<h3>GET /gsan/segundaViaContaRelatorio</h3>
<div class="level3">

&lt;columns>
A.P.I obter (ou enviar por e-mail) o PDF com as contas informadas. Parâmetros:

matricula:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

idConta:

<ol>
<li class="level1"> Lista de strings com a identificação das contas.</li>
</ol>

simplificada:

<ol>
<li class="level1"> Parâmetro opcional. Quando informado, emite a conta com o layout simplificado. Caso não seja informado, é emitido no layout padrão de conta.</li>
</ol>

email:

<ol>
<li class="level1"> 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.</li>
</ol>

Resposta esperada 1: com e-mail informado

<ol>
<li class="level1"> body: string informando que o e-mail foi enviado.</li>
</ol>

Exemplo:
&lt;/columns>
&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:figura_8.1.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 8.1: Exemplo de request para a rota /gsan/segundaViaContaRelatorio com e-mail&lt;/center>&lt;/html>
&lt;/WRAP>

&lt;columns>
Resposta esperada 2: sem e-mail informado:

<ol>
<li class="level1"> body: BLOB do arquivo PDF com content-type: aplication/pdf.</li>
</ol>

Exemplo:
&lt;/columns>
&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:figura_8.2.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 8.2: Exemplo de request para a rota /gsan/segundaViaContaRelatorio sem e-mail&lt;/center>&lt;/html>
&lt;/WRAP>

</div>

<h2>Abrir RA: Falta D’Água, Vazamento e Religação</h2>
<div class="level2">

&lt;columns>
A.P.I’s responsáveis pela verificação e cadastramento de registros de atendimento (RA) por Falta de Água, Vazamento e Religação da ligação de água. Veja abaixo as rotas necessárias para a realização deste serviço:
&lt;/columns>

</div>

<h3>POST /gsan/verificarRAWS</h3>
<div class="level3">

&lt;columns>
A.P.I para checar a existência de registros de atendimento abertos para o imóvel.

Campos do body:

matricula:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

especificacao:

<ol>
<li class="level1"> Valor inteiro com a identificação da especificação do atendimento.</li>
</ol>

Resposta esperada 1 (caso exista registro de atendimento pendente para a matrícula informada):

<ol>
<li class="level1 node"> body: Objeto JSON com os campos abaixo citados:<ol>
<li class="level2"> protocolo: Protocolo do registro de atendimento.</li>
<li class="level2"> dataPrevistaAtendimentoRA: A data em que o registro de atendimento está previsto para ser atendido.</li>
<li class="level2"> status: Texto informativo que a solicitação já se encontra cadastrada.</li>
</ol>
</li>
</ol>

Exemplo:
&lt;/columns>

&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:figura_9.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 9.1: Exemplo de request para a rota /gsan/verficarRAWS com RA pendente&lt;/center>&lt;/html>
&lt;/WRAP>
&lt;columns>
Resposta esperada 2 (caso não exista registro de atendimento pendente para a matrícula informada):

<ol>
<li class="level1 node"> error: objeto JSON com os campos abaixo citados:<ol>
<li class="level2"> detailtMessage: mensagem do erro.</li>
</ol>
</li>
</ol>

&lt;/columns>

&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:9.2.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 9.2: Exemplo de request para a rota /gsan/verficarRAWS sem RA pendente&lt;/center>&lt;/html>
&lt;/WRAP>
&lt;columns>
Observação: No exemplo 9.2 o código de status da resposta é 422.
&lt;/columns>

</div>

<h3>GET /gsan/episodiosFaltaAgua</h3>
<div class="level3">

&lt;columns>
A.P.I para checar a existência de ocorrências de desabastecimento na região do imóvel. Parâmetros:

matricula:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

Resposta esperada

<ol>
<li class="level1 node"> body: lista de objetos JSON com os campos especificados abaixo:<ol>
<li class="level2"> idOcorrencia: identificador da ocorrência operacional.</li>
<li class="level2"> ocorrencia: descrição da ocorrência operacional.</li>
<li class="level2"> ocorrenciaAbreviada: descrição da ocorrência com no máximo 30 caracteres.</li>
<li class="level2"> dataHora: data e hora da ocorrência, no formato DD/MM/YYYY HH:mi:ss.</li>
<li class="level2"> previsão: data e período da previsão de retomada do abastecimento.</li>
<li class="level2"> areaAfetada: descrição das áreas afetadas pela ocorrência.</li>
<li class="level2"> areaAfetadaAbreviada: descrição das áreas afetadas pela ocorrência, com no máximo 30 caracteres.</li>
</ol>
</li>
</ol>

Exemplo:
&lt;/columns>

&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:kaufman2.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 10: Exemplo de request para a rota /gsan/episodiosFaltaAgua&lt;/center>&lt;/html>
&lt;/WRAP>

</div>

<h3>GET /gsan/tipoEspecificacaoRA</h3>
<div class="level3">

&lt;columns>
A.P.I para listar as especificações de um tipo de solicitação de atendimento. Parâmetros:

tipoSolicitacao:

<ol>
<li class="level1"> Valor inteiro com a identificação do tipo de solicitação.</li>
</ol>

Resposta esperada:

<ol>
<li class="level1 node"> body: lista de objetos JSON contendo os campos abaixo:<ol>
<li class="level2"> id: identificador da especificação do atendimento.</li>
<li class="level2"> descricao: descrição da especificação.</li>
</ol>
</li>
</ol>

Exemplo:
&lt;/columns>

&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:kaufman3.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 11: Exemplo de request para a rota /gsan/tipoEspecificacaoRA&lt;/center>&lt;/html>
&lt;/WRAP>

</div>

<h3>POST /gsan/verificarExistenciaRAReligacao</h3>
<div class="level3">

&lt;columns>
A.P.I para checar se existe registro de atendimento de religação para o imóvel. Campos do body:

matricula:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

Resposta esperada 1:

<ol>
<li class="level1 node"> body: objeto JSON com os campos abaixo citados:<ol>
<li class="level2"> protocolo: protocolo do registro de atendimento.</li>
<li class="level2"> dataPrevistaAtendimentoRA: a data em que o registro de atendimento está previsto para ser atendido.</li>
<li class="level2"> status: texto informativo que a solicitação já se encontra cadastrada.</li>
</ol>
</li>
</ol>

Exemplo:
&lt;/columns>

&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:kaufman5.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 12.1 – Exemplo de request para a rota /gsan/verificarExistenciaRAReligacao&lt;/center>&lt;/html>
&lt;/WRAP>

&lt;columns>
Resposta esperada 2:

<ol>
<li class="level1 node"> error: objeto JSON com os campos descritos abaixo:<ol>
<li class="level2"> mensagem: mensagem indicando que não existe solicitação cadastrada para a matrícula.</li>
</ol>
</li>
</ol>

&lt;/columns>

&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:kaufman13.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 12.2 – Exemplo 2 de request para a rota /gsan/verificarExistenciaRAReligacao&lt;/center>&lt;/html>
&lt;/WRAP>

&lt;columns>
Observação: No exemplo 12.2 o código de status da resposta é 422.
&lt;/columns>

</div>

<h3>GET /gsan/verificarDebitosImovel</h3>
<div class="level3">

&lt;columns>
A.P.I para checar se o imóvel ainda possui débito em atraso. Parâmetros:

matrícula:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

Resposta esperada:

<ol>
<li class="level1"> message: mensagens de validação dos fluxos conforme descritos nas árvores conversacionais (ver: <a href="https://www.gsan.com.br/doku.php?id=postgres:boto-nlp:abrir-ra:religacao" class="urlextern" title="https://www.gsan.com.br/doku.php?id=postgres:boto-nlp:abrir-ra:religacao" rel="ugc nofollow">https://www.gsan.com.br/doku.php?id=postgres:boto-nlp:abrir-ra:religacao</a>).</li>
<li class="level1 node"> body: objeto JSON com os campos abaixo:<ol>
<li class="level2"> matricula: valor inteiro com a identificação do imóvel no sistema comercial.</li>
<li class="level2"> endereco: endereço do imóvel.</li>
<li class="level2"> cortado: valor booleano indicador se o imóvel encontra-se cortado ou não.</li>
</ol>
</li>
<li class="level1 node"> débitos: objeto JSON referente aos débitos originários do corte, caso possua, com os seguintes campos:<ol>
<li class="level2 node"> contas: lista de objetos JSON com os valores:<ol>
<li class="level3"> id: identificador da conta.</li>
<li class="level3"> referência: mês/ano de referência da conta.</li>
<li class="level3"> valor: valor total da conta.</li>
</ol>
</li>
<li class="level2 node"> guias: lista de objetos JSON com os valores:<ol>
<li class="level3"> id: identificador da guia de pagamento.</li>
<li class="level3"> referência: mês/ano de referência da guia de pagamento.</li>
<li class="level3"> valor: valor total da guia de pagamento.</li>
</ol>
</li>
<li class="level2 node"> débitos: lista de objetos JSON com os valores:<ol>
<li class="level3"> id: identificador do débito a cobrar.</li>
<li class="level3"> referência: mês/ano de referência do débito a cobrar.</li>
<li class="level3"> valor: valor total do débito a cobrar.</li>
</ol>
</li>
</ol>
</li>
</ol>

Exemplo:

&lt;/columns>

&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:13.1.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 13.1 – Exemplo de request para a rota /gsan/verificarDebitosImovel&lt;/center>&lt;/html>
&lt;/WRAP>

&lt;columns>
Exemplo 2:
&lt;/columns>

&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:13.2.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 13.2 – Exemplo 2 de request para a rota /gsan/verificarDebitosImovel&lt;/center>&lt;/html>
&lt;/WRAP>

</div>

<h3>GET /gsan/verificarEmailCadastrado</h3>
<div class="level3">

&lt;columns>
A.P.I para checar se o e-mail informado está vinculado ao cliente do imóvel. Parâmetros:

matrícula:

<ol>
<li class="level1"> Valor inteiro com a identificação do imóvel no sistema comercial.</li>
</ol>

email:

<ol>
<li class="level1"> String com o e-mail para validação.</li>
</ol>

Resposta esperada:

<ol>
<li class="level1"> body: valor booleano indicando se o e-mail informado está associado ao cliente do imóvel ou não.</li>
</ol>

Exemplo:
&lt;/columns>

&lt;WRAP center round box 100%>
<img src="/lib/exe/fetch.php?media=postgres:boto-nlp:14.jpg" class="mediacenter" loading="lazy" alt="" />
&lt;html>&lt;center> Figura 14 – Exemplo 2 de request para a rota /gsan/verificarEmailCadastrado&lt;/center>&lt;/html>
&lt;/WRAP>

~~NOSIDEBAR~~

~~ODT~~

</div>

Enable Complex Tables Editor Height px Turn supplementary image paste support on

Resumo da edição: Minor changes