API de integração

A API de integração tem por objetivo ser um canal de comunicação entre o Geoserviços e os demais sistemas da Tecsystem.

A integração entre os sistemas se dará através de uma interface que fará a comunicação com o banco de dados do Geoserviços e, opcionalmente, com o Monnae através da API do Monnae.

Essa interface é compilada e distribuída como um pacote padrão Delphi (dcp/bpl) chamado GeoServicosAPI. Para que um sistema possa utilizá-la é necessário incluir esse pacote na lista de Runtime packages do projeto e sempre distribuí-lo junto com a aplicação.

A API fornece também acesso às classes de domínio necessárias para transferir dados entre os sistemas.

Para que a API possa ser utilizada, é necessário obter acesso à interface que dá acesso aos serviços disponíveis. Isso é feito chamando a função getGeoServicosProxy.

function getGeoServicosProxy(const CaminhoBanco: string; const CaminhoIntegracaoMonnae: string = ''): IProxy;

uses IntProxy, ClsGeoservicosProxy;
 
var Proxy: IPRoxy;
 
Proxy := getGeoServicosProxy('CaminhoBancoGeoServicos', 'CaminhoBancoMonnae');

Se o caminho do banco de dados do Monnae estiver em branco, ele será ignorado. A função só retornará uma instância do proxy se conseguir conectar com sucesso no(s) banco(s) de dados informado(s). O banco de dados precisa estar na mesma versão que a API. A validação do banco de dados do Monnae é feita pela API do Monnae.

• ECaminhoBancoMonnaeInvalido: quando a API do Monnae indicar que o caminho é inválido.
• EErroIntegracaoMonnae: quando houver qualquer outro erro com a API do Monnae.
• VersaoIncompativelException: quando o versão do banco de dados não for igual à da API.
• BancoInvalidoException: quando o banco de dados estiver indisponível ou não for possível verificar a versão.
• CaminhoBancoVazioException: quando o caminho do banco do Geoserviços for vazio.
• CaminhoInvalidoException: quando não for possível acessar o bando de dados.
• ConexaoRedeIndisponivelException: quando não for possível acessar o servidor.

function PersistirPessoa(const Pessoa: TPessoaGSP): integer;

Este método deve receber uma pessoa como parâmetro de entrada e persistir essa pessoa no banco de dados do Geoserviços.

Caso a pessoa passada como parâmetro de entrada já exista no banco de dados do Geoserviços o sistema irá fazer apenas um atualização dos dados. Caso contrário, o sistema se encarregará de inserir essa pessoa no Geoserviços. O primeiro critério a ser verificado é o CPF/CNPJ. Se já existir uma pessoa cadastrada com o número do documento igual ao da pessoa enviada pela API, a operação será de atualização. Caso o documento não exista, a atualização só será feita se a pessoa passada como parâmetro tiver um código.

Retorna o código da pessoa.

• ECPFCNPJObrigatorio: quando o documento não for informado.
• ECPFCNPJInvalido: quando o documento for inválido.
• EDataNascimentoFutura: quando a data de nascimento for posterior à data corrente.
• EDataMaior: quando a data de cadastro for posterior à data corrente.
• EPessoaNaoDefinidaException: quando o objeto TPessoaGSP for nulo.
• EErroIntegracaoMonnae: quando houver um erro com a API do Monnae.

procedure ExcluirPessoa(const CodigoPessoaGeoServicos: integer);

Este método deve receber como parâmetro de entrada um código referente a uma pessoa. Caso este código exista no Geoserviços o cadastro da pessoa será excluído do sistema.

• EErroExclusaoPessoaException: quando não for possível excluir a pessoa.
• EErroIntegracaoMonnae: quando houver um erro com a API do Monnae.

function PersistirPontoAtendimento(const PontoAtendimento: TPontoAtendimentoGSP): TPontoAtendimentoGSP;

Este método deve receber um ponto de atendimento como parâmetro e persistir esse ponto no banco de dados do Geoserviços.

Caso o ponto de atendimento já exista no Geoserviços o sistema irá fazer uma atualização dos dados. Caso contrário, o sistema irá inserir um novo ponto de atendimento no Geoserviços. O primeiro critério a ser verificado é o número do documento junto com a categoria do ponto. Se já existir um ponto com o número do documento e categoria iguais aos do ponto enviado pela API, a operação será de atualização. Caso o ponto não exista, a atualização só será feita se o ponto enviado tiver um código.

