====== API de integração ======

===== Resumo =====

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

===== Descrição =====

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 [[softwares:monnae:requisitos:modulos:api_integracao|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.

===== Inicialização da API =====

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''.

<code delphi>
function getGeoServicosProxy(const CaminhoBanco: string; const CaminhoIntegracaoMonnae: string = ''): IProxy;
</code>

<code delphi>
uses IntProxy, ClsGeoservicosProxy;

var Proxy: IPRoxy;

Proxy := getGeoServicosProxy('CaminhoBancoGeoServicos', 'CaminhoBancoMonnae');
</code>

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.

==== Exceções ====

  * **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.

===== Pessoas =====

==== Inclusão/alteração ====

<code delphi>
function PersistirPessoa(const Pessoa: TPessoaGSP): integer;
</code>

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.

=== Exceções ===

  * **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.

==== Exclusão ====

<code delphi>
procedure ExcluirPessoa(const CodigoPessoaGeoServicos: integer);
</code>

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.

=== Exceções ===

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

===== Pontos de atendimento =====

==== Inclusão/alteração ====

<code delphi>
function PersistirPontoAtendimento(const PontoAtendimento: TPontoAtendimentoGSP): TPontoAtendimentoGSP;
</code>

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.

=== Exceções ===

  * **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.

==== Exclusão ====

<code delphi>
procedure ExcluirPontoAtendimento(const CodigoPontoAtendimento: integer);
</code>

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.

=== Exceções ===

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

===== Departamentos =====

==== Listar ====

<code delphi>
function RecuperarListaDepartamentos: TDepartamentosGSP;
</code>

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

Se nenhum departamento for encontrado, retorna uma lista vazia.

===== Categorias =====

==== Listar ====

<code delphi>
function RecuperarListaCategorias: TCategoriasGSP;
</code>

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

Se nenhuma categoria for encontrada, retorna uma lista vazia.

===== Atendimentos =====

==== Inclusão/alteração ====

<code delphi>
function PersistirAtendimento(const Atendimento: TAtendimentoGSP): TAtendimentoGSP;
</code>

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.

=== Exceções ===

  * **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.

===== Serviços =====

==== Listar ====

<code delphi>
function RecuperarListaServicos: TServicosGSP;
</code>

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

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

==== Listar status finais ====

<code delphi>
function RecuperarListaStatusFinais(const CodigoServico: integer): TStatusServicosGSP;
</code>

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.

==== Listar serviços por ponto de atendimento ====

<code delphi>
function RecuperarServicosPontoAtendimento(const CodigoPontoAtendimento: integer): TServicosPontoGSP; overload;
function RecuperarServicosPontoAtendimento(const CodigoPontoAtendimento: integer; const DataExecucao: TDateTime): TServicosPontoGSP; overload;
</code>

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.


===== Pontos de verificação =====

==== Conexão ====

  * 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.

==== Utilizaçã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.

===== Observações =====


~~DISCUSSION|Sugira mudanças, aponte falhas ou contribua de alguma forma aqui:~~