HyperSync × WSRESTFUL: como criar webservices REST no Protheus
Por Cesar Ramalho (abre em nova aba), HSB Consultoria · Atualizado em
Com WSRESTFUL, cada webservice é um fonte ADVPL ou TLPP que alguém escreve, compila e aplica no RPO. Com o HyperSync, você configura o endpoint e ele já é o webservice de produção, sem fonte, sem compilação e sem patch.
- Os dois usam a autenticação do REST do próprio Protheus.
- Os WSRESTFUL que vocês já têm continuam funcionando.
- Regra de negócio própria continua em ADVPL, chamada pelo HyperSync.
Lado a lado
| Tema | WSRESTFUL | HyperSync |
|---|---|---|
| Como nasce | Um fonte ADVPL ou TLPP com a classe WSRESTFUL e um método por verbo. | Um endpoint no configurador, em 6 passos: direção, tipo, execução, configuração, autorização e sandbox. |
| Compilação e patch | Compilar e aplicar o patch no RPO de cada ambiente. | Nenhum. O endpoint configurado já é o webservice de produção. |
| Mudar um campo ou um filtro | Alterar o fonte, compilar e aplicar de novo. | Editar o endpoint no configurador. |
| Rota | Uma por serviço, definida no fonte. | Uma para todos: POST /api/v1/hypersync/execute, com o código do endpoint no corpo. |
| Campos devolvidos | Os que o fonte monta no JSON. | Os que quem chama pede em "fields", como no GraphQL. |
| Autenticação | A do REST do Protheus. | A mesma: o login do REST do próprio Protheus. |
| Quem pode chamar | O que o fonte e a configuração do REST controlarem. | Lista de usuários do Protheus autorizados, endpoint por endpoint. |
| Gravação | O fonte chama a rotina automática ou grava na tabela e trata o retorno. | Tipo ExecAuto, pela rotina padrão e com as validações dela, ou RecLock, direto na tabela. |
| Volume | Fila, protocolo e aviso de término ficam por conta do fonte. | Execução assíncrona: entra na fila, devolve um protocolo e avisa por webhook quando termina. |
| Auditoria | O log que o fonte gravar. | Cada execução registrada: quem chamou, empresa e filial, entrada, retorno e tempo. |
| Para quem vai integrar | Exemplos de chamada preparados pelo time. | O sandbox testa e gera o cURL e a collection do Postman. |
| Banco e arquivo agendados | Outro fonte, agendado no Schedule. | Tipos Banco de Dados e Arquivo (CSV ou TXT no FTP), pelo Schedule do Protheus. |
| Regra de negócio própria | Qualquer uma, em código. | Tipo Customizado: o endpoint chama uma função ADVPL de vocês. |
O mesmo webservice, das duas formas
O CRM precisa dos clientes de um estado, com código, nome e UF da SA1.
Com WSRESTFUL
clientes.prw · simplificado#include "totvs.ch"
#include "restful.ch"
WSRESTFUL clientes DESCRIPTION "Clientes por estado"
WSDATA estado AS STRING
WSMETHOD GET DESCRIPTION "Lista os clientes" WSSYNTAX "/clientes?estado=SP"
END WSRESTFUL
WSMETHOD GET WSRECEIVE estado WSSERVICE clientes
Local cAlias := GetNextAlias()
Local cUF := Self:estado
Local aLista := {}
Local oItem
Local oResp := JsonObject():New()
BeginSql Alias cAlias
SELECT A1_COD, A1_NOME, A1_EST
FROM %table:SA1% SA1
WHERE A1_EST = %exp:cUF% AND SA1.%notDel%
EndSql
While !(cAlias)->(EoF())
oItem := JsonObject():New()
oItem["a1_cod"] := AllTrim((cAlias)->A1_COD)
oItem["a1_nome"] := AllTrim((cAlias)->A1_NOME)
oItem["a1_est"] := (cAlias)->A1_EST
aAdd(aLista, oItem)
(cAlias)->(DbSkip())
EndDo
(cAlias)->(DbCloseArea())
oResp["result"] := aLista
::SetContentType("application/json")
::SetResponse(oResp:ToJson())
Return .T.Depois: compilar, aplicar o patch no RPO de cada ambiente e testar. Paginação, tratamento de erro e log também entram no fonte.
Com o HyperSync
configuração- 1Direção
- Saída
- 2Tipo
- Query SQL
- 3Execução
- Síncrona
- 4Configuração
- O SELECT na SA1 com os campos que podem sair
- 5Autorização
- O usuário do CRM
- 6Sandbox
- Testa e gera o cURL
O CRM chama:
POST /api/v1/hypersync/execute
Authorization: Bearer <token do REST do Protheus>
tenantId: 99,01
{
"id": 41,
"data": {
"fields": ["A1_COD", "A1_NOME", "A1_EST"],
"params": "A1_EST = 'SP'"
}
}E recebe só os campos que pediu:
{
"result": [
{ "a1_cod": "000142", "a1_nome": "CLIENTE EXEMPLO LTDA", "a1_est": "SP" }
]
}Configurado, já está em produção. Cada chamada fica na Auditoria.
Quando o ADVPL continua
Regra de negócio que nenhuma rotina padrão cobre
Vira uma função ADVPL de vocês, chamada pelo tipo Customizado. O webservice continua configurado no HyperSync, com autorização, auditoria e sandbox; só a regra é código.
Avisar outro sistema no momento em que um dado muda
O HyperSync não tem gatilho de alteração: quem inicia a chamada é o sistema de fora, ou o Schedule do Protheus nas saídas agendadas. Disparar algo quando um registro muda continua sendo ADVPL, num ponto de entrada.
Os webservices que vocês já têm
Continuam funcionando. Não é preciso migrar tudo de uma vez: as integrações novas podem nascer no HyperSync.
Perguntas frequentes
Vale usar o HyperSync ou fazer WSRESTFUL?+
O HyperSync substitui o REST do Protheus?+
Posso usar os dois ao mesmo tempo?+
Preciso saber ADVPL para usar o HyperSync?+
Como um sistema chama o endpoint do HyperSync?+
Quem instala o HyperSync?+
Veja um webservice do Protheus ficar pronto para produção.
A demonstração monta o endpoint numa conversa, no visual do configurador. Nenhum Protheus real é acessado.