Consumindo API’s TOTVS e criando um CRUD utilizando o PO UI(novo THF)
Neste artigo vou trazer um passo a passo para criar um CRUD de uma entidade TOTVS de maneira simplificada, e utilizando o PO UI para a interface, sendo este o primeiro de alguns artigos que eu e minha equipe lançaremos para facilitar a integração com produtos TOTVS utilizando API.
Antes de iniciarmos, são necessários alguns pre-requisitos:
- Iniciar um novo projeto Angular(segue link com instruções: angular.io/cli/new )
- Instalar a biblioteca do PO UI (segue Link com instruções: PO-angular)
- Habilitar o Produto Totvs para receber Requisições REST(segue link com instruções: Clique Aqui)
No meu caso, estou utilizando o Protheus, mas a comunicação será a mesma, independentemente do produto utilizado.
Agora, já estamos com os pré-requisitos prontos, mas antes de iniciar a codificação da interface, precisamos decidir qual API utilizaremos para este processo. Acessando o api.totvs.com.br, podemos ver todas as API disponíveis no momento e realizar filtros para localizarmos a que nos interessa mais:
Para este exemplo irei utilizar a API de Cliente/Fornecedor, pois tem todos os verbos disponíveis e não precisa de outros cadastros anteriores.
Agora, com a API escolhida podemos colocar a mão na massa:
Vamos criar um novo módulo no projeto que seja responsável por listar todos os clientes disponíveis no backend — eu irei chamar de customer-list — e, em seguida, já criaremos também um componente e um serviço:
ng generate module customer-list
ng generate service customer-list\customer-list
ng generate component customer-list
Vamos começar criando o serviço de listagem de clientes. Para isso, podemos acessar o arquivo customer-list.service.ts e vamos criar o método que irá buscar estas informações no backend.
Também criei dentro do service um método para estruturar a tabela com nomes mais amigáveis para o usuário final.
Utilizando o componente po-table, passando o parâmetro p-items, já conseguimos gerar uma tabela simples, mas vamos incrementar a tabela, passando também o parâmetro p-columns (para formatar os datos) e o p-actions (darei mais detalhes adiante, neste artigo).
Agora, podemos acessar o arquivo customer-list.component.ts e, na inicialização deste componente, iremos chamar o serviço para listar todos os clientes e colocar na variável vinculada, assim como o retorno da função com a estrutura.
Criando Formulário para Inclusão do Cliente
Primeiro, vamos criar o módulo, o serviço e o componente que iremos trabalhar.
ng generate module customer-form
ng generate service customer-form\customer-form
ng generate component customer-form
Também foram criados alguns models para refletir o formato da entidade na TOTVS. Recomendo baixar estes e colocar no seu projeto.
Neste momento vamos utilizar o componente do PO UI que irá gerar dinamicamente o formulário na tela, também estaremos passando o p-fields que informará a estrutura do formulário e o p-value que será o vinculo com a variável.
Agora, no fonte de serviço já vamos criar um POST para API, que conforme a documentação pede um body com as informações para a inclusão do registro.
As propriedades solicitadas e retornadas pelo formulário são semelhantes as requerida pela API, então vamos, utilizando o modelo passado, adequar estes dados para o envio do POST.
Ao consumir o serviço, fazemos um subscribe para aguardar o retorno da requisição. Neste caso, se for bem sucedida, vamos apresentar uma mensagem informando o sucesso e redirecionaremos novamente para a tela inicial (que contém a lista). Caso ocorra alguma falha, iremos manter a página atual, entretanto informaremos o erro.
Tanto para o sucesso quanto para o erro, estamos utilizando o componente do PO UI de mensagens para fazer esta exibição.
Os Verbos Restantes (PUT e DELETE)
Já estamos nos encaminhando para o final do nosso CRUD. Como citei no começo do artigo, voltamos para o p-actions. Note que nele temos duas ações, uma para deleção e outra para atualização do registro.
Iniciando pela deleção, simplesmente vamos chamar o serviço de DELETE passando a chave necessária para que o backend saiba fazer o processo.
Também utilizamos o subscribe, além do po-notification, para esta requisição. Também, em caso de sucesso, fazemos o processo de GET lista para atualizar o estado da lista.
Além da ação excluir, temos a ação alterar, aqui na lista, que simplesmente chama a pagina formulário passando por parâmetros as informações do registro.
No formulário vamos criar a tratativa para, caso venham os parâmetros, buscar o registro no backend e preencher as informações na tela para facilitar a alteração para o usuário. Além disso, a ação do botão irá chamar um verbo PUT que irá atualizar determinado registro. Este verbo espera receber, além da chave, o body com as informações para alteração.
Outras tratativas se mantém igual ao POST, utilizando o po-notification e retornando para a lista de registros:
Com isso, temos um tela Web consumindo os serviços TOTVS. Assim como comentei anteriormente, este padrão pode ser utilizado para qualquer API, bastando mudar apenas a estrutura dos dados, para o formulário e tabela.
Caso queria acesso ao projeto completo, pode acessar a pagina no GIT Hub:
E fiquem de olho, em breve, lançaremos outros artigos, com mais informações sobre o consumo de API Totvs. Deixem o developers.totvs.com nos seus favoritos, pois além dos artigos de API também temos artigos variados sobre tecnologia.
