Pular para o conteúdo
Guia

Como criar uma API REST no Protheus sem escrever ADVPL

Por Cesar Ramalho (abre em nova aba), HSB Consultoria · Atualizado em

Para criar uma API REST no Protheus sem ADVPL, você configura o endpoint no HyperSync em 6 passos e ele já é o webservice de produção: sem fonte, sem compilar e sem patch no RPO. Todos os endpoints atendem numa rota só, POST /api/v1/hypersync/execute, autenticados pelo REST do próprio Protheus.

  • Consulta por SQL e gravação pela rotina padrão (ExecAuto) ou direto na tabela (RecLock).
  • Só os usuários do Protheus autorizados chamam, e cada execução fica na Auditoria.
  • ADVPL só entra quando há regra de negócio própria, no tipo Customizado.

Antes de começar

Protheus 12.1.2410 em diante

O HyperSync roda no Protheus do cliente, a partir do release 12.1.2410.

REST do Protheus no ar

A autenticação é a do REST do próprio Protheus: quem integra pega o token com usuário e senha do ERP.

Instalação pela HSB

Uma vez por ambiente. Depois disso, cada endpoint novo é só configuração.

Como a instalação funciona está em Instalação.

Os 6 passos do configurador

Cada integração é um endpoint. Ao final do sexto passo ele já responde em produção.

  1. 1DireçãoEntrada, quando o outro sistema grava no Protheus, ou saída, quando ele lê do Protheus ou o Protheus exporta.
  2. 2Tipo de processamentoNa saída: Query SQL (devolve JSON na chamada), Banco de Dados (grava em SQL Server, PostgreSQL ou Oracle) ou Arquivo (CSV ou TXT no FTP). Na entrada: ExecAuto, pela rotina automática padrão, ou RecLock, direto na tabela. Há ainda o Customizado, que chama uma função ADVPL de vocês.
  3. 3Tipo de execuçãoSíncrona, que responde na mesma chamada, ou assíncrona, que entra na fila e devolve um ticket. Banco de Dados e Arquivo são sempre assíncronos e rodam pelo Schedule do Protheus.
  4. 4ConfiguraçãoA consulta SQL, com os campos que podem sair e se o endpoint aceita filtro. Ou a rotina ExecAuto e as operações permitidas: incluir, alterar, excluir.
  5. 5AutorizaçãoA lista de usuários do Protheus que podem chamar o endpoint. Quem não está na lista recebe 400 sem permissão.
  6. 6SandboxTesta o endpoint e gera o cURL e a collection do Postman para quem vai integrar. Na gravação, o teste roda numa transação desfeita no fim. O tipo Banco de Dados não tem sandbox.

Exemplo 1: consultar clientes na SA1

Um CRM precisa dos clientes de São Paulo, com código, nome e UF.

O endpoint

1Direção
Saída
2Tipo
Query SQL
3Execução
Síncrona
4Configuração
O SELECT na SA1 com código, nome, CNPJ e UF
5Autorização
O usuário do Protheus da integração
6Sandbox
Testa e gera o cURL
  • fields escolhe as colunas entre as que a consulta traz, como no GraphQL.
  • params manda um filtro, uma condição SQL, quando o endpoint permite parâmetros.
  • page e pageSize, dentro de data, paginam. Sem paginação volta tudo o que a consulta trouxer.
  • O endpoint de consulta passa pela trava de SQL: só lê.

A chamada

POST /api/v1/hypersync/execute
Authorization: Bearer <token do REST do Protheus>
tenantId: 99,01
Content-Type: application/json

{
  "id": 41,
  "data": {
    "fields": ["A1_COD", "A1_NOME", "A1_EST"],
    "params": "A1_EST = 'SP'"
  }
}

A resposta traz só os campos pedidos, com os nomes em minúsculas:

{
  "result": [
    { "a1_cod": "000231", "a1_nome": "COMERCIAL ALVORADA LTDA", "a1_est": "SP" },
    { "a1_cod": "000117", "a1_nome": "DISTRIBUIDORA PAULISTA SA", "a1_est": "SP" }
  ]
}

Exemplo 2: gravar um título a pagar por ExecAuto

Um sistema de compras inclui títulos na SE2 pela FINA050. O endpoint é de entrada, tipo ExecAuto, e a rotina valida o título como validaria na tela.

POST /api/v1/hypersync/execute
Authorization: Bearer <token do REST do Protheus>
tenantId: 99,01
Content-Type: application/json

