Guia

Como incluir pedido de venda no Protheus por API (MATA410)

Por Cesar Ramalho (abre em nova aba), HSB Consultoria · Atualizado em 6 de outubro de 2026

Para incluir um pedido de venda no Protheus por API com o HyperSync, o sistema de fora faz um POST no endpoint ExecAuto da MATA410, com o cabeçalho (SC5) e os itens (SC6) na mesma chamada. A rotina padrão valida o pedido como validaria na tela, e o retorno diz que gravou ou traz a mensagem de erro da própria rotina.

Sem fonte ADVPL: o endpoint é configurado no HyperSync e já está em produção.
Síncrono para resposta na hora; assíncrono, com ticket, para picos de pedidos.
Campos com o nome do Protheus: C5_CLIENTE, C6_PRODUTO, C6_QTDVEN.

O endpoint e a chamada completa

O endpoint sai dos 6 passos do configurador. Quem chama usa a rota única do HyperSync, com o token do REST do Protheus e a empresa e filial no header tenantId.

O endpoint

1Direção: Entrada
2Tipo: ExecAuto
3Execução: Síncrona, ou assíncrona para picos
4Configuração: Rotina MATA410, com a inclusão permitida
5Autorização: O usuário do Protheus da integração
6Sandbox: Testa sem gravar e gera o cURL

Os 6 passos estão explicados em Como criar uma API REST no Protheus sem escrever ADVPL.

A chamada

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

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

O que vai no corpo

function: A rotina: MATA410. Fica fora de data.
action: 3 inclui, 4 altera, 5 exclui. O endpoint define quais são permitidas.
data.cabec: Os campos da SC5. O C5_NUM pode ficar de fora: a rotina numera o pedido.
C5_CLIENTE e C5_LOJACLI: Código e loja de um cliente que já existe na SA1.
C5_CONDPAG: A condição de pagamento cadastrada no Protheus.
data.itens: Uma linha por item da SC6: produto da SB1, quantidade, preço e TES.
Datas: Em AAAAMMDD, como 20261013.

Os campos obrigatórios são os do dicionário do seu ambiente: o que a tela da MATA410 exige, a chamada também exige. Não há de-para; os nomes são os do Protheus.

A resposta: gravou ou a rotina recusou

Sucesso

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

A execução fica na Auditoria: quem chamou, empresa e filial, entrada, retorno e tempo.

Erro de validação da rotina

{
  "errorMessage": "<a mensagem da MATA410, a mesma que o Protheus mostraria na tela>"
}

O errorMessage traz a mesma mensagem que o Protheus mostraria na tela. Um C5_CLIENTE que não existe na SA1, por exemplo, volta aqui com a recusa da própria rotina.

Antes de a rotina rodar, a chamada volta 400 quando falta o id, quando o endpoint não existe ou está inativo e quando o usuário não está na lista de autorizados.

Síncrono ou assíncrono

No síncrono, a resposta acima volta na mesma chamada. Quando os pedidos chegam em pico e quem chama não precisa esperar, o endpoint pode ser assíncrono: a chamada entra na fila e responde na hora com um ticket.

1. Resposta na hora

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

2. Resultado depois

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

Volta 404 se o ticket não existe. O resultado também fica na Auditoria, com o status Pendente até terminar e Concluído depois.

3. Aviso ao concluir

Opcional: o Protheus chama um conector de webhook (POST, PUT ou PATCH) sempre, só no sucesso ou só no erro. O corpo é montado com variáveis da execução: ticket, status, endpoint, empresa e filial, quem chamou, duração e retorno.

O modo assíncrono é o que roda no pipeline da Disney, com mais de 10 milhões de integrações por mês. Ver o case.

O cliente já precisa estar na SA1

O pedido só aponta o código e a loja do cliente em C5_CLIENTE e C5_LOJACLI. Se quem vende só conhece o CNPJ, um endpoint Query SQL na SA1 devolve o código antes de mandar o pedido.

Consulta pelo CNPJ:

{
  "id": 44,
  "data": {
    "fields": ["A1_COD", "A1_LOJA"],
    "params": "A1_CGC = '12345678000190'"
  }
}

Resposta:

{ "result": [ { "a1_cod": "000231", "a1_loja": "01" } ] }

Se não vier nada, o cliente é cadastrado antes por um endpoint de entrada (ExecAuto ou RecLock) e o pedido vai em seguida. Quem orquestra essa sequência é o sistema que chama.

Quem chama o endpoint

Loja virtual ou sistema próprio

Faz o POST direto, com o token do REST do Protheus de um usuário autorizado no endpoint.

Marketplace

A própria plataforma ou um middleware de vocês converte o pedido para os campos do Protheus e chama o endpoint.

Middleware

Recebe o aviso da loja ou do marketplace, consulta a SA1, monta o cabec e os itens e faz a chamada da MATA410.

Não há conector pronto por marca: Shopify, VTEX e Mercado Livre são exemplos de quem chama. O HyperSync também não recebe webhook de outro sistema. Mais sobre isso em Integrar o Protheus a e-commerce e marketplace.

Perguntas frequentes

Dá para mandar o cabeçalho e os itens do pedido na mesma chamada?+

Sim. O endpoint ExecAuto da MATA410 recebe o cabeçalho da SC5 em data.cabec e os itens da SC6 em data.itens, no mesmo POST. O pedido inteiro entra numa chamada só, na empresa e filial do header tenantId.

O pedido incluído por API passa pelas validações da MATA410?+

Sim. O tipo ExecAuto grava pela rotina automática padrão, com as validações da própria rotina. Se algo não passa, o retorno é um errorMessage com a mesma mensagem que o Protheus mostraria na tela.

O que acontece se o cliente do pedido não existir na SA1?+

A MATA410 recusa o pedido e a chamada volta um errorMessage com a mensagem da rotina. O pedido só referencia o código e a loja do cliente; quem chama consulta a SA1 antes, por exemplo pelo CNPJ com um endpoint Query SQL, e cadastra o cliente quando ele ainda não existe.

Consigo testar a inclusão do pedido sem gravar de verdade?+

Sim. O sandbox do configurador roda a gravação numa transação desfeita no fim, então nada fica gravado. Ele também gera o cURL e a collection do Postman. Em produção, a mesma chamada grava.

Quando usar o modo assíncrono para pedidos de venda?+

Quando chegam muitos pedidos de uma vez e quem chama não precisa da resposta na mesma chamada. A chamada responde na hora com um ticket, o resultado sai em GET v1/hypersync/getresponse?ticket=<ticket> e fica na Auditoria. Se quiser, o Protheus avisa um webhook quando a execução termina.

O HyperSync tem conector pronto para Shopify, VTEX ou Mercado Livre?+

Não. Não há conector por marca: a própria plataforma ou um middleware de vocês faz o POST no endpoint, com os campos no nome do Protheus. O HyperSync também não recebe webhook de outro sistema; quem recebe o aviso do marketplace e chama o endpoint é o middleware.

Veja o endpoint de pedido de venda ficar pronto para produção.

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

Ver a demonstração Começar grátis