Especificação funcional: API de integração

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

A API de integração é formada por um conjunto de classes que permitem que outros sistemas se comuniquem e troquem dados com o Monnae de forma padronizada e controlada. Ela é constituída basicamente de uma interface, que disponibiliza os recursos acessíveis através da API, e uma série de classes auxiliares que facilitam o uso desses serviços.

Essa interface é compilada e distribuída como um pacote padrão Delphi (dcp/bpl) chamado APIIntegracao. 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.

Após incluir o pacote no projeto, será necessário incluir as units IntMonnaeProxy e UntMonnaeProxy. A primeira contém a interface da API - IMonnaeProxy - que disponibiliza todos os métodos que podem ser utilizados, enquanto a segunda contém a classe que implementa essa interface: TMonnaeProxy.

Para ter acesso à classe da API que implementa IMonnaeProxy é necessário invocar o método GetMonnaeProxy, passando como parâmetro o caminho do banco de dados do Monnae ao qual se deseja ter acesso. Esse método retorna um objeto do tipo IMonnaeProxy e a partir dele será possível invocar todos os demais métodos da API.

unit AcessoAPI;
 
interface
 
uses
  Contnrs, IntMonnaeProxy, UntMonnaeProxy;
 
implementation
 
procedure RecuperarCentrosCusto;
var
  APIMonnae: IMonnaeProxy;
  CentrosCusto: TObjectList;
begin
  APIMonnae := GetMonnaeProxy('C:\Monnae.fdb');
  CentrosCusto := APIMonnae.RecuperarListaCentrosCusto;
end;
 
end.

O uso do método GetMonnaeProxy pode disparar as seguintes exceções:

• VersaoIncompativelException: Indica que a versão da API é incompatível com a versão do Monnae.
• CaminhoBancoVazioException: Indica que o caminho do banco de dados não foi passado para a API;
• CaminhoInvalidoException: Indica que o caminho do banco de dados é inválido ou está incorreto e o banco de dados não pôde ser localizado;
• BancoInvalidoException: Indica que o banco de dados informado é inválido ou não é um banco de dados do Tecsystem Monnae;
• ConexaoRedeIndisponivelException: Indica problemas na conexão com o banco de dados através da rede.

function PersistirPessoa(Pessoa: TPessoaMP): integer; 

• Pessoa: Objeto (TPessoaMP) que contém os dados da pessoa.

Código da pessoa no Monnae.

A API verifica se uma pessoa já existe através do seu número de documento (CPF ou CNPJ). Caso a pessoa já exista, seus dados serão sobrescritos pelos dados que estão sendo enviados. Caso ela ainda não exista no banco de dados do Monnae, uma nova pessoa será incluída. Em ambos os casos a função irá retornar o código da pessoa no Monnae. Obs: Se uma pessoa com um código for enviada pela aplicação que consome a API ela será persistida sem que haja a verificação do documento, pois a API assume que esse código foi anteriormente incluído no Monnae e está sendo utilizado pela aplicação que a consome.

O uso do método PersistirPessoa pode disparar as seguintes exceções:

• PessoaNaoDefinidaException: Indica que nenhum objeto foi passado como parâmetro;
• NomeNaoPreenchidoException: Indica que o nome da pessoa não foi preenchido;
• DocumentoPessoaInexistenteException: Indica que o número do documento principal da pessoa (CPF ou CNPJ) não foi preenchido;
• DocumentoPessoaInvalidoException: Indica que o número do documento principal da pessoa (CPF ou CNPJ) é inválido;
• TipoPessoaInvalidoException: Indica que o tipo da pessoa (física/jurídica) é inválido;
• DataCadastroInvalidaException: Indica que a data de cadastro da pessoa é inválida ou não foi informada;
• SituacaoPessoaInvalidaException: Indica que a situação da pessoa (ativa/inativa) é inválida.

procedure ExcluirPessoa(CodigoPessoa: integer);

• CodigoPessoa: Código da pessoa que será excluída.

Nenhum.

O Monnae só permite que uma pessoa seja excluída caso ela não possua nenhum título vinculado. Para excluir uma pessoa que já tenha títulos cadastrados, será necessário excluir os títulos primeiro e só depois excluir a pessoa.

O uso do método ExcluirPessoa pode disparar as seguintes exceções:

• PessoaVinculadaException: Indica que a pessoa possui vínculo com algum título no Monnae.

function PersistirTitulo(Titulo: TTituloMP): integer;

• Titulo: Objeto (TTituloMP) que contém os dados do título.

Código do título no Monnae.

