rev2-2026-05-17

PedidoVenda

CRUD de Pedido de Venda (cabeçalho SC5 + itens SC6) via wrapper MATA410 (MsExecAuto). Reescrito em rev1 (16/05/2026) para o padrão da biblioteca: 1 pedido por chamada, C5_NUM no path, sub-rotas INCLUIR/ALTERAR/EXCLUIR, e GETs alinhados ao mesmo formato do WsSCJ (Orçamento).

Bloqueio TOTVS: a SC5/SC6 não tem flag de bloqueio próprio (SC5 não tem C5_MSBLQL). O bloqueio relevante mora em SA1 (cliente, via U_C980Blq) e SB1 (produto). Validação acontece no wrapper U_MT410Exc — tentativa de incluir com cliente ou produto bloqueado retorna 422 com a mensagem do MsExecAuto.

Vinculação com o ERP

Tabela mestre SC5 Pedidos de venda · cabeçalho

Tabela detalhe SC6 Itens dos pedidos

Rotina automática MATA410 MsExecAuto · op 3/4/5

Wrapper AdvPL U_MT410Exc src/lib/MAT/MT410EXC.prw

Fonte REST WSSC5.prw src/api/PedidoVenda/

Chave externa C5_NUM no path · 6 chars

Dependências de ambiente

Cadastro

Cliente (SA1)

validado via DbSeek(xFilial("SA1") + C5_CLIENTE + C5_LOJACLI) antes do MsExecAuto; cliente inexistente → 422.

Cadastro

Produto (SB1)

cada item valida C6_PRODUTO em SB1 antes da composição do aItens do MATA410.

Cadastro

Condição (SE4) e TES (SF4)

validação delegada ao MATA410; mensagem do GetAutoGRLog retorna 422 quando o código não existe.

Out of scope

Rateio AGG e grade SC6

Não suportados nesta revisão. Pedidos com rateio múltiplo ou produtos com grade precisam usar a tela MATA410 do ERP.

Convenções

Envelope canônico. Toda resposta usa { success: bool, message: string, data: object|string }. Erros têm success=false + message com causa; sucessos retornam o C5_NUM em data.C5_NUM.

Chave no path. Todas as operações de mutação usam {numero} como path-param (6 chars, padding via PadR). Diferente do rev0 antigo que usava C5_EXTERNO como chave externa — aquele schema foi descontinuado.

Datas em ISO. C5_EMISSAO e C6_ENTREG aceitam tanto AAAAMMDD quanto YYYY-MM-DD — conversão interna usa SToD(StrTran(v,"-","")).

Alteração de item via LINPOS. No PUT, o item informa LINPOS com o C6_ITEM alvo; opcionalmente AUTDELETA="S" marca exclusão da linha. Itens sem LINPOS são tratados como novos.

Whitelist de campos. Cabeçalho aceita apenas C5_TIPO, C5_CLIENTE, C5_LOJACLI, C5_LOJAENT, C5_CONDPAG, C5_VEND1, C5_TRANSP, C5_TPFRETE, C5_EMISSAO, C5_OBS, C5_XORIG, C5_IDEXT. Itens aceitam C6_PRODUTO, C6_QTDVEN, C6_PRCVEN, C6_PRUNIT, C6_VALOR, C6_TES, C6_LOCAL, C6_OPER, C6_ENTREG. Campos fora dessa lista são ignorados.

Pedido de Venda — mutação

Inclusão / alteração / exclusão via MATA410.

POST /WsPedidoVenda/INCLUIR/000001 Inclui pedido — MATA410 op=3

Descrição

Inclui um pedido de venda em SC5/SC6. {numero} deve ser único — duplicidade retorna 409. Cliente em SA1 e produto(s) em SB1 são validados antes da chamada ao MATA410; falhas viram 422 com a mensagem do GetAutoGRLog.

Path parameter

numerostring · max 6 · obrigatório

Valor a ser usado como C5_NUM. Padding com espaço à direita até TamSX3('C5_NUM')[1].

Cenário

Request body

application/json PedidoPayload · obrigatório

Envelope { cabecalho: {...}, itens: [...] }. Schema em PedidoPayload.

cabecalho.C5_CLIENTEstring · obrigatório

Código do cliente em SA1.

cabecalho.C5_LOJACLIstring · opcional

Loja do cliente. Default "01" quando omitido.

cabecalho.C5_CONDPAGstring · opcional

Condição de pagamento (SE4).

cabecalho.C5_EMISSAOstring (date) · opcional

Data ISO YYYY-MM-DD ou AAAAMMDD.

