Pular para o conteúdo
Documentação

Documentação da chamada do HyperSync

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

Todo endpoint do HyperSync é chamado pela mesma rota, POST /api/v1/hypersync/execute, com o código do endpoint no campo id do corpo. A autenticação é o token Bearer do REST do próprio Protheus, e a empresa e a filial vão no header tenantId. O que muda de um tipo para outro é o resto do corpo e a resposta.

  • O endpoint configurado já é o webservice de produção: sem fonte ADVPL, sem compilar, sem patch no RPO.
  • O sandbox de cada endpoint gera o cURL e a collection do Postman com a chamada pronta.
  • Entrada e saída usam os nomes de campo do Protheus: não há de-para.

Autenticação e headers

Quem integra pega um token no REST do próprio Protheus (o OAuth2 do Protheus, com usuário e senha do ERP) e manda em Authorization: Bearer. Validade e renovação do token seguem o REST do Protheus. Além do token, o usuário precisa estar na lista de autorizados do endpoint, definida no passo de autorização do configurador.

Toda chamada:

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

Headers:

Authorization
Bearer com o token do REST do próprio Protheus.
tenantId
Empresa e filial em que a chamada roda, separadas por vírgula (ex.: 99,01).
Content-Type
application/json: o corpo é sempre JSON.

A URL base é a do backend do HyperSync no ambiente de vocês; o cURL que o sandbox gera já traz a URL completa. Cada ambiente do Protheus (homologação, produção) tem os seus endpoints, sem cópia automática de um para o outro.

Rota única

Não existe URL por endpoint. Todos usam POST /api/v1/hypersync/execute, e o campo id do corpo diz qual endpoint executar. Antes de executar, a chamada volta 400 se faltar o id, se o endpoint não existir ou estiver inativo, ou se o usuário não estiver na lista de autorizados.

Query SQL
Síncrona ou assíncrona
Saída
data.fields, data.params, data.page, data.pageSize
{"result": [...]}, campos em minúsculas
ExecAuto
Síncrona ou assíncrona
Entrada
function, action, data.cabec, data.itens
{"successMessage": ...} ou {"errorMessage": ...}
RecLock
Síncrona ou assíncrona
Entrada
table, operation, fields, chave, indice
Vista no teste do sandbox
Customizado
Síncrona ou assíncrona
Entrada ou saída
Definido pela função ADVPL de vocês
Definida pela função
Banco de Dados
Sempre assíncrona, pelo Schedule
Saída
Só o id, enviado pelo Schedule
Resumo de registros atualizados, inseridos e erros
Arquivo
Sempre assíncrona, pelo Schedule
Saída
data, separator, extension, header
Caminho do arquivo gerado

Query SQL

Saída: devolve o resultado da consulta do endpoint na própria chamada. O corpo diz quais campos voltam, como no GraphQL, e o filtro. A resposta traz os nomes de campo em minúsculas. A trava de SQL garante que o endpoint de consulta só lê: para gravar, os tipos são ExecAuto e RecLock.

Corpo:

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

Resposta:

{
  "result": [
    { "a1_cod": "000231", "a1_nome": "COMERCIAL ALVORADA LTDA", "a1_est": "SP" },
    { "a1_cod": "000117", "a1_nome": "DISTRIBUIDORA PAULISTA SA", "a1_est": "SP" }
  ]
}
id
Código do endpoint.
data.fields
As colunas que devem voltar, entre as que a consulta do endpoint traz.
data.params
Filtro, como condição SQL. Só vale quando o endpoint permite parâmetros.
data.page
Página pedida.
data.pageSize
Registros por página. Sem paginação, volta tudo o que a consulta trouxer: o limite vem da própria consulta.

ExecAuto

Entrada: grava pela rotina automática padrão do Protheus, com as validações da própria rotina. Cabeçalho e itens vão na mesma chamada. Datas em AAAAMMDD. No pedido de venda, o C5_NUM fica de fora: a rotina numera.

Corpo (pedido de venda pela MATA410, simplificado):

{
  "id": 42,
  "function": "MATA410",
  "action": 3,
  "data": {
    "cabec": {
      "C5_CLIENTE": "000231",
      "C5_LOJACLI": "01",
      "C5_EMISSAO": "20261013",
      "C5_CONDPAG": "001"
    },
    "itens": [
      { "C6_PRODUTO": "PA-00102", "C6_QTDVEN": 2, "C6_PRCVEN": 899.9, "C6_TES": "501" }
    ]
  }
}

