🚀 Semana 2: Configurando o Servidor REST e Criando a Primeira API em TL++

Olá, Devs! Chegamos à segunda semana da nossa jornada! Depois de entender a arquitetura, é hora de colocar a mão na massa e configurar o coração da nossa solução: o servidor REST do Protheus e a nossa primeira API em TL++.

Nesta postagem, vamos destrinchar as configurações do appserver.ini e analisar o código que transforma dados do Protheus em um payload JSON, pronto para ser consumido pelo nosso Front-end em Flutter!

⚙️ Análise do appserver.ini: O Motor do REST O arquivo appserver.ini é o responsável por transformar o Application Server do Protheus em um servidor REST (HTTP Listener).

💡 Resultado de Sucesso! Ao subir o AppServer com essa configuração e acessar a URL base (http://IP_DO_SERVIDOR:8090/rest), obtemos a tela de login, confirmando que o servidor REST está ativo e exigindo autenticação!

💻 Criando os Endpoints com TL++ (dashboard.tlpp) O código em TL++ é onde a mágica dos dados acontece. Utilizamos a sintaxe limpa do TL++ e as annotations de REST (@Get) para mapear funções ADVPL diretamente para endpoints da nossa API.

Estrutura Básica: Cada função utiliza a annotation @Get seguida pelo nome do endpoint desejado (ex: /fanual):

@Get("/fanual") 
Function u_fat_anual() 

 Local jResponse      := JsonObject():New()
 Local aJson          := {}
 Local jQueryString   := Nil 
 Local cQuery         := Nil

 jQueryString := oRest:getQueryRequest()

// … lógica de banco de dados … 

 If (Select("TRB1") <> 0) 
  dbSelectArea("TRB1") 
  TRB1->(dbCloseArea("TRB1"))
 EndIf

  cQuery := "Select SUBSTRING(E1_VENCTO, 5,2) Mes, SUM(E1_Valor) Honorarios, SUM(E1_Saldo) Saldo, SUM(E1_Valor) - SUM(E1_Saldo) Recebido "
  cQuery += "From Se1010 "
  cQuery += "Where D_E_L_E_T_ = '' And SUBSTRING(E1_VENCTO, 1,4) = '2025' and E1_VENCTO < '20250724' "
  cQuery += "Group By SUBSTRING(E1_VENCTO, 5,2) "
  cQuery += "Order By SUBSTRING(E1_VENCTO, 5,2)"

  PlsQuery(cQuery,"TRB1")
  dbSelectArea("TRB1")
 TRB1->(dbGoTop())

  While TRB1->(!EOF())

    Aadd(aJson,JsonObject():new())
    nPos := Len(aJson)
    aJson[nPos]['mes']        := TRB1->Mes
    aJson[nPos]['honorarios'] := TRB1->Honorarios
    aJson[nPos]['saldo']      := TRB1->Saldo
    aJson[nPos]['recebido']   := TRB1->Recebido

    TRB1->(DbSkip())

  Enddo

  TRB1->(DbCloseArea())

  jResponse:set(aJson)
  oRest:setKeyHeaderResponse('Content-Type','application/json')
  oRest:setResponse(jResponse:toJSON())

// Retorna o JSON 
Return .T.

Destaques da Lógica (u_fat_anual como exemplo):

1. Montagem da Query: Utilizamos a função PlsQuery() com SQL padrão para consultar os dados necessários (Ex: Select SUBSTRING(E1_VENCTO, 5,2) Mes, SUM(E1_Valor) Honorarios… ).
2. Iteração e JSON: Um laço While TRB1->(!EOF()) é usado para percorrer o resultado da consulta.
3. Estrutura do JSON: Para cada registro, um objeto JSON (JsonObject()) é criado e preenchido.
4. Resposta: A função oRest:setResponse(jResponse:toJSON()) empacota o array de objetos JSON e o envia como resposta HTTP.

Endpoints Criados:

• /fanual (Faturamento Anual)
• /vreceber (Valor a Receber)
• /vaberto (Valor em Aberto)
• /fprefixo (Faturamento por Prefixo)
• /utitulos (Últimos Títulos)

🔒 Próximos Passos: Autenticação e Front-end

Com o backend configurado e os dados prontos, o foco da Semana 3 será a criação do nosso Front-end em Flutter!

Para garantir a segurança, utilizaremos o padrão de autenticação OAuth2 nativo do Protheus. A chamada para obtenção do token será feita no endpoint padrão:

/api/oauth2/v1/token

Isso é fundamental para mantermos as credenciais seguras e utilizarmos tokens JWT nas requisições subsequentes.

🔗 Código Fonte

Todos os arquivos mencionados (appserver.ini e dashboard.tlpp) estão disponíveis no meu GitHub. Sinta-se à vontade para clonar e adaptar ao seu ambiente!

GitHub: https://github.com/lllippe/dashboard_tlpp

Vejo vocês na próxima semana, quando iniciaremos o desenvolvimento em Flutter! Fiquem ligados! 🚀

#TOTVS #RESTAPI #Integração #Flutter #TLPP #OAuth2