Essa é uma revisão anterior do documento!
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:
-
-
-
|
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:
|
Figura 1 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:
|
Figura 2 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:
|
Figura 3: 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:
|
Figura 4.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:
|
Figura 4.2: Exemplo de request para a rota /gsan/chatbot/autenticarMatricula
Observação: No exemplo 4.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:
|
Figura 5: 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:
|
Figura 6: Exemplo de request para a rota /gsan/segundaViaContaTotal
GET /gsan/segundaViaCodigoBarra
A.P.I para obter os códigos de barras 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:
|
Figura 7: 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:
|
Figura 8.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:
|
Figura 8.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 (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:
|
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:
|
Figura 9.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.
|
Figura 9.2: Exemplo de request para a rota /gsan/verficarRAWS sem RA pendente
Observação: Nesse segundo exemplo 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:
|
Figura 10: Exemplo de request para a rota /gsan/episdiosFaltaAgua