Comparativo

HyperSync × WSRESTFUL: como criar webservices REST no Protheus

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

Como nasce
WSRESTFULUm fonte ADVPL ou TLPP com a classe WSRESTFUL e um método por verbo.
HyperSyncUm endpoint no configurador, em 6 passos: direção, tipo, execução, configuração, autorização e sandbox.
Compilação e patch
WSRESTFULCompilar e aplicar o patch no RPO de cada ambiente.
HyperSyncNenhum. O endpoint configurado já é o webservice de produção.
Mudar um campo ou um filtro
WSRESTFULAlterar o fonte, compilar e aplicar de novo.
HyperSyncEditar o endpoint no configurador.
Rota
WSRESTFULUma por serviço, definida no fonte.
HyperSyncUma para todos: POST /api/v1/hypersync/execute, com o código do endpoint no corpo.
Campos devolvidos
WSRESTFULOs que o fonte monta no JSON.
HyperSyncOs que quem chama pede em "fields", como no GraphQL.
Autenticação
WSRESTFULA do REST do Protheus.
HyperSyncA mesma: o login do REST do próprio Protheus.
Quem pode chamar
WSRESTFULO que o fonte e a configuração do REST controlarem.
HyperSyncLista de usuários do Protheus autorizados, endpoint por endpoint.
Gravação
WSRESTFULO fonte chama a rotina automática ou grava na tabela e trata o retorno.
HyperSyncTipo ExecAuto, pela rotina padrão e com as validações dela, ou RecLock, direto na tabela.
Volume
WSRESTFULFila, protocolo e aviso de término ficam por conta do fonte.
HyperSyncExecução assíncrona: entra na fila, devolve um protocolo e avisa por webhook quando termina.
Auditoria
WSRESTFULO log que o fonte gravar.
HyperSyncCada execução registrada: quem chamou, empresa e filial, entrada, retorno e tempo.
Para quem vai integrar
WSRESTFULExemplos de chamada preparados pelo time.
HyperSyncO sandbox testa e gera o cURL e a collection do Postman.
Banco e arquivo agendados
WSRESTFULOutro fonte, agendado no Schedule.
HyperSyncTipos Banco de Dados e Arquivo (CSV ou TXT no FTP), pelo Schedule do Protheus.
Regra de negócio própria
WSRESTFULQualquer uma, em código.
HyperSyncTipo 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
1
Direção
Saída
2
Tipo
Query SQL
3
Execução
Síncrona
4
Configuração
O SELECT na SA1 com os campos que podem sair
5
Autorização
O usuário do CRM
6
Sandbox
Testa e gera o cURL

O CRM chama:

POST /api/v1/hypersync/execute
Authorization: Bearer <token do REST do Protheus>

{
  "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?+
Para consultar e gravar dados do Protheus por API, o HyperSync entrega o webservice sem fonte: você configura, testa no sandbox e ele já está em produção, sem compilar nem aplicar patch no RPO. WSRESTFUL continua fazendo sentido quando a regra de negócio é toda própria, e mesmo aí ela pode virar uma função ADVPL chamada pelo tipo Customizado do HyperSync.
O HyperSync substitui o REST do Protheus?+
Não. Ele usa a autenticação do REST do próprio Protheus, e os webservices WSRESTFUL que vocês já têm continuam funcionando.
Posso usar os dois ao mesmo tempo?+
Sim. Dá para levar as integrações novas para o HyperSync e manter os WSRESTFUL que já existem até a hora de trocar.
Preciso saber ADVPL para usar o HyperSync?+
Não para consultar e gravar. A consulta é um SELECT e a gravação usa a rotina automática padrão (ExecAuto) ou grava direto na tabela (RecLock). ADVPL só entra no tipo Customizado, quando há regra de negócio própria.
Como um sistema chama o endpoint do HyperSync?+
Com um POST em /api/v1/hypersync/execute, autenticado pelo REST do Protheus. O código do endpoint vai no campo id do corpo e, na consulta, o corpo também diz quais campos devolver.
Quem instala o HyperSync?+
A engenharia da HSB, uma vez por ambiente. Depois disso, cada webservice novo é só configuração.

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.

Ver a demonstraçãoComeçar grátis