====== Especificação funcional: API de integração ====== ===== Resumo ===== A API de integração tem por objetivo ser um canal de comunicação entre o Tecsystem Monnae e os demais sistemas da Tecsystem. ===== Descrição ===== 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. ===== Uso básico ===== 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. ==== Exemplo de uso ==== 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. ==== Exceções ==== 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. ===== Serviços disponibilizados pela API ===== ==== Inclusão/alteração de pessoas ==== == Assinatura do método == function PersistirPessoa(Pessoa: TPessoaMP): integer; == Parâmetros == * Pessoa: Objeto (//TPessoaMP//) que contém os dados da pessoa. == Retorno == Código da pessoa no Monnae. == Exceções e outras informações == 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. ==== Exclusão de pessoas ==== == Assinatura do método == procedure ExcluirPessoa(CodigoPessoa: integer); == Parâmetros == * CodigoPessoa: Código da pessoa que será excluída. == Retorno == Nenhum. == Exceções e outras informações == 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. ==== Inclusão/alteração de títulos ==== == Assinatura do método == function PersistirTitulo(Titulo: TTituloMP): integer; == Parâmetros == * Titulo: Objeto (//TTituloMP//) que contém os dados do título. == Retorno == Código do título no Monnae. == Exceções e outras informações == 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; ==== Exclusão de títulos==== == Assinatura do método == procedure ExcluirTitulo(CodigoTitulo: integer); == Parâmetros == * CodigoTitulo: Código do título que será excluído. == Retorno == Nenhum. == Exceções e outras informações == 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. ==== Recuperação de títulos==== == Assinatura do método == function RecuperarTitulo(CodigoTitulo: integer): TTituloMP; == Parâmetros == * CodigoTitulo: Código do título que será recuperado. == Retorno == Objeto do tipo TTituloMP que contém os dados do título. == Exceções e outras informações == O uso do método //RecuperarTitulo// pode disparar as seguintes exceções: * **TituloNaoEncontradoException**: Indica que o título não foi encontrado no Monnae. ==== Verificação de baixa de títulos ==== == Assinatura do método == function VerificarTituloPago(CodigoTitulo: integer): Boolean; == Parâmetros == * CodigoTitulo: Código do título que será verificado. == Retorno == Valor booleano que indica se o título foi (true) ou não (false) baixado. == Exceções e outras informações == O uso do método //VerificarTituloPago// não dispara exceções, mesmo que o título já não exista mais no Monnae. ==== Recuperação de contas ==== == Assinatura do método == function RecuperarConta(CodigoConta: integer): TContaMP; == Parâmetros == * CodigoConta: Código da conta que será recuperada. == Retorno == Objeto do tipo TContaMP que contém os dados da conta. == Exceções e outras informações == O uso do método //RecuperarConta// pode disparar as seguintes exceções: * **ContaInvalidaException**: Indica que a conta não existe no Monnae. ==== Recuperação da lista de contas ==== == Assinatura do método == function RecuperarListaContas(Operacao: EnTipoOperacaoMP.Valores = credito): TObjectList; == Parâmetros == * Operação: Tipo de operação (débito/crédito) das contas que serão recuperadas. == Retorno == Lista (TObjectList) de objetos do tipo TContaMP, cada um contendo os dados de uma conta. == Exceções e outras informações == 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. ==== Recuperação de centros de custo ==== == Assinatura do método == function RecuperarCentroCusto(Codigo: integer): TCentroCustoMP; overload; function RecuperarCentroCusto(Nome: string): TCentroCustoMP; overload; == Parâmetros == * Codigo/Nome: Código ou Nome do centro de custo que será recuperado. == Retorno == Objeto do tipo TCentroCustoMP que contém as informações do centro de custo. == Exceções e outras informações == 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. ==== Recuperação da lista de centros de custo ==== == Assinatura do método == function RecuperarListaCentrosCusto: TObjectList; == Parâmetros == Nenhum. == Retorno == Lista (TObjectList) de objetos do tipo TCentroCustoMP, cada um contendo os dados de um centro de custo. == Exceções e outras informações == 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. ==== Recuperação do limite de crédito da pessoa ==== == Assinatura do método == function RecuperarLimiteCreditoDisponivel(CodigoPessoa: integer; const LimiteCredito: currency = 0): Currency; == Parâmetros == * Codigo da pessoa. == Retorno == 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). == Exceções e outras informações == 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. ==== Recuperação do limite de concedido para pessoa ==== == Assinatura do método == function RecuperarLimiteCreditoConcedido(CodigoPessoa: integer): Currency; == Parâmetros == * Codigo da pessoa. == Retorno == Retorna o limite de crédito concedido no cadastro da pessoa (PROCRECUPERARLIMITECONCEDIDO). ==== Recuperação do limite de utilizado da pessoa ==== == Assinatura do método == function RecuperarLimiteCreditoUtilizado(CodigoPessoa: integer; const LimiteCredito: currency = 0): Currency; == Parâmetros == * Codigo da pessoa. == Retorno == 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. ==== Recuperação do código do plano de contas padrão da pessoa ==== == Assinatura do método == function RecuperarCodigoPlanoContasPessoa(CodigoPessoa: integer): Integer; == Parâmetros == * Codigo da pessoa. == Retorno == Retorna o código do plano de contas padrão cadastrado na pessoa. ==== Recuperação da propriedade isenta de cobrança da pessoa ==== == Assinatura do método == function PessoaIsentaDeCobranca(CodigoPessoa: integer): Boolean; == Parâmetros == * Codigo da pessoa. == Retorno == Retorna true se a pessoa for isenta de cobrança e false para o caso contrário. ===== Objetos de domínio e classes de apoio ===== ==== Pessoa ==== 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. |< 100% 19% 60% 7% 7% 7%>| ^ Campo ^ Descrição ^ Tipo ^ Tamanho ^ Obrigatório? ^ |Código |Código da pessoa | Inteiro | -- | Sim | |Tipo |Define o tipo da pessoa: física ou jurídica | Enumerado | -- | Sim | |Nome/Razão Social |Nome/Razão Social da pessoa | Texto | 60 | Sim | |Apelido/Nome fantasia |Apelido/Nome fantasia da pessoa | Texto | 60 | Não | |Logradouro |Endereço da pessoa(Rua, Avenida...) | Texto | 80 | Não | |Número |Número do endereço da pessoa | Texto | 05 | Não | |Complemento |Complemento do endereço da pessoa | Texto | 80 | Não | |Bairro |Bairro da pessoa | Texto | 30 | Não | |Município |Município onde se localiza a pessoa | Texto | 60 | Não | |UF |Estado onde se localiza o endereço da pessoa | Texto | 02 | Não | |País |País onde se localiza o endereço da pessoa | Texto | 60 | Não | |Cep |Cep do endereço da pessoa | Numérico | 09 | Não | |Cpf/Cnpj |Documento da pessoa | Numérico | 14 | Não | |Rg/Inscrição estadual |Documento da pessoa | Numérico | 18 | Não | |Telefone |Contato da pessoa | Numérico | 18 | Não | |Fax |Contato da pessoa | Numérico | 18 | Não | |Celular |Contato da pessoa | Numérico | 18 | Não | |Email |Contato da pessoa | Texto | 50 | Não | |Grupo |Campo de cadastro para utilização livre do usuário(Grupo de enquadramento da pessoa) | Texto | 20 | Não | |Situação |Situação da pessoa: Ativa ou Inativa | Enumerado | -- | Sim | |Data de cadastro |Data em que a pessoa foi cadastrada | Data | -- | Sim | |Código interno |Código livre que pode ser atribuído a uma pessoa no Monnae | Texto | 30 | Não | |Observações |Observações relacionadas a pessoa | Texto | 2000 | Não | |Limite de crédito |Limite de crédito da pessoa | Numérico | 16 | Não | |Código plano contas |Código do plano de contas padrão | Inteiro | -- | Não | |Isenta de cobrança |Isenta a pessoa da cobrança do módulo de cobrança | Booleano | -- | Sim | O campo grupo deverá enviar valor se houver ou null se não houver valor para o banco. O banco deverá persistir esse campo apenas se houver valor, isso está sendo feito para que o campo não seja atualizado sem valor caso não esteja sendo utilizado por quem consome a API. ==== Conta ==== A classe //TContaMP// (ClsContaMP) contém os atributos pertinentes a uma conta de um plano de contas. |< 100% 19% 60% 7% 7% 7%>| ^ Campo ^ Descrição ^ Tipo ^ Tamanho ^ Obrigatório? ^ |Código |Código da conta | Inteiro | -- | Sim | |Operação |Tipo da operação (Débito ou Crédito) | Enumerado | -- | Sim | |Grupo |Grupo ao qual a conta pertence | Texto | 30 | Sim | |Subgrupo |Subgrupo ao qual a conta pertence | Texto | 30 | Sim | |Número |Número da conta | Texto | 33 | Não | |Nome |Nome da conta | Texto | 30 | Sim | |Descrição |Descrição da conta | Texto | 200 | Não | |Valor |Valor que será atribuído à conta no título | Numérico | 11 | Sim | |Situação |Situação da conta (ativa ou inativa) | Enumerado | -- | Sim | |Centro de custo |Centro de custo vinculado à conta (durante a persistência de um título) | Enumerado | -- | Sim | ==== Centro de custo ==== A classe //TCentroCustoMP// (ClsCentroCustoMP) contém atributos pertinentes a um centro de custo. |< 100% 19% 60% 7% 7% 7%>| ^ Campo ^ Descrição ^ Tipo ^ Tamanho ^ Obrigatório? ^ |Código |Código do centro de custo | Inteiro | -- | Sim | |Nome |Nome do centro de custo | Texto | 60 | Sim | |Classificação |Classificação do centro de custo | Texto | 20 | Sim | |Descrição |Descrição do centro de custo | Texto | 500 | Não | |Observações |Informações adicionais do centro de custo | Texto | 2000 | Não | |Padrão |Indica se o centro de custo está configurado como padrão do sistema | Booleano | -- | Sim | |Situação |Situação atual do centro de custo (ativo/inativo) | Enumerado | -- | Sim | ==== Título ==== A classe //TTituloMP// (ClsTituloMP) contém atributos pertinentes a um título de cobrança. |< 100% 19% 60% 7% 7% 7%>| ^ Campo ^ Descrição ^ Tipo ^ Tamanho ^ Obrigatório? ^ |Código |Código do título | Inteiro | -- | Sim | |Operação |Define o tipo do título: receita (crédito) ou despesa (débito) | Enumerado | -- | Sim | |CodigoPessoa |Código da Pessoa, no Monnae, ao qual o título está vinculado | Numérico | -- | Sim | |Histórico |Descrição do título | Texto | 200 | Não | |Portador |Portador do título | Texto | 60 | Não | |Número |Número do documento | Texto | 25 | Sim | |Data de competência |Data de competência do título | Data | -- | Não | |Data de emissão |Data de emissão do título | Data | -- | Sim | |Data de vencimento |Data de vencimento do título | Data | -- | Sim | |Valor |Valor integral do título | Numérico | 11 | Sim | |Contas |Lista de contas (TObjectList) que classificam o título de acordo com sua natureza. | Objeto | -- | Sim | |Observações |Observações relacionadas ao título | Texto | 2000 | Não | ==== Tipos enumerados ==== * 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. ==== Exceções ==== Todas as exceções lançadas pela API estão definidas na //unit// UntExcecoesMP. ===== Pontos de verificação ===== O comportamento da API e as exceções lançadas estão descritas em cada serviço. ===== Observações ===== ~~DISCUSSION|Sugira mudanças, aponte falhas ou contribua de alguma forma aqui:~~