itens[].C6_PRODUTOstring · obrigatório

Produto (SB1).

itens[].C6_QTDVENnumber · obrigatório

Quantidade vendida.

itens[].C6_PRCVENnumber · opcional

Preço unitário. Quando omitido, MATA410 busca da tabela de preços.

itens[].C6_TESstring · opcional

TES (SF4). Quando omitido, MATA410 resolve via matriz de TES da venda.

Mínimo viável. Cliente + 1 item; MATA410 resolve condição/TES/preço a partir do cadastro.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsPedidoVenda/INCLUIR/000001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json

{
  "cabecalho": {
    "C5_CLIENTE": "000001"
  },
  "itens": [
    {
      "C6_PRODUTO": "P0001",
      "C6_QTDVEN": 10
    }
  ]
}

Realístico. Cabeçalho completo com condição/data, 2 itens com preço e TES explícitos.

RequestHTTP/1.1 · application/json

POST https://erpapi.jetme.com.br/api/99/01/WsPedidoVenda/INCLUIR/000001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json

{
  "cabecalho": {
    "C5_TIPO": "N",
    "C5_CLIENTE": "000001",
    "C5_LOJACLI": "01",
    "C5_CONDPAG": "001",
    "C5_EMISSAO": "2026-05-17",
    "C5_XORIG": "API_TESTE"
  },
  "itens": [
    {
      "C6_PRODUTO": "P0001",
      "C6_QTDVEN": 5,
      "C6_PRCVEN": 120.00,
      "C6_TES": "501",
      "C6_LOCAL": "01"
    },
    {
      "C6_PRODUTO": "P0002",
      "C6_QTDVEN": 2,
      "C6_PRCVEN": 350.00,
      "C6_TES": "501"
    }
  ]
}

Respostas

201

Pedido criado. data.C5_NUM retorna o número informado no path.

400

Número ausente/inválido, payload mal-formado, JSON inválido.

409

Pedido já cadastrado com esse número.

422

Cliente/produto inexistente, ou erro do MATA410 (TES não encontrado, condição inválida, regra de bloqueio).

401

Token ausente ou expirado.

PUT /WsPedidoVenda/ALTERAR/000001 Altera cabeçalho/itens — MATA410 op=4

Descrição

Alteração de pedido existente. Diferente do POST, cabecalho e itens são opcionais — quando omitidos, mantêm o valor atual. Itens são endereçados via LINPOS (= C6_ITEM). Itens sem LINPOS entram como novos. AUTDELETA="S" em conjunto com LINPOS exclui a linha.

Path parameter

numerostring · max 6 · obrigatório

Número do pedido existente.

Cenário

Request body

cabecalho.C5_OBSstring · opcional

Observação livre.

cabecalho.C5_CONDPAGstring · opcional

Nova condição de pagamento.

itens[].LINPOSstring · obrigatório p/ alteração

C6_ITEM do item alvo.

itens[].C6_QTDVENnumber · opcional

Nova quantidade.

itens[].AUTDELETAstring ("S"/"N") · opcional

"S" exclui o item do pedido.

Alterar só cabeçalho. Itens não tocados.

Requestapplication/json

PUT https://erpapi.jetme.com.br/api/99/01/WsPedidoVenda/ALTERAR/000001

{
  "cabecalho": {
    "C5_OBS": "Pedido revisado",
    "C5_CONDPAG": "002"
  }
}

Alterar item específico. Quantidade do item 01 sobe para 20; item 02 é excluído.

Requestapplication/json

PUT https://erpapi.jetme.com.br/api/99/01/WsPedidoVenda/ALTERAR/000001

{
  "itens": [
    { "LINPOS": "01", "C6_QTDVEN": 20 },
    { "LINPOS": "02", "AUTDELETA": "S" }
  ]
}

Respostas

200

Pedido alterado.

404

Pedido não encontrado.

422

Erro de regra do MATA410 (item bloqueado por liberação, regra de pricing etc).

DELETE /WsPedidoVenda/EXCLUIR/000001 Exclui pedido — MATA410 op=5

Descrição

Exclui o pedido. O endpoint reconstrói o array de itens mínimo (C6_ITEM + C6_PRODUTO) a partir do SC6 e passa para MATA410 op=5. Liberações em uso ou pedidos com NF emitida ficam barrados pelo MATA410 → 422.

Cenário

Exemplo

Exclusão direta. Sem body — só o número no path.

RequestHTTP/1.1

DELETE https://erpapi.jetme.com.br/api/99/01/WsPedidoVenda/EXCLUIR/000001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…

Respostas

200