Resposta quando grava:

{
  "successMessage": "Registro incluído via execauto com sucesso!"
}

Resposta quando a rotina recusa (FINA050 com natureza inválida, abreviada):

{
  "errorMessage": "AJUDA:E2_NATUREZ\n...\nNatureza - E2_NATUREZ := DINHEIRO < -- Invalido\n...\nFalha na gravação automática do Titulo!"
}
id
Código do endpoint.
function
A rotina automática: MATA410 (pedido de venda), FINA050 (títulos a pagar) e outras. Fica fora de data.
action
3 inclui, 4 altera, 5 exclui. O endpoint define quais operações são permitidas. Fica fora de data.
data.cabec
Campos do cabeçalho, com os nomes do Protheus.
data.itens
Lista de itens, quando a rotina tem detalhe. Na MATA410, os itens da SC6, na mesma chamada do cabeçalho.

O passo a passo do pedido de venda está em Pedido de venda no Protheus por API (MATA410).

RecLock

Entrada: grava direto na tabela, sem passar pela rotina padrão, então as validações da rotina não rodam. Quando a regra da rotina importa, use ExecAuto. O sandbox do configurador traz este modelo de corpo, e o teste nele mostra o retorno.

Corpo de inclusão (operation 3):

{
  "id": 43,
  "table": "SA1",
  "operation": 3,
  "fields": {
    "A1_COD": "000142",
    "A1_LOJA": "01",
    "A1_NOME": "CLIENTE EXEMPLO LTDA",
    "A1_PESSOA": "J"
  }
}

Corpo de alteração (operation 4, com chave e índice):

{
  "id": 43,
  "table": "SA1",
  "operation": 4,
  "fields": { "A1_NOME": "CLIENTE EXEMPLO COMERCIO LTDA" },
  "chave": "  00014201",
  "indice": 1
}
id
Código do endpoint.
table
A tabela que recebe o registro.
operation
3 inclui, 4 altera, 5 exclui.
fields
Os campos gravados, com os nomes do Protheus.
chave
Obrigatória em 4 e 5. Os valores na sequência do índice, como no DbSeek: no índice 1 da SA1, filial, código e loja, cada um no tamanho do campo.
indice
Obrigatório em 4 e 5. O número do índice da tabela usado no DbSeek.

Customizado

O endpoint chama uma função ADVPL de vocês, para a regra de negócio que nenhuma rotina padrão cobre. A chamada usa a mesma rota, com o código do endpoint em id; o que mais vai no corpo e o que volta são definidos pela função. É o único tipo que envolve ADVPL. O endpoint continua no configurador, com autorização e auditoria como os outros.

Banco de Dados e Arquivo

Os dois são saída, sempre assíncronos, e rodam pelo Schedule do Protheus, na frequência que vocês configurarem. A origem é uma consulta SQL, e o destino é o banco ou o FTP de vocês. O resultado de cada execução fica na Auditoria.

Banco de Dados

Grava o resultado da consulta em SQL Server, PostgreSQL ou Oracle. Cria a tabela de destino se ela não existir e atualiza ou insere pela chave escolhida. O tipo Banco de Dados não tem sandbox.

O que o Schedule envia (o código do endpoint, e mais nada):

{ "id": "000045" }

Resultado:

{
  "result": "Registros atualizados: 0 | Registros inseridos: 3 | Erros: 0"
}

Arquivo

Gera um arquivo CSV ou TXT com separador a partir da consulta e envia para o FTP. O HyperSync não gera CNAB nem outro layout bancário.

Corpo da execução:

{
  "id": 44,
  "data": {
    "fields": ["C5_NUM", "C5_CLIENTE", "C5_EMISSAO", "C5_CONDPAG"],
    "params": ""
  },
  "separator": ";",
  "extension": "csv",
  "header": true
}

Resultado (caminho do arquivo gerado):

{
  "result": "\\hypersync\\44\\20261013142207.csv"
}
data.fields / data.params
Os mesmos da Query SQL: colunas e filtro da consulta.
separator
Separador: pipe, vírgula, ponto e vírgula ou tab.
extension
csv ou txt.
header
true para a primeira linha levar o nome das colunas.

Execução assíncrona

Na execução assíncrona, a chamada entra na fila e responde na hora com um ticket. O resultado sai depois em GET v1/hypersync/getresponse?ticket=<ticket> e fica na Auditoria. Ticket que não existe volta 404. Query SQL, ExecAuto, RecLock e Customizado podem ser síncronos ou assíncronos, escolha feita no passo 3 do configurador; Banco de Dados e Arquivo são sempre assíncronos.

