Se você está começando a trabalhar com integrações no TOTVS Protheus, entender como utilizar o método GET em APIs REST é fundamental. Neste artigo, vou te ensinar, passo a passo, como consumir uma API REST usando o método GET, explicando conceitos importantes e mostrando um exemplo prático com AdvPL e TL++, para quem deseja consultar dados padrão e customizados dentro do Protheus, facilitando a comunicação entre sistemas e plataformas externas.

Por que o método GET é tão importante no Protheus?

O método GET é um dos verbos do protocolo HTTP, utilizado para recuperar dados do servidor. Ou seja, ele serve para pegar informações já armazenadas no sistema e trazê-las para você, sem modificar nada na base de dados.

Dentro do contexto do Protheus e das APIs REST, o GET é o principal método para consultas, seja de clientes, produtos, pedidos de venda, lançamentos financeiros ou qualquer outra informação armazenada no sistema. Ele é fundamental porque:

• Consulta de dados: permite buscar registros de forma rápida e eficiente.
• Requisições idempotentes: fazer a mesma requisição várias vezes não altera o estado do servidor, garantindo segurança nas operações de leitura.
• Sem corpo (Body): as requisições GET geralmente não enviam dados no corpo da requisição, apenas parâmetros via URL.
• Parâmetros via URL: os filtros ou identificadores para a consulta são passados diretamente na URL, seja como parâmetros de query (query parameters) ou parâmetros de caminho (path parameters).

Entendendo os parâmetros na requisição GET

Para exemplificar, imagine que você quer consultar um cliente específico no Protheus. A URL da requisição REST pode ser estruturada assim:

• http://localhost:8080/rest/clientes?codigo=1234 (com parâmetro de query)
• http://localhost:8080/rest/clientes/1234 (com parâmetro de caminho)

Essas URLs indicam ao servidor qual recurso deve ser retornado — no caso, o cliente com código 1234. Através desse caminho, o método GET solicita os dados, e o servidor responde com as informações correspondentes.

Exemplo prático: Consumindo um serviço REST no Protheus

Vamos colocar a mão na massa e fazer uma consulta simples para retornar as companhias cadastradas na base de teste do Protheus. Para isso, você pode acessar a tela de serviços REST, copiar a URL do serviço configurado e fazer a requisição diretamente no VS Code, utilizando uma extensão para testes de API, como o Thunder Client.

Veja como funciona o fluxo básico:

1. Acesse a URL do serviço REST que retorna as companhias.

2. Configure os parâmetros de autorização (Authorization) e Tenant ID, que são necessários para acessar o banco de dados.

3. Envie a requisição GET e receba a resposta com os dados das companhias, como código, nome, tipo (matriz ou filial) e outros detalhes.

Construindo um serviço REST simples com TL++ e AdvPL

Para quem quer ir além do consumo e desenvolver seus próprios serviços REST no Protheus, vamos criar um exemplo básico usando TL++ (uma evolução da linguagem AdvPL). O exemplo consiste em um serviço que responde a uma requisição GET com uma mensagem simples.

Os passos principais são:

• Incluir as bibliotecas padrão do Protheus e do TL++.
• Definir o endpoint do serviço REST, que representa a URL final para acesso.
• Criar uma user function que será chamada na requisição GET.
• Configurar a resposta do serviço usando o método SetResponse que envia um JSON com uma mensagem.

Veja um trecho da estrutura do código:

Esse serviço pode ser compilado e testado diretamente no ambiente Protheus, usando o Thunder Client para enviar a requisição GET e verificar a resposta, conforme você pode conferir na imagem abaixo.

Considerações Finais

Esse foi um breve resumo sobre a introdução ao método GET, recomendamos que assista o nosso vídeo completo no início da página pois nele apresentamos uma explicação completa de cada ponto citado nesse artigo.

Cursos

Se você está buscando se tornar um desenvolvedor completo no Protheus, dominar REST, PO-UI e as demais tecnologias relacionadas ao Protheus, não fique de fora da nossa turma de alunos, clique aqui para mais detalhes.