{
  "id": 43,
  "function": "FINA050",
  "action": 3,
  "data": {
    "cabec": {
      "E2_PREFIXO": "BOL",
      "E2_NUM": "000051207",
      "E2_TIPO": "DP",
      "E2_NATUREZ": "202010",
      "E2_FORNECE": "F00012",
      "E2_LOJA": "01",
      "E2_EMISSAO": "20261006",
      "E2_VENCTO": "20261106",
      "E2_VALOR": 1500.00
    }
  }
}

Se a rotina gravou:

{ "successMessage": "Registro incluído via execauto com sucesso!" }
  • function e action ficam fora de data. A action 3 inclui, a 4 altera e a 5 exclui; o endpoint define quais são permitidas.
  • Os campos vão com o nome do Protheus e as datas em AAAAMMDD.
  • Se a rotina recusar, volta errorMessage com a mesma mensagem que o Protheus mostraria na tela.

Rotina com cabeçalho e itens, como o pedido de venda, manda os dois na mesma chamada. O exemplo completo está no guia Como incluir pedido de venda no Protheus por API (MATA410).

O que muda em relação a escrever o fonte

Criar o webservice
Fonte ADVPLEscrever o fonte ADVPL ou TLPP, compilar e aplicar o patch no RPO de cada ambiente.
HyperSyncConfigurar o endpoint nos 6 passos. Não há publicação de serviço nem reinício.
Mudar um campo ou um filtro
Fonte ADVPLAlterar o fonte, compilar e aplicar de novo.
HyperSyncEditar o endpoint no configurador.
Quem pode chamar
Fonte ADVPLO que o fonte e a configuração do REST controlarem.
HyperSyncLista de usuários do Protheus autorizados, endpoint por endpoint.
Log
Fonte ADVPLO que o fonte gravar.
HyperSyncCada execução na Auditoria: quem chamou, empresa e filial, entrada, retorno e tempo.
Entregar para quem integra
Fonte ADVPLExemplos de chamada preparados pelo time.
HyperSyncO cURL e a collection do Postman que o sandbox gera.

O mesmo webservice feito das duas formas, com o fonte WSRESTFUL ao lado, está em HyperSync × WSRESTFUL.

Quando o ADVPL ainda entra

Regra de negócio própria

Vira uma função ADVPL de vocês, chamada pelo tipo Customizado. O endpoint continua no HyperSync, com autorização, auditoria e sandbox; só a regra é código.

Converter campos

Não há de-para: entrada e saída usam os nomes do Protheus, como C5_CLIENTE e A1_COD. A conversão fica com quem chama ou numa função Customizada.

Disparar quando 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. Avisar outro sistema quando um registro muda continua sendo ADVPL.

Perguntas frequentes

Dá para criar uma API REST no Protheus sem escrever ADVPL?+
Sim. Com o HyperSync, instalado pela HSB no Protheus a partir do release 12.1.2410, você configura o endpoint em 6 passos e ele já é o webservice de produção. 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.
Preciso compilar ou aplicar patch no RPO para publicar o endpoint?+
Não. Configurado, o endpoint já responde na rota única POST /api/v1/hypersync/execute. Não há fonte para compilar, patch no RPO, publicação de serviço nem reinício.
Como fica a autenticação da API?+
É a do REST do próprio Protheus: quem integra pega um token com usuário e senha do ERP e chama com Authorization: Bearer. Além disso, o usuário precisa estar na lista de autorizados do endpoint; senão a chamada volta 400 sem permissão. Empresa e filial vão no header tenantId, por exemplo 99,01.
Quais tabelas e rotinas posso usar?+
Qualquer tabela do Protheus, numa consulta SQL que também pode juntar tabelas, e qualquer rotina que aceite ExecAuto, como a MATA410 (pedido de venda) e a FINA050 (títulos a pagar). Para gravar direto na tabela, há o RecLock. Os campos entram e saem com o nome do Protheus: não há de-para.
O endpoint criado em homologação vai sozinho para produção?+
Não. Cada ambiente do Protheus tem os seus endpoints, e não há cópia automática de um para o outro. Como não há fonte, também não há patch para levar: o endpoint é configurado no ambiente de produção.
A consulta pode alterar dados do Protheus?+
Não. Os endpoints de consulta passam por uma trava de SQL e só leem. Para gravar existem os tipos de entrada, ExecAuto e RecLock, e cada endpoint tem a sua lista de usuários autorizados.

Veja um endpoint do Protheus ficar pronto sem uma linha de ADVPL.

A demonstração monta o endpoint numa conversa, no visual do configurador. Nenhum Protheus real é acessado.

Ver a demonstraçãoComeçar grátis