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: Validação / Integração - Status Login/Autenticação Segunda Via de Contas 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:

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:

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:

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:

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:

Resposta esperada 2: error: objeto JSON com os campos definidos abaixo: detailMessage: mensagem do erro. Exemplo:

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:

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:

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:

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:

Resposta esperada 2: sem e-mail informado: body: BLOB do arquivo PDF com content-type: aplication/pdf. Exemplo:

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:

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.

Observação: No exemplo 9.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:

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:

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:

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.

Observação: No exemplo 12.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:

Exemplo 2:

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:

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:

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:

~~NOSIDEBAR~~