Retorna o próprio ponto de atendimento com seu código e os códigos dos cadastros vinculados atualizados.

• ENomeObrigatorio: quando o nome do ponto estiver em branco.
• EPontoAtendimentoDuplicado: quando um ponto de atendimento como mesmo nome já existir.
• EPessoaDuplicada: quando uma pessoa for vinculada mais de uma vez no mesmo ponto.
• EResponsavelNaoEncontrado: quando não for definido um responsável pelo ponto.
• EAtividadeDuplicada: quando uma atividade for vinculada mais de uma vez no mesmo ponto.
• ECategoriaObrigatoria: quando a categoria não for definida.
• ETipoDocumentoObrigatorio: quando o tipo do documento não for definido.
• EDocumentoInvalido: quando o documento for inválido.
• EErroIntegracaoMonnae: quando houver um erro com a API do Monnae.

procedure ExcluirPontoAtendimento(const CodigoPontoAtendimento: integer);

Este método deve receber como parâmetro de entrada um código referente a um ponto de atendimento. Caso este código exista no Geoserviços o cadastro será excluído do sistema.

• EErroExclusaoPontoException: quando não for possível excluir o ponto.
• EErroIntegracaoMonnae: quando houver um erro com a API do Monnae.

function RecuperarListaDepartamentos: TDepartamentosGSP;

Este método deve retornar uma lista de departamentos existentes no sistema.

Se nenhum departamento for encontrado, retorna uma lista vazia.

function RecuperarListaCategorias: TCategoriasGSP;

Este método deve retornar uma lista das categorias existentes no sistema.

Se nenhuma categoria for encontrada, retorna uma lista vazia.

function PersistirAtendimento(const Atendimento: TAtendimentoGSP): TAtendimentoGSP;

Este método deve receber como parâmetro um atendimento para ser persistido no banco de dados do Geoserviços.

Retorna o código do atendimento.

• EDataInvalida: quando a data do cadastro for inválida ou não informada.
• EPessoaObrigatoria: quando o solicitante não for informado.
• EPontoAtendimentoObrigatorio: quando o ponto de atendimento não for informado.
• EDadosObrigatorios: quando a lista de serviços não for definida ou estiver vazia.
• EServicoInvalido: quando algum serviço vinculado ao atendimento não for definido.
• EStatusInvalido: quando o status de algum serviço vinculado ao atendimento não for definido.

function RecuperarListaServicos: TServicosGSP;

Este método deve retornar uma lista dos serviços cadastrados no sistema.

Se nenhum serviço for encontrado, retorna uma lista vazia.

function RecuperarListaStatusFinais(const CodigoServico: integer): TStatusServicosGSP;

Este método recebe um código de serviço.

Retorna uma lista dos estados do tipo “final” do serviço informado.

Se nenhum estado for encontrado, retorna uma lista vazia.

function RecuperarServicosPontoAtendimento(const CodigoPontoAtendimento: integer): TServicosPontoGSP; overload;
function RecuperarServicosPontoAtendimento(const CodigoPontoAtendimento: integer; const DataExecucao: TDateTime): TServicosPontoGSP; overload;

Este método deve retornar um objeto do tipo TServicosPontoGSP, uma lista de TServicoPontoGSP que contém os dados do serviço e da execução do serviço num dado atendimento. O sistema que está consumindo a API poderá chamar o método passando como parâmetro, além do código do ponto de atendimento, o período de execução do serviço (data) para recuperar a lista de serviços do ponto de atendimento.

Retorna todos os serviços prestados em atendimentos vinculados ao ponto cujo código foi informado.

Se for informada a data, somente os serviços com data de execução no mesmo ano da data informada serão retornados.

Se nenhum serviço for encontrado, retorna uma lista vazia.

• Fica a cargo da API verificar a autenticidade do banco de dados do Geoserviços, caso a validação falhe a API deve lançar uma exceção que deverá ser capturada pelo sistema que a está utilizando.
• Fica a cargo da API verificar se a versão do BD do Geoserviços utilizado é compatível com a API encontrada no pacote do sistema que a utiliza. Caso não seja compatível a API deverá lançar uma exceção informando que a versão da API não é compatível com a versão do BD do Geoserviços.
• Fica a cargo do software cliente informar a API a localização do banco de dados do Geoserviços que será utilizado na integração.

• Fica a cargo do sistema que está utilizando a API o tratamento das exceções lançadas pela mesma.
• A API deve se encarregar de registrar as ações executadas no Geoserviços.