Excluído com sucesso.

404

Pedido inexistente.

422

Pedido com liberação ativa, NF emitida, ou regra do MATA410.

Consulta

Consulta por número, listagem paginada e typeahead.

GET /WsPedidoVenda/000001 Pedido por número (cabeçalho + itens)

Descrição

Devolve cabeçalho e itens em data.{cabecalho,itens}. 404 quando o número não existe.

Cenário

Exemplo

RequestHTTP/1.1

GET https://erpapi.jetme.com.br/api/99/01/WsPedidoVenda/000001

Response 200application/json

{
  "success": true,
  "data": {
    "cabecalho": {
      "C5_NUM": "000001",
      "C5_CLIENTE": "000001",
      "C5_LOJACLI": "01",
      "C5_EMISSAO": "20260517"
    },
    "itens": [
      { "C6_ITEM": "01", "C6_PRODUTO": "P0001", "C6_QTDVEN": 10 }
    ]
  }
}

GET /WsPedidoVenda/_list Listagem paginada com filtros

Descrição

Itera SC5 em ordem do índice 1 (C5_FILIAL+C5_NUM) com filtros opcionais num, cliente, loja e emissao. Paginação via page/pageSize.

Query parameters

numstring · opcional

Prefixo de C5_NUM.

clientestring · opcional

Match exato de C5_CLIENTE.

lojastring · opcional

Match exato de C5_LOJACLI.

emissaostring · opcional

AAAAMMDD — match exato.

pageinteger · default 1

Página solicitada.

pageSizeinteger · default 50, max 500

Tamanho da página.

Cenário

Exemplo

RequestHTTP/1.1

GET https://erpapi.jetme.com.br/api/99/01/WsPedidoVenda/_list?cliente=000001&page=1&pageSize=25

GET /WsPedidoVenda/_search Typeahead por C5_NUM

Descrição

Busca via TCGenQry em SC5 com C5_NUM LIKE <q>% (helper U_RestSug). Mínimo 2 caracteres em q; limite default 10 (max 25).

Query parameters

qstring · min 2 · obrigatório

Prefixo numérico do C5_NUM.

limitinteger · default 10, max 25

Limite de sugestões.

Cenário

Exemplo

RequestHTTP/1.1

GET https://erpapi.jetme.com.br/api/99/01/WsPedidoVenda/_search?q=0000&limit=5

Schemas

Componentes do contrato OpenAPI

PedidoPayload

object

Envelope de entrada do POST/PUT. Cabeçalho + array de itens.

cabecalhoCabecalho · obrigatório no POST

Ver Cabecalho. Opcional no PUT.

itensarray[Item] · obrigatório no POST

Array de itens. Ver Item.

Cabecalho

object · SC5

Cabeçalho do pedido. Whitelist do CAMPOS_CAB_ALLOW em WSSC5.prw.

C5_TIPOstring · opcionalSC5.C5_TIPO

"N"=normal (default).

C5_CLIENTEstring · obrigatório (POST)SC5.C5_CLIENTE

Código do cliente em SA1.

C5_LOJACLIstring · default 01SC5.C5_LOJACLI

Loja do cliente.

C5_LOJAENTstring · opcionalSC5.C5_LOJAENT

Loja de entrega.

C5_CONDPAGstring · opcionalSC5.C5_CONDPAG

Condição de pagamento (SE4).

C5_VEND1string · opcionalSC5.C5_VEND1

Vendedor (SA3).

C5_TRANSPstring · opcionalSC5.C5_TRANSP

Transportadora (SA4).

C5_TPFRETEstring · opcionalSC5.C5_TPFRETE

Tipo de frete (C/F/T/S/R).

C5_EMISSAOstring (date) · opcionalSC5.C5_EMISSAO

ISO ou AAAAMMDD. Default = data do servidor.

C5_OBSstring · opcionalSC5.C5_OBS

Observação livre.

C5_XORIGstring · opcionalSC5.C5_XORIG

Origem da integração (rastreabilidade).

C5_IDEXTstring · opcionalSC5.C5_IDEXT

ID externo (legado rev0). Não usado como chave em rev1; só rastreamento.

Item

object · SC6

Item do pedido. Whitelist do CAMPOS_ITEM_ALLOW.

LINPOSstring · PUT

Apenas em PUT: C6_ITEM do item alvo de alteração/exclusão.

AUTDELETAstring · PUT

Apenas em PUT: "S" exclui a linha (combinar com LINPOS).

C6_PRODUTOstring · obrigatório (POST)SC6.C6_PRODUTO

Produto (SB1, 15 chars).