Resposta da chamada:

{
  "ticket": "3f6c1e9a-7b2d-4c58-9a41-0d2e8f5b6c17"
}

Consulta do resultado:

GET v1/hypersync/getresponse?ticket=3f6c1e9a-7b2d-4c58-9a41-0d2e8f5b6c17

O serviço de filas do assíncrono só organiza a ordem de execução (o ticket), sem dado nenhum: a execução e os dados ficam no Protheus.

Webhook ao concluir

Opcional, para endpoint assíncrono. Quando a execução termina, o Protheus chama um conector de webhook cadastrado por vocês. É só o aviso de término: o HyperSync não dispara quando um dado muda no Protheus e não recebe webhook de outro sistema.

Configuração do aviso:

Método
POST, PUT ou PATCH.
Quando
Sempre, só no sucesso ou só no erro.
Corpo
Montado por vocês com as variáveis da execução, abaixo.

Variáveis da execução para montar o corpo:

ticket
O protocolo da execução, o mesmo que a chamada devolveu.
status
A situação da execução quando o aviso sai.
endpoint
O endpoint executado.
empresa e filial
As do header tenantId da chamada.
quem chamou
O usuário do Protheus que fez a chamada.
duração
Quanto a execução levou.
retorno
A saída da execução: o resultado ou a mensagem de erro.

Status e Auditoria

O motor grava só dois status de execução. Cada execução, síncrona ou assíncrona, fica registrada na Auditoria. O painel não tem botão de reprocessar.

Status:

Pendente
A execução entrou e ainda não terminou.
Concluído
A execução terminou. Se a rotina recusou a gravação, a mensagem de erro está no retorno.

O que a Auditoria registra de cada execução:

  • Usuário do Protheus que chamou
  • Empresa e filial
  • Entrada na fila, início, fim e duração
  • Status
  • Entrada (o corpo recebido)
  • Saída (o retorno)

Erros conhecidos

O corpo não tem o id
400, antes de executar.
O endpoint não existe ou está inativo
400, antes de executar.
O usuário do token não está na lista de autorizados do endpoint
400 sem permissão, antes de executar.
A consulta tem erro de SQL
Erro de Sintaxe, com o log do banco.
A rotina do ExecAuto recusou a gravação (validação da rotina)
errorMessage, com a mesma mensagem que o Protheus mostraria na tela.
O ticket consultado em getresponse não existe
404.

Tempo limite da chamada, tamanho máximo do corpo, número máximo de itens, nova tentativa e como evitar duplicidade: a HSB confirma para o ambiente de vocês.

Perguntas frequentes

Por que a consulta também é POST?+
Porque o corpo leva o código do endpoint e, na consulta, os campos que devem voltar, o filtro e a paginação. Como no GraphQL, quem chama diz o que quer receber, e a resposta traz só esses campos.
Cada endpoint tem uma URL própria?+
Não. Todos usam POST /api/v1/hypersync/execute, e o campo id do corpo diz qual endpoint executar. Um endpoint novo não muda a URL de quem já integra.
Onde pego o token para chamar o HyperSync?+
No REST do próprio Protheus, pelo OAuth2 do Protheus, com usuário e senha do ERP. O token vai em Authorization: Bearer, e o usuário também precisa estar na lista de autorizados do endpoint; senão a chamada volta 400 sem permissão.
Como digo em qual empresa e filial a chamada roda?+
No header tenantId, com empresa e filial separadas por vírgula, por exemplo 99,01. Uma instalação atende várias empresas e filiais, e cada execução registra as duas na Auditoria.
O sandbox grava de verdade?+
Não. O sandbox testa a gravação numa transação desfeita no fim e gera o cURL e a collection do Postman. Em produção, a mesma chamada grava de verdade. O tipo Banco de Dados não tem sandbox.
Posso mandar os campos com outros nomes, como cliente em vez de C5_CLIENTE?+
Não. Não há de-para de campos: entrada e saída usam os nomes do Protheus. A conversão fica com quem chama, ou numa função do tipo Customizado.

Mais respostas, de produto a planos, em Perguntas frequentes sobre o HyperSync.

Veja a chamada pronta de um endpoint.

A demonstração monta o endpoint numa conversa, no visual do configurador, com a chamada que vai para quem integra. Nenhum Protheus real é acessado.

Ver a demonstraçãoComeçar grátis