Página bloqueada

Essa página está bloqueada para edição por outro usuário. Você tem que esperar até que esse usuário termine a edição ou que o bloqueio expire.
Atualmente bloqueada por: 216.73.216.61
O bloqueio expira em: 15/12/2025 16:00 (234 min)
Essa página está em modo somente de leitura. Você pode visualizar a fonte, mas não alterá-la. Informe-se com o administrador do Wiki, caso você ache que isso está incorreto.
{{:postgres:boto-nlp:tatodesk_marca_05.png?nolink&250 |}} \\ \\

\\ \\
====== API de Integração com os Serviços do Chatbot ======
<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).
</columns>
\\
====== Serviços ======
<columns>
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]]**
\\
</columns>
\\
===== Validação/Integração - Status =====
<columns>
**A.P.I** responsável por informar se o sistema comercial está online e apto a receber requisições.
</columns>
\\

==== GET /gsan/verificarBot ====
<columns>
**A.P.I** para obter o status do serviço do sistema comercial.

\\

**Resposta esperada**:

  - **body**: valor booleano
\\

Exemplo:
</columns>

<WRAP center round box 100%>
{{  :postgres:boto-nlp:11111.jpg?nolink  |}}
<html><center> Figura 1 exemplo de request para a rota /gsan/verificarBot</center></html>
</WRAP>
\\


===== Login/Autenticação =====
<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:
</columns>
\\

==== GET /gsan/localidadeImovel ====
<columns>
**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:
</columns>

<WRAP center round box 100%>
{{  :postgres:boto-nlp:figura_1.jpg?nolink  |}}
<html><center> Figura 2 Exemplo de request para a rota /gsan/localidadeImovel</center></html>
</WRAP>
\\

==== GET /gsan/buscarImoveis ====
<columns>
**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:
</columns>
<WRAP center round box 100%>
{{  :postgres:boto-nlp:figura_2.jpg?nolink  |}}
<html><center> Figura 3 Exemplo de request para a rota /gsan/buscarImoveis</center></html>
</WRAP>
\\

==== GET /gsan/verificarMatriculaCpfCnpj ====
<columns>
**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:
</columns>
<WRAP center round box 100%>
{{  :postgres:boto-nlp:figura_3.jpg?nolink  |}}
<html><center> Figura 4: Exemplo de request para a rota /gsan/verificarMatriculaCpfCnpj</center></html>
</WRAP>
\\
==== GET /gsan/chatbot/autenticarMatricula ====
<columns>
**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:
</columns>
<WRAP center round box 100%>
{{  :postgres:boto-nlp:figura_4.1.jpg?nolink  |}}
<html><center> Figura 5.1: Exemplo de request para a rota /gsan/chatbot/autenticarMatricula</center></html>
</WRAP>

<columns>
\\
**Resposta esperada 2**:

  - **error**: objeto **JSON** com os campos definidos abaixo:
    - **detailMessage**: mensagem do erro.
\\

Exemplo:
</columns>
<WRAP center round box 100%>
{{  :postgres:boto-nlp:figura_4.2.jpg?nolink  |}}
<html><center> Figura 5.2: Exemplo de request para a rota /gsan/chatbot/autenticarMatricula</center></html>
</WRAP>

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

===== Segunda Via de Contas =====
<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:
</columns>
\\

==== GET /gsan/segundaViaConta ====
<columns>
**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:
</columns>
<WRAP center round box 100%>
{{  :postgres:boto-nlp:figura_5.jpg?nolink  |}}
<html><center> Figura 6: Exemplo de request para a rota /gsan/segundaViaConta</center></html>
</WRAP>
\\

==== GET /gsan/segundaViaContaTotal ====
<columns>
**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:
</columns>
<WRAP center round box 100%>
{{  :postgres:boto-nlp:figura_6.jpg?nolink  |}}
<html><center> Figura 7: Exemplo de request para a rota /gsan/segundaViaContaTotal</center></html>
</WRAP>
\\

==== GET /gsan/segundaViaCodigoBarra ====
<columns>
**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:
</columns>
<WRAP center round box 100%>
{{  :postgres:boto-nlp:figura_7.jpg?nolink  |}}
<html><center> Figura 8: Exemplo de request para a rota /gsan/segundaViaCodigoBarra</center></html>
</WRAP>

\\

==== GET /gsan/segundaViaContaRelatorio ====
<columns>
**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:
</columns>
<WRAP center round box 100%>
{{  :postgres:boto-nlp:figura_8.1.jpg?nolink  |}}
<html><center> Figura 9.1: Exemplo de request para a rota /gsan/segundaViaContaRelatorio com e-mail</center></html>
</WRAP>
\\