C6_QTDVENnumber · obrigatório (POST)SC6.C6_QTDVEN

Quantidade vendida.

C6_PRCVENnumber · opcionalSC6.C6_PRCVEN

Preço unitário (MATA410 resolve quando omitido).

C6_PRUNITnumber · opcionalSC6.C6_PRUNIT

Preço unitário sem impostos.

C6_VALORnumber · opcionalSC6.C6_VALOR

Valor total da linha.

C6_TESstring · opcionalSC6.C6_TES

TES (SF4, 3 chars). MATA410 resolve via matriz quando omitido.

C6_LOCALstring · default 01SC6.C6_LOCAL

Armazém.

C6_OPERstring · opcionalSC6.C6_OPER

Operação.

C6_ENTREGstring (date) · opcionalSC6.C6_ENTREG

Data de entrega. ISO ou AAAAMMDD.

EnvelopeSucesso

object · envelope

Envelope canônico de sucesso. Mesmo formato em todos os endpoints da biblioteca.

successboolean

true.

messagestring

Texto descritivo da operação concluída.

dataobject

Payload de retorno (e.g. { C5_NUM: "000001" } em POST, ou { cabecalho, itens } em GET).

EnvelopeErro

object · envelope

Envelope canônico de erro. Mesma forma do sucesso, com success=false.

successboolean

false.

messagestring

Causa do erro. Para erros do MATA410, traz o GetAutoGRLog com linhas separadas por /.

datastring

Vazio ("").

Cenários

Combinações testáveis dos endpoints — alinhadas 1-pra-1 com examples: do YAML.

incluir-minimo

POST /WsPedidoVenda/INCLUIR/{numero}

Caminho feliz mínimo: cliente + 1 item. MATA410 resolve TES/condição/preço pelo cadastro.

cabecalho.C5_CLIENTE

000001

itens[0].C6_PRODUTO

P0001

itens[0].C6_QTDVEN

incluir-completo

POST /WsPedidoVenda/INCLUIR/{numero}

Caminho realístico: cabeçalho com condição/data/origem, 2 itens com preço e TES explícitos.

cabecalho

C5_TIPO=N, C5_CLIENTE=000001/01, C5_CONDPAG=001, C5_EMISSAO=2026-05-17, C5_XORIG=API_TESTE

itens[0]

P0001 · qtd 5 · prc 120 · TES 501 · armazém 01

itens[1]

P0002 · qtd 2 · prc 350 · TES 501

alterar-cabecalho

PUT /WsPedidoVenda/ALTERAR/{numero}

Edita só campos do cabeçalho — itens não tocados.

cabecalho.C5_OBS

"Pedido revisado"

cabecalho.C5_CONDPAG

"002"

alterar-item-linpos

PUT /WsPedidoVenda/ALTERAR/{numero}

Edita item via LINPOS + opcional AUTDELETA.

itens[0]

LINPOS=01, C6_QTDVEN=20 (altera quantidade)

itens[1]

LINPOS=02, AUTDELETA="S" (exclui item)

excluir

DELETE /WsPedidoVenda/EXCLUIR/{numero}

Exclusão direta sem body. Falha quando há liberação ativa ou NF emitida.

path.numero

000001 (C5_NUM existente)

consulta-byid

GET /WsPedidoVenda/{numero}

Retorna cabeçalho + itens do pedido único.

path.numero

000001

listagem

GET /WsPedidoVenda/_list

Pedidos do cliente 000001, paginação 25 por página.

cliente

000001

page

pageSize

typeahead

GET /WsPedidoVenda/_search

Sugestões de C5_NUM começando em "0000", limite 5.

"0000"

limit

Pendências conhecidas (rev2)

Rateio AGG não suportado. Pedidos que precisam de rateio múltiplo por centro de custo precisam usar a tela MATA410 do ERP. Adicionar suporte exige extensão do aCab com array aRateio — não escopado nesta revisão.

Grade SC6 não suportada. Produtos com grade (variação/tamanho) não podem ser incluídos por este endpoint — MATA410 espera estrutura especial em aCab[?][SC9] que não está mapeada.

Smoke test E2E pendente. Validação automática requer fixtures estáveis de SA1, SB1, SE4 e SF4 no ambiente. Hoje a validação roda manual via Postman a partir do openapi.yaml. Ver README.md do endpoint.

Bloqueio TOTVS SC5/SC6 ausente. A tabela SC5 não tem C5_MSBLQL nesta base. O bloqueio efetivo herda de SA1 (cliente) e SB1 (produto) via U_C980Blq no wrapper U_MT410Exc.