Olá! neste artigo, vou te guiar passo a passo para debugar uma API REST do TOTVS Protheus usando o VS Code e as ferramentas TOTVS. Se você trabalha com ADVPL, TL++ e integrações REST, este conteúdo vai economizar muito tempo na hora de localizar e corrigir erros.
O que você vai aprender
- O conceito básico de debug e porque ele é essencial;
- Diferenças entre debug clássico (sem multithread) e debug com multithread;
- Configuração prática do VS Code para interceptar requisições API;
- Teste prático com Thunder Client e uma aplicação POUI.
O que é o debug?
Debug é a técnica de executar um programa passo a passo para localizar o ponto exato em que o comportamento ou erro ocorre. Em vez de tentar adivinhar onde o problema está, você executa o código linha a linha, observa variáveis e o fluxo, e corrige com precisão.
Debug clássico no Protheus (sem multithread)
No modo tradicional de debug do Protheus (programas no RPO, ADVPL/TL++), o fluxo típico é:
- Smart Client faz a solicitação;
- App Server carrega o programa do RPO;
- VS Code (via configuração de debug) intercepta a execução e para no breakpoint;
- Enquanto o breakpoint está ativo, você consegue abrir outro Smart Client e continuar trabalhando em outros módulos normalmente.
Isso é útil porque apenas a sessão depurada fica parada — os demais usuários e sessões continuam funcionando.
Debug com Multithread: o que muda
Quando você ativa o modo multithread para depuração de APIs REST, o comportamento muda significativamente:
- O VS Code passa a interceptar requisições vindas de diferentes fontes (Smart Client, Web Services, API REST, POUI, chamadas via HTTP, etc.);
- Ao atingir um breakpoint, o App Server pode congelar o processamento de vários threads, o que faz com que o sistema inteiro aparente “travar” — inclusive usuários já logados;
- Para retomar o sistema, é preciso avançar/continuar a execução nos breakpoints; cada liberação permite que a requisição completa e o App Server prossigam.
Ou seja: o multithread permite interceptar requisições API externas, mas exige cuidado porque pode impactar todos os usuários conectados.
Configurando o VS Code para debugar APIs REST
Segue o passo a passo prático para configurar seu VS Code:
- Acesse a aba de Depuração/Debug e clique no ícone da engrenagem;
- Escolha a opção de configuração: Depuração do idioma TOTVS via web app (ou equivalente do seu launcher);
- No JSON de launch, na última linha do objeto de configuração, adicione uma vírgula e inclua a tag para ativar o multithread.
“enableMultiThread”: true
Dicas:
- Renomeie o “name” para algo descritivo como webdebug-rest, facilitando alternar entre configurações;
- Salve o arquivo e verifique se o VS Code mostra a nova configuração no seletor de execução/depuração.
Ajuste necessário no appserver.ini
Para depurar com exclusividade e evitar usuários “travados” ao iniciar a depuração, edite o appserver REST correspondente e, na seção [general], ative a chave:
buildkillusers = 1
Essa chave força a desconexão de usuários presentes quando o App Server inicia, garantindo um ambiente exclusivo para depuração. Use com extremo cuidado — idealmente em ambiente de desenvolvimento ou homologação, nunca em produção sem planejamento.
Testando: Thunder Client e uma requisição API
Com o webdebug-rest selecionado e o App Server rodando, faça um teste HTTP (eu uso o Thunder Client no VS Code):
- Crie a requisição para o endpoint da sua API;
- Envie (Send) e observe o VS Code atingir o breakpoint configurado;
- Enquanto estiver nos breakpoints com multithread habilitado, o sistema pode não responder a logins ou outras ações até que você avance os pontos de parada;
- Use os controles do depurador (Step Over / Continue) para avançar e liberar a execução.
Ao avançar por todos os breakpoints, o login/ação congelada volta ao normal e a requisição conclui.
Depuração via aplicação POUI
O mesmo fluxo vale para aplicações POUI: ao salvar um formulário que faça chamada ao backend, o App Server intercepta e o VS Code para na linha configurada. O comportamento de congelamento também se aplica enquanto o multithread estiver ativo.
Boas práticas e recomendações
- Realize depuração com multithread apenas em ambientes de desenvolvimento/homologação;
- Comunique a equipe antes de ativar buildkillusers, pois será necessário desconectar usuários;
- Use breakpoints pontuais e específicos — evite pontos de parada genéricos que interrompam múltiplas requisições;
- Se precisar inspecionar múltiplas requisições concorrentes, documente o fluxo e seqüencie as execuções para não perder o controle;
- Tenha sempre backups e um ambiente de testes que reproduza a produção para validar correções após depuração.
Conclusão
Debugar APIs REST no Protheus com VS Code é uma habilidade que aumenta muito sua produtividade e precisão na correção de erros. O modo clássico permite depuração sem impactar outras sessões, enquanto o multithread é ideal para interceptar chamadas externas (API, webservices, POUI) — porém exige cuidado porque pode congelar o sistema e os usuários. Configure corretamente o launch do VS Code e o appserver.ini, teste com ferramentas como Thunder Client e siga as boas práticas para garantir segurança e eficiência.
Considerações Finais
Esta aula foi uma breve explicação de como Depurar/Debugar APIs no TOTVS Protheus, para conferir o processo completo de forma prática sugerimos que assista o vídeo no início da página.
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.
Sobre nós:
A RFB Sistemas é uma consultoria e escola há mais de 15 anos no mercado e já atuamos em diferentes setores e portes de empresas ajudando a implantar a melhor solução para gerenciar os seus negócios, o que possibilita que sua empresa consiga tomar decisões mais rápidas, assertivas e claro otimizando resultados. Além disso já capacitamos mais de 1.600 profissionais a utilizarem as ferramentas, como: TOTVS Protheus e RM, Microsoft Power BI e Excel