<columns>
**Resposta esperada 2**: sem e-mail informado:
  - **body**: **BLOB** do arquivo PDF com **content-type: aplication/pdf**.
\\

Exemplo:
</columns>
<WRAP center round box 100%>
{{  :postgres:boto-nlp:figura_8.2.jpg?nolink  |}}
<html><center> Figura 9.2: Exemplo de request para a rota /gsan/segundaViaContaRelatorio sem e-mail</center></html>
</WRAP>
\\


===== Abrir RA: Falta D’Água, Vazamento e Religação =====
<columns>
**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:
</columns>

\\
==== POST /gsan/verificarRAWS ====
<columns>
**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:
</columns>
\\

<WRAP center round box 100%>
{{  :postgres:boto-nlp:figura_9.jpg?nolink  |}}
<html><center> Figura 10.1: Exemplo de request para a rota /gsan/verficarRAWS com RA pendente</center></html>
</WRAP>
<columns>
\\

**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.
</columns>
\\

<WRAP center round box 100%>
{{  :postgres:boto-nlp:9.2.jpg?nolink  |}}
<html><center> Figura 10.2: Exemplo de request para a rota /gsan/verficarRAWS sem RA pendente</center></html>
</WRAP>
\\

<columns>
**Observação**: No exemplo **10.2** o código de status da resposta é **422**.
</columns>

\\
==== GET /gsan/episodiosFaltaAgua ====
<columns>
**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:
</columns>
\\

<WRAP center round box 100%>
{{  :postgres:boto-nlp:kaufman2.jpg?nolink  |}}
<html><center> Figura 11: Exemplo de request para a rota /gsan/episodiosFaltaAgua</center></html>
</WRAP>

\\

==== GET /gsan/tipoEspecificacaoRA ====
<columns>
**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:
</columns>
\\

<WRAP center round box 100%>
{{  :postgres:boto-nlp:kaufman3.jpg?nolink  |}}
<html><center> Figura 12: Exemplo de request para a rota /gsan/tipoEspecificacaoRA</center></html>
</WRAP>
\\
==== POST /gsan/verificarExistenciaRAReligacao ====
<columns>
**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:
</columns>
\\

<WRAP center round box 100%>
{{  :postgres:boto-nlp:kaufman5.jpg?nolink  |}}
<html><center> Figura 13.1 – Exemplo de request para a rota /gsan/verificarExistenciaRAReligacao</center></html>
</WRAP>
\\

<columns>
**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.
</columns>
\\

<WRAP center round box 100%>
{{  :postgres:boto-nlp:kaufman13.jpg?nolink  |}}
<html><center> Figura 13.2 – Exemplo 2 de request para a rota /gsan/verificarExistenciaRAReligacao</center></html>
</WRAP>
\\

<columns>
**Observação**: No exemplo **13.2** o código de status da resposta é **422**.
</columns>

\\
==== GET /gsan/verificarDebitosImovel ====
<columns>
**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:

</columns>
\\

<WRAP center round box 100%>
{{  :postgres:boto-nlp:13.1.jpg?nolink  |}}
<html><center> Figura 14.1 – Exemplo de request para a rota /gsan/verificarDebitosImovel</center></html>
</WRAP>
\\
<columns>
Exemplo 2:
</columns>

\\

<WRAP center round box 100%>
{{  :postgres:boto-nlp:13.2.jpg?nolink  |}}
<html><center> Figura 14.2 – Exemplo 2 de request para a rota /gsan/verificarDebitosImovel</center></html>
</WRAP>


==== GET /gsan/verificarEmailCadastrado ====
<columns>
**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:
</columns>

\\

<WRAP center round box 100%>
{{  :postgres:boto-nlp:14.jpg?nolink  |}}
<html><center> Figura 15 – Exemplo 2 de request para a rota /gsan/verificarEmailCadastrado</center></html>
</WRAP>
\\

==== POST /gsan/inserirRAWS ====
<columns>
**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:
</columns>

\\

<WRAP center round box 100%>
{{  :postgres:boto-nlp:15.jpg?nolink  |}}
<html><center> Figura 16 – Exemplo de request para a rota /gsan/inserirRAWS</html>
</WRAP>
\\

==== POST /gsan/inserirRAReligacao ====
<columns>
**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:
</columns>

\\

<WRAP center round box 100%>
{{  :postgres:boto-nlp:16.jpg?nolink  |}}
<html><center> Figura 17 – Exemplo de request para a rota /gsan/inserirRAReligacao</html>
</WRAP>



\\
Clique **[[=postgres:tatodesk|AQUI]]** para retornar.
~~NOSIDEBAR~~
\\
~~ODT~~