rev1-2026-05-07 Protheus 12.1.2210 · build 240223P

ComissaoVendas

CRUD de comissões de vendas (tabela SE3) via rotina automática MATA490 (modelo 1, array plano de campos). A chave externa é a chave composta do índice 3 da SE3 — vendedor, cliente, loja, prefixo, número e parcela do título — passada como string única separada por | no path.

Bloqueio TOTVS: tabela SE3 — comissoes de pedido, sem padrao MSBLQL nesta base.

Base URL https://erpapi.jetme.com.br/api/99/01 Empresa 99 · Filial 01

Vinculação com o ERP

Tabela mestre SE3 Comissões de vendas (títulos)

Rotina automática MATA490 Modelo 1 · array plano

Wrapper AdvPL U_MT490Exc src/lib/MT490EXC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Chave composta · índice 3 da SE3

VEND + CODCLI + LOJA + PREFIXO + NUM + PARCELA

campos E3_VEND + E3_CODCLI + E3_LOJA + E3_PREFIXO + E3_NUM + E3_PARCELA
cada componente é re-padded com PadR para o tamanho do SX3 antes de qualquer DbSeek.

Cadastro · pré-requisito

Vendedor (SA3) e Cliente (SA1)

E3_VEND deve existir em SA3 · E3_CODCLI/E3_LOJA em SA1
o MsExecAuto do MATA490 rejeita chave técnica inexistente

Título de origem · pré-requisito

Título em SE1 (Contas a Receber)

par E3_PREFIXO/E3_NUM/E3_PARCELA deve corresponder a um título em SE1
campo de moeda E3_MOEDA herda da tabela SM2 de cotações

Reposicionamento prévio

DbSeek no índice 3 antes do MATA490

PUT e DELETE reposicionam SE3 em DbSetOrder(3) com PadR em cada componente
pré-requisito da rotina automática — sem reposicionamento, o MATA490 retorna registro inexistente

Convenções

Chave composta no path. Todas as rotas /WsComVnd/... recebem a chave única no formato VEND|CODCLI|LOJA|PREFIXO|NUM|PARCELA. O separador | é URL-encoded como %7C em clientes HTTP que não toleram o caractere bruto. Componentes ausentes não são aceitos — todos os 6 segmentos são obrigatórios.

Operações verbose no path. Diferente do padrão CRUD por verbo puro, este endpoint usa segmentos explícitos /INCLUIR/{chave}, /ALTERAR/{chave} e /EXCLUIR/{chave} — reflexo direto da rotina automática MATA490 (operações 3/4/5). O verbo HTTP (POST/PUT/DELETE) continua coerente com a semântica REST.

Formato de datas. Campos E3_EMISSAO, E3_DATA e E3_VENCTO aceitam dois formatos: ISO YYYY-MM-DD ou compacto YYYYMMDD. A conversão interna é feita em fStrToDate. Os exemplos do contrato usam ISO; as fixtures de smoke usam compacto.

Campo E3_PROCCOM. Deve refletir a operação: "INCLUSAO" em POST, "ALTERACAO" em PUT. O endpoint não injeta automaticamente — o cliente envia no payload. Quando ausente, o próprio MATA490 aplica default seguro.

Paginação simples. /_list aceita page/pageSize (default 50, máx 500) e filtros por vend (usa o índice 3), codcli, loja, prefixo e num. Não há delta-sync nesta versão.

Comissão

CRUD por chave composta

GET /WsComVnd/{chave} Consulta comissão por chave composta

Descrição

Retorna a comissão posicionando a SE3 no índice 3 (E3_FILIAL + E3_VEND + E3_CODCLI + E3_LOJA + E3_PREFIXO + E3_NUM + E3_PARCELA). Cada componente da chave é re-padded para o tamanho do SX3 antes do DbSeek. Aplica filtro de filial via xFilial("SE3") e respeita o whitelist CAMPOS_GET do .prw.