A API verifica se um título já existe através de seu código. Se o título informado tiver código igual ou menor do que zero, um novo título será incluído. Caso contrário a API irá buscar um título já existente através do código informado. Caso o título seja encontrado, seus dados serão sobrescritos pelos dados atuais. Caso o título não seja encontrado, uma exceção será lançada. Em ambos os casos (inclusão/alteração) a função irá retornar o código do título no Monnae.

O uso do método PersistirTitulo pode disparar as seguintes exceções:

• TituloNaoDefinidoException: Indica que nenhum objeto foi passado como parâmetro;
• TituloNaoEncontradoException: Indica que o título passado como parâmetro possui um código maior do que zero, mas esse título não foi encontrado no Monnae;
• TituloJaPagoException: Indica que o título já foi pago e por isso não pode ser alterado;
• PessoaNaoDefinidaException: Indica que o título passado como parâmetro não possui nenhuma pessoa vinvulada;
• PessoaNaoEncontradaException: Indica que a pessoa vinculada ao título não está cadastrada no Monnae;
• PessoaInativaException: Indica que a pessoa está inativa no Monnae e por isso não é possível incluir um título para essa pessoa. Alterações de títulos existentes são permitidas;
• NumeroDocNaoPreenchidoException: Indica que o número do documento não foi preenchido;
• DataEmissaoNaoPreenchidaException: Indica que a data de emissão não foi preenchida;
• DataVencimentoNaoPreenchidaException: Indica que a data de vencimento não foi preenchida;
• DataVencimentoInvalidaException: Indica que a data de vencimento é menor que a data de emissão;
• ValorNaoPreenchidoException: Indica que o valor do título não foi informado, é igual ou menor que zero;
• ContaNaoDefinidaException: Indica que o título passado como parâmetro não possui nenhuma conta vinculada;
• ClasseInvalidaException: Indica que a lista de contas do título possui um objeto que não é uma conta (não é uma instância de TContaMP);
• ContaValorInvalidoException: Indica que uma das contas da lista de contas do título não contém um valor válido (valor maior do que zero);
• ContaInexistenteException: Indica que a conta vinculada ao título não existe mais no Monnae;
• ContaInativaException: Indica que a conta vinculada ao título está inativa no Monnae e por isso não pode ser usada;
• ContasDuplicadasException: Indica que existem duas ou mais contas duplicadas na lista de contas do título (contas duplicadas possuem mesma operação, grupo, subgrupo, nome e centro de custo);
• TotalContasInvalidoException: Indica que a soma das contas da lista de contas do título é diferente do valor do título;
• CentroCustoNaoDefinidoException: Indica que a conta vinculada ao título não possui um centro de custo vinculado;
• CentroCustoInexistenteException: Indica que o centro de custo vinculado ao título não existe no Monnae;
• CentroCustoInativoException: Indica que o centro de custo vinculado ao título está inativo no Monnae e por isso não pode ser usado;

procedure ExcluirTitulo(CodigoTitulo: integer);

• CodigoTitulo: Código do título que será excluído.

Nenhum.

O Monnae só permite que um título seja excluído caso ele ainda não tenha sido pago.

O uso do método ExcluirTitulo pode disparar as seguintes exceções:

• TituloJaPagoException: Indica que o título já foi pago e por isso não pode ser excluído.

function RecuperarTitulo(CodigoTitulo: integer): TTituloMP;

• CodigoTitulo: Código do título que será recuperado.

Objeto do tipo TTituloMP que contém os dados do título.

O uso do método RecuperarTitulo pode disparar as seguintes exceções:

• TituloNaoEncontradoException: Indica que o título não foi encontrado no Monnae.

function VerificarTituloPago(CodigoTitulo: integer): Boolean;

• CodigoTitulo: Código do título que será verificado.

Valor booleano que indica se o título foi (true) ou não (false) baixado.

O uso do método VerificarTituloPago não dispara exceções, mesmo que o título já não exista mais no Monnae.

function RecuperarConta(CodigoConta: integer): TContaMP;

• CodigoConta: Código da conta que será recuperada.

Objeto do tipo TContaMP que contém os dados da conta.

O uso do método RecuperarConta pode disparar as seguintes exceções:

• ContaInvalidaException: Indica que a conta não existe no Monnae.

function RecuperarListaContas(Operacao: EnTipoOperacaoMP.Valores = credito): TObjectList;

• Operação: Tipo de operação (débito/crédito) das contas que serão recuperadas.

Lista (TObjectList) de objetos do tipo TContaMP, cada um contendo os dados de uma conta.

O método RecuperarListaContas recupera apenas as contas ativas no Monnae. Caso não existam contas a serem retornadas, o método retornará um valor nulo (nil). O uso desse método não dispara exceções.

function RecuperarCentroCusto(Codigo: integer): TCentroCustoMP; overload;
function RecuperarCentroCusto(Nome: string): TCentroCustoMP; overload;

• Codigo/Nome: Código ou Nome do centro de custo que será recuperado.

Objeto do tipo TCentroCustoMP que contém as informações do centro de custo.

Caso o método RecuperarCentroCusto não encontre o centro de custo desejado, o método retornará um valor nulo (nil). O uso desse método não dispara exceções.

function RecuperarListaCentrosCusto: TObjectList;

Nenhum.

Lista (TObjectList) de objetos do tipo TCentroCustoMP, cada um contendo os dados de um centro de custo.

O método RecuperarListaCentrosCusto recupera apenas os centros de custo ativos no Monnae. Caso não existam centros de custo a serem retornados, o método retornará um valor nulo (nil). O uso desse método não dispara exceções.

function RecuperarLimiteCreditoDisponivel(CodigoPessoa: integer; const LimiteCredito: currency = 0): Currency;

• Codigo da pessoa.

Retorna a diferença entre o limite de crédito pré cadastrado na pessoa e a soma dos títulos em aberto dessa pessoa (PROCRECUPERARLIMITEDISPONIVEL).

Caso o limite de crédito informado no cadastro da pessoa seja 0,00 a função sempre retornará zero.

Obs: O parâmetro LimiteCredito serve para atualizar o limite disponível no caso de inclusão ou alteração do limite de crédito em que o valor ainda não esteja guardado no bando de dados. O procedure deverá verificar se esse valor é zero antes de pesquisar o valor no BD, caso o valor seja maior que zero o procedure assumirá esse valor como limite de crédito e retornará a diferença desse valor e a soma dos títulos de crédito em aberto da pessoa.

function RecuperarLimiteCreditoConcedido(CodigoPessoa: integer): Currency;

• Codigo da pessoa.

Retorna o limite de crédito concedido no cadastro da pessoa (PROCRECUPERARLIMITECONCEDIDO).

function RecuperarLimiteCreditoUtilizado(CodigoPessoa: integer; const LimiteCredito: currency = 0): Currency;

• Codigo da pessoa.

Retorna o limite de utilizado pela pessoa no Monnae(PROCRECUPERARLIMITEUTILIZADO). Esse valor é retornado da subtração entre o limite concedido e o limite disponível.

Obs: Caso seja passado valor no parâmetro LimiteCredito esse valor será levado em consideração como sendo o limite concedido.

function RecuperarCodigoPlanoContasPessoa(CodigoPessoa: integer): Integer;

• Codigo da pessoa.

Retorna o código do plano de contas padrão cadastrado na pessoa.

function PessoaIsentaDeCobranca(CodigoPessoa: integer): Boolean;

• Codigo da pessoa.

Retorna true se a pessoa for isenta de cobrança e false para o caso contrário.

A classe TPessoaMP (ClsPessoaMP) contém os atributos necessários para que se possa cadastrar uma pessoa no Monnae. Esta classe está contida na API pois há a necessidade de vinculo entre um título e uma pessoa. Logo, para que um título possa ser incluído, a pessoa deverá estar previamente cadastrada no Monnae.

A classe TContaMP (ClsContaMP) contém os atributos pertinentes a uma conta de um plano de contas.

A classe TCentroCustoMP (ClsCentroCustoMP) contém atributos pertinentes a um centro de custo.

A classe TTituloMP (ClsTituloMP) contém atributos pertinentes a um título de cobrança.

• EnSituacaoContaMP (EnumSituacaoContaMP): Define os valores possíveis para a situação de uma conta: ativa, inativa;
• EnSituacaoPessoaMP (EnumSituacaoPessoaMP): Define os valores possíveis para a situação de uma pessoa: ativo, inativo;
• EnTipoPessoaMP (EnumTipoPessoaMP): Define os valores possíveis para o tipo de uma pessoa: fisica, juridica;
• EnTipoOperacaoMP (EnumTipoOperacaoMP): Define os valores possíveis para a o tipo de operação de um título ou de uma conta: debito, credito;

Todos os tipos enumerados possuem um método para retornar a lista de valores possíveis, para converter um valor em string e para converter uma string no valor correspondente.

Todas as exceções lançadas pela API estão definidas na unit UntExcecoesMP.

O comportamento da API e as exceções lançadas estão descritas em cada serviço.