Path parameter

chave string · path · obrigatório SE3 · índice 3

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsComVnd/000001%7C00000402%7C01%7C001%7C123456789%7C1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Comissão encontrada. Envelope { success: true, data: Comissao }.

400

Chave malformada (componente ausente, separador incorreto). Tier: validation-error.

404

Comissão inexistente para a chave informada. Tier: not-found.

500

Erro interno (DbSeek, serialização). Tier: business-error.

POST /WsComVnd/INCLUIR/{chave} Inclui nova comissão

Descrição

Inclui uma comissão via MATA490 em modo 3 (operação INCLUSAO). Os componentes da chave composta passados no path são autoritativos e sobrescrevem qualquer valor de E3_VEND/E3_CODCLI/E3_LOJA/E3_PREFIXO/E3_NUM/E3_PARCELA presente no payload.

Whitelist de campos: ver ComissaoPayload.
Pré-requisitos cadastrais (SA3, SA1, SE1) — ver bloco "Vinculação com o ERP".
E3_PROCCOM deve refletir a operação: "INCLUSAO" no POST.

Path parameter

chave string · path · obrigatório SE3 · índice 3

Request body

application/json ComissaoPayload · obrigatório

Payload plano com campos do whitelist CAMPOS_ALLOW. Schema completo em ComissaoPayload.

Comissão padrão — payload realista, datas em formato compacto YYYYMMDD. Fixture: fixtures/create.json.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsComVnd/INCLUIR/000001%7C00000402%7C01%7C001%7C123456789%7C1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "E3_EMISSAO": "20260507",
  "E3_SERIE": "UNI",
  "E3_BASE": 1000,
  "E3_PORC": 10,
  "E3_DATA": "20260507",
  "E3_SEQ": "  ",
  "E3_TIPO": "DH",
  "E3_PEDIDO": "TST00001",
  "E3_VENCTO": "20260607",
  "E3_PROCCOM": "INCLUSAO",
  "E3_MOEDA": "01"
}

Mínimo com datas ISO — apenas campos obrigatórios pelo MATA490, datas no formato YYYY-MM-DD.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsComVnd/INCLUIR/000001%7C00000402%7C01%7C001%7C123456790%7C1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "E3_EMISSAO": "2026-05-07",
  "E3_BASE": 500,
  "E3_PORC": 5,
  "E3_DATA": "2026-05-07",
  "E3_VENCTO": "2026-06-07",
  "E3_PROCCOM": "INCLUSAO",
  "E3_MOEDA": "01"
}

Respostas

201

Comissão incluída. Envelope CrudResponse com data = chave composta gravada.

400

Chave malformada ou payload inválido. Tier: validation-error.

409

Comissão já existe para a chave informada. Tier: business-error.

422

Regra de negócio rejeitada pelo MATA490 (vendedor/cliente/título inexistente, moeda inválida, tipo de comissão incompatível). Tier: business-error.

500

Erro interno.

PUT /WsComVnd/ALTERAR/{chave} Altera comissão existente

Descrição

Altera campos da comissão via MATA490 em modo 4 (operação ALTERACAO). O endpoint reposiciona a SE3 no índice 3 antes do MsExecAuto — pré-requisito da rotina automática. Aceita qualquer subconjunto do whitelist CAMPOS_ALLOW, mas os campos da chave (E3_VEND/E3_CODCLI/E3_LOJA/E3_PREFIXO/E3_NUM/E3_PARCELA) no payload são ignorados — a chave vem do path.

E3_PROCCOM: "ALTERACAO" em PUT (ou ausente — MATA490 aplica default).

Path parameter

chave string · path · obrigatório SE3 · índice 3

Request body

application/json ComissaoPayload · obrigatório

Subconjunto do whitelist. Campos da chave no payload são ignorados.

Alteração completa — atualiza base, percentual, vencimento e pedido. Fixture: fixtures/update.json.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsComVnd/ALTERAR/000001%7C00000402%7C01%7C001%7C123456789%7C1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "E3_EMISSAO": "20260507",
  "E3_SERIE": "UNI",
  "E3_BASE": 2000,
  "E3_PORC": 15,
  "E3_DATA": "20260507",
  "E3_TIPO": "DH",
  "E3_PEDIDO": "TST_ALTERADO",
  "E3_VENCTO": "20260707",
  "E3_PROCCOM": "ALTERACAO",
  "E3_MOEDA": "01"
}

Altera apenas valor da base e percentual — payload mínimo de correção. Demais campos preservam valor anterior.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsComVnd/ALTERAR/000001%7C00000402%7C01%7C001%7C123456789%7C1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "E3_BASE": 1500,
  "E3_PORC": 12
}

Respostas

200

Comissão alterada. Envelope CrudResponse.

400

Chave malformada ou payload inválido. Tier: validation-error.

404

Comissão inexistente. Tier: not-found.

422

Regra de negócio rejeitada pelo MATA490 (campo fora do whitelist, enum inválido, alteração não permitida em comissão já paga). Tier: business-error.

500

Erro interno.

DEL /WsComVnd/EXCLUIR/{chave} Exclui comissão

Descrição

Exclui a comissão via MATA490 em modo 5 (operação EXCLUSAO). O endpoint reposiciona a SE3 no índice 3 antes do MsExecAuto. O MATA490 rejeita exclusão de comissões já apropriadas (movimentadas no financeiro) ou vinculadas a títulos liquidados.

Path parameter

chave string · path · obrigatório SE3 · índice 3

Chamada de exemplo

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsComVnd/EXCLUIR/000001%7C00000402%7C01%7C001%7C123456789%7C1
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Comissão excluída. Envelope CrudResponse.

400

Chave malformada. Tier: validation-error.

404

Comissão inexistente. Tier: not-found.

422

Comissão já apropriada / título vinculado liquidado / regra do MATA490 rejeitou. Tier: business-error.

500

Erro interno.

Listagem

Listagem paginada por filtros de chave

GET /WsComVnd/_list Lista comissões com filtros e paginação

Descrição

Lista comissões com filtros por componente da chave composta. vend é o filtro principal (usa o índice 3 da SE3 com seek); codcli, loja, prefixo e num refinam o seek progressivamente. Paginação simples via page/pageSize.

Query parameters

vend string · query · opcional SE3.E3_VEND

Código do vendedor (filtro principal — usa o índice 3 da SE3).

codcli string · query · opcional SE3.E3_CODCLI

Código do cliente.

loja string · query · opcional SE3.E3_LOJA

Loja do cliente.

prefixo string · query · opcional SE3.E3_PREFIXO

Prefixo do título de origem.

num string · query · opcional SE3.E3_NUM

Número do título de origem.

page integer · query · opcional

Página (default 1, mínimo 1).

pageSize integer · query · opcional

Tamanho da página (default 50, máx 500).

Chamada de exemplo

Request · por vendedorHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsComVnd/_list?vend=000001&page=1&pageSize=50
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Request · refina por cliente + títuloHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsComVnd/_list?vend=000001&codcli=00000402&loja=01&prefixo=001&num=123456789
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de comissões. Envelope com data (array de Comissao), page, pageSize, count.

400

Parâmetro fora do domínio (ex: pageSize > 500).

500

Erro interno.

Schemas

Definições canônicas — campos com origem SX3 rastreável

Comissao

object

Representação retornada nos GETs (/{chave}, /_list). Inclui os 6 componentes da chave composta, dados financeiros (base, percentual) e referências ao título de origem. Campos efetivamente retornados dependem do whitelist CAMPOS_GET.

E3_VENDstring · opcionalSE3.E3_VEND

Código do vendedor (FK para SA3).

E3_CODCLIstring · opcionalSE3.E3_CODCLI

Código do cliente (FK para SA1).

E3_LOJAstring · opcionalSE3.E3_LOJA

Loja do cliente.

E3_PREFIXOstring · opcionalSE3.E3_PREFIXO

Prefixo do título de origem.

E3_NUMstring · opcionalSE3.E3_NUM

Número do título.

E3_PARCELAstring · opcionalSE3.E3_PARCELA

Parcela do título (espaço quando única).

E3_EMISSAOstring (date) · opcionalSE3.E3_EMISSAO

Data de emissão da comissão.

E3_SERIEstring · opcionalSE3.E3_SERIE

Série da nota / título (default "UNI").

E3_BASEnumber · opcionalSE3.E3_BASE

Valor base de cálculo da comissão.

E3_PORCnumber · opcionalSE3.E3_PORC

Percentual da comissão.

E3_DATAstring (date) · opcionalSE3.E3_DATA

Data-base de apuração.

E3_SEQstring · opcionalSE3.E3_SEQ

Sequência de desdobramento (default em branco).

E3_TIPOstring · opcionalSE3.E3_TIPO

Tipo do título de origem (ex: "DH" = duplicata).

E3_PEDIDOstring · opcionalSE3.E3_PEDIDO

Pedido de venda associado (referência informativa).

E3_VENCTOstring (date) · opcionalSE3.E3_VENCTO

Vencimento — data prevista de apropriação.

E3_PROCCOMstring · opcionalSE3.E3_PROCCOM

Processo de comissão. Reflete a operação que gerou o registro.

INCLUSAOALTERACAO

E3_MOEDAstring · opcionalSE3.E3_MOEDA

Código da moeda (default "01" = moeda corrente).

ComissaoPayload

object

Payload plano aceito em POST (INCLUIR) e PUT (ALTERAR). Whitelist definida em CAMPOS_ALLOW no .prw. Os 6 componentes da chave (E3_VEND/E3_CODCLI/E3_LOJA/E3_PREFIXO/E3_NUM/E3_PARCELA) vêm do path e são ignorados quando presentes no body.

E3_EMISSAOstring (date) · opcionalSE3.E3_EMISSAO

Data de emissão. Aceita YYYY-MM-DD ou YYYYMMDD.

E3_SERIEstring · opcionalSE3.E3_SERIE

Série (default "UNI").

E3_BASEnumber · opcionalSE3.E3_BASE

Valor base. MATA490 exige > 0 quando E3_PORC > 0.

E3_PORCnumber · opcionalSE3.E3_PORC

Percentual de comissão (0 a 100).

E3_DATAstring (date) · opcionalSE3.E3_DATA

Data-base de apuração. Aceita ISO ou compacto.

E3_SEQstring · opcionalSE3.E3_SEQ

Sequência de desdobramento (default " ").

E3_TIPOstring · opcionalSE3.E3_TIPO

Tipo do título (ex: "DH"). Validado contra o SX5 de tipos.

E3_PEDIDOstring · opcionalSE3.E3_PEDIDO

Pedido de venda relacionado (referência informativa).

E3_VENCTOstring (date) · opcionalSE3.E3_VENCTO

Vencimento (data prevista de apropriação). Aceita ISO ou compacto.

E3_PROCCOMstring · opcionalSE3.E3_PROCCOM

Processo: "INCLUSAO" em POST, "ALTERACAO" em PUT. Ausente = default do MATA490.

INCLUSAOALTERACAO

E3_MOEDAstring · opcionalSE3.E3_MOEDA

Moeda do título (default "01").

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data traz a chave composta gravada (POST) ou string vazia (PUT/DELETE).

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

datastring | object · opcional

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter o token interno da causa (ex: mensagem do NomeAutoLog do MATA490) para tratamento programático, quando aplicável.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial do erro.

datastring · opcional

Token interno / detalhe técnico (ex: log do MsExecAuto).