rev1-2026-05-07 Protheus 12.1.33

Orcamento

Ciclo completo de orçamento de vendas (cabeçalho SCJ + itens SCK): inclusão, alteração e exclusão via MATA415; aprovação (efetivação em pedido SC5/SC6) e cancelamento via MATA416. O número do orçamento (CJ_NUM) é gerado pelo Protheus na inclusão via GetSXENum + ConfirmSX8; o cliente deve passar "auto" (ou qualquer string) no path da inclusão — o valor é ignorado.

Bloqueio TOTVS: tabela SCJ/SCK — orcamento, bloqueio relevante esta em SA1 (cliente) e SB1 (produto).

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

Vinculação com o ERP

Tabela mestre SCJ Cabeçalho do orçamento

Tabela detalhe SCK Itens do orçamento

Rotinas automáticas MATA415 / MATA416 MsExecAuto (CRUD + workflow)

Wrappers AdvPL U_MT415EX / U_MT416EX src/lib/MT415EXC.prw

Operações & modos

POST INCLUIR MATA415 op 3 PUT ALTERAR MATA415 op 4 DEL EXCLUIR MATA415 op 5 POST APROVAR MATA416 op 4 POST CANCELAR MATA416 op 6

Dependências de ambiente

Cadastro

Cliente (SA1) + condição (SE4) + TES (SF4) + produto (SB1)

CJ_CLIENTE+CJ_LOJACLI precisam existir em SA1 · CJ_CONDPAG em SE4 · CK_TES em SF4 · CK_PRODUTO em SB1

Sequência

Numeração SX8 do CJ_NUM

GetSXENum("SCJ","CJ_NUM") + ConfirmSX8 · gerada pelo Protheus na inclusão (path {numero} é ignorado)

Integração · condicional

Localização Brasil (impostos)

cálculo de ICMS/PIS/COFINS conforme TES e regras do MATXFIS · ativado automaticamente pelo MATA415

Bloqueio · fontes

Cancelamento requer release ≥ 28/03/2025

MATA416 op 6 (cancelamento) só existe em fontes a partir de 28/03/2025; ambientes anteriores retornam 422 do lMsErroAuto

Bloqueio · SIGAGSP

Aprovação indisponível com SIGAGSP ativo

ADV0066 · MATA416 op 4 (efetivação) é rejeitada quando SIGAGSP está habilitado · 422 com mensagem do MsExecAuto

Convenções

Identificador externo. Todas as rotas usam CJ_NUM (chave do orçamento) como path param. Na inclusão o valor é ignorado — o servidor gera o número via GetSXENum e devolve em data.numero. Por convenção, envie "auto". Nas demais rotas (ALTERAR, EXCLUIR, APROVAR, CANCELAR, GET /{numero}) o número é obrigatório e procurado por DbSeek sobre o índice de chave da SCJ.

Modelo 2 (cabeçalho + itens). O payload de inclusão / alteração é dividido em cabecalho (objeto com campos da SCJ) e itens (array com linhas da SCK). O MsExecAuto do MATA415 trata as duas tabelas atomicamente — falha em qualquer item aborta o cabeçalho.

Remoção parcial de itens no PUT. Para excluir uma linha existente, envie no array itens um objeto com LINPOS (o CK_ITEM da linha) e AUTDELETA:"S". Novos itens podem ser adicionados na mesma chamada — o MATA415 processa adições e deleções juntas.

Aprovar não é reversível sem cuidado. POST /APROVAR/{numero} efetiva o orçamento gerando SC5/SC6 (pedido de venda real). O smoke test do projeto mantém essa rota comentada de propósito. CANCELAR também exige release ≥ 28/03/2025; ambientes anteriores devolvem 422.

Whitelist de campos. Cabeçalho aceita CJ_CLIENTE, CJ_LOJACLI, CJ_LOJAENT, CJ_CONDPAG, CJ_TIPO, CJ_TIPOCLI, CJ_TABELA, CJ_VEND1, CJ_TRANSP, CJ_OBS (CAMPOS_CAB_ALLOW). Itens aceitam CK_PRODUTO, CK_QTDVEN, CK_PRCVEN, CK_PRUNIT, CK_VALOR, CK_TES, CK_LOCAL, CK_OPER, CK_DESC1 (CAMPOS_ITEM_ALLOW). Campos fora do whitelist são descartados silenciosamente.

Paginação. /_list usa page (default 1) e pageSize (default 50, máx 500). O filtro emissao é data exata no formato AAAAMMDD.

CRUD

Inclusão, alteração, exclusão e consulta por número

POST /WsSCJ/INCLUIR/{numero} Inclui novo orçamento (MATA415 op 3)

Descrição

Inclui um orçamento novo via MATA415 em modo 3 (MODEL_OPERATION_INSERT). O número CJ_NUM é gerado pelo Protheus (GetSXENum + ConfirmSX8) — o {numero} do path é ignorado (use "auto"). O servidor devolve a chave gerada em data.numero.

Whitelist do cabeçalho: ver OrcamentoInput.
Whitelist dos itens: ver OrcamentoItemInput.
Pré-requisitos: cliente em SA1, condição em SE4, TES em SF4, produto em SB1.

Path parameter

numero string · path · obrigatório SCJ.CJ_NUM

Na inclusão, valor é ignorado; envie "auto". O CJ_NUM real é gerado e devolvido em data.numero.

Request body

application/json OrcamentoInput · obrigatório

Objeto com cabecalho (campos da SCJ) e itens[] (pelo menos 1 linha da SCK). Schema completo em OrcamentoInput.

Mínimo (1 item). Cliente, condição e TES já cadastrados; payload usado pelo test-orcamento.sh da biblioteca.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "CJ_CLIENTE": "000001",
    "CJ_LOJACLI": "01",
    "CJ_LOJAENT": "01",
    "CJ_CONDPAG": "001"
  },
  "itens": [
    {
      "CK_PRODUTO": "PA001",
      "CK_QTDVEN": 1,
      "CK_PRCVEN": 100,
      "CK_PRUNIT": 100,
      "CK_VALOR": 100,
      "CK_TES": "501"
    }
  ]
}

Vários itens com vendedor, transportadora e observação. Cabeçalho preenche também CJ_VEND1, CJ_TRANSP e CJ_OBS; dois itens com TES e local diferentes.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "CJ_CLIENTE": "000001",
    "CJ_LOJACLI": "01",
    "CJ_LOJAENT": "01",
    "CJ_CONDPAG": "001",
    "CJ_TIPO": "N",
    "CJ_VEND1": "000001",
    "CJ_TRANSP": "000001",
    "CJ_OBS": "Orcamento de teste - smoke realistic"
  },
  "itens": [
    {
      "CK_PRODUTO": "PA001",
      "CK_QTDVEN": 2,
      "CK_PRCVEN": 120,
      "CK_PRUNIT": 120,
      "CK_VALOR": 240,
      "CK_TES": "501",
      "CK_LOCAL": "01"
    },
    {
      "CK_PRODUTO": "PA002",
      "CK_QTDVEN": 1,
      "CK_PRCVEN": 350,
      "CK_PRUNIT": 350,
      "CK_VALOR": 350,
      "CK_TES": "501",
      "CK_LOCAL": "02",
      "CK_DESC1": 5
    }
  ]
}

Respostas

201

Orçamento incluído. Envelope CrudResponse com data.numero = CJ_NUM gerado.

400

JSON inválido ou seções cabecalho/itens ausentes. Tier: validation-error.

422

Regra de negócio do MATA415 rejeitou (cliente inexistente, TES inválido, produto bloqueado, etc.). data traz o token de erro do NomeAutoLog. Tier: business-error.

500

Erro interno.

PUT /WsSCJ/ALTERAR/{numero} Altera orçamento existente (MATA415 op 4)

Descrição

Altera o cabeçalho e/ou os itens do orçamento via MATA415 em modo 4 (MODEL_OPERATION_UPDATE). Aceita qualquer subconjunto do whitelist em cabecalho; em itens, pode adicionar linhas novas (formato OrcamentoItemInput) e/ou remover linhas existentes (OrcamentoItemDelete com LINPOS + AUTDELETA:"S").

Body é opcional — uma chamada sem body apenas valida que o orçamento existe (retorna 200 sem alterar nada).

Path parameter

numero string · path · obrigatório SCJ.CJ_NUM

CJ_NUM do orçamento existente.

Request body

application/json OrcamentoAlterInput · opcional

Schema em OrcamentoAlterInput.

Alteração simples de observação. Payload mínimo do test-orcamento.sh.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsSCJ/ALTERAR/000000123
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "cabecalho": {
    "CJ_OBS": "Alterado via smoke test"
  }
}

Remoção parcial + adição. Remove o item de posição 0001 (via AUTDELETA:"S") e inclui uma linha nova. O MATA415 processa o array como diff.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsSCJ/ALTERAR/000000123
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "itens": [
    {
      "LINPOS": "0001",
      "AUTDELETA": "S"
    },
    {
      "CK_PRODUTO": "PA003",
      "CK_QTDVEN": 5,
      "CK_PRCVEN": 80,
      "CK_PRUNIT": 80,
      "CK_VALOR": 400,
      "CK_TES": "501"
    }
  ]
}

Troca de vendedor e condição. Só campos do cabeçalho; array de itens omitido — itens existentes preservados.

RequestHTTP/1.1 · application/json

PUT https://erpapi.jetme.com.br/api/99/01/WsSCJ/ALTERAR/000000123
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "cabecalho": {
    "CJ_VEND1": "000002",
    "CJ_CONDPAG": "002"
  }
}

Respostas

200

Orçamento alterado. Envelope CrudResponse.

400

JSON inválido. Tier: validation-error.

404

Orçamento inexistente para {numero}. Tier: not-found.

422

MATA415 rejeitou (item inválido, TES inexistente, LINPOS não encontrado, etc.). Tier: business-error.

500

Erro interno.

DEL /WsSCJ/EXCLUIR/{numero} Exclui orçamento (MATA415 op 5)

Descrição

Exclui o orçamento via MATA415 em modo 5 (MODEL_OPERATION_DELETE). Remove cabeçalho e itens atomicamente. Orçamento já aprovado (com pedido SC5 vinculado) pode ser rejeitado pelo MsExecAuto — nesse caso use POST /CANCELAR em vez de exclusão.

Path parameter

numero string · path · obrigatório SCJ.CJ_NUM

CJ_NUM do orçamento existente.

Chamada de exemplo

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsSCJ/EXCLUIR/000000123
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Orçamento excluído. Envelope CrudResponse.

400

{numero} ausente. Tier: validation-error.

404

Orçamento inexistente. Tier: not-found.

422

Orçamento aprovado / com pedido vinculado / dependências. Tier: business-error.

500

Erro interno.

GET /WsSCJ/{numero} Consulta orçamento por número

Descrição

Retorna o orçamento completo: cabecalho (campos de CAMPOS_CAB_GET) + itens[] (campos de CAMPOS_ITEM_GET ordenados por CK_ITEM). Aplica filtro de filial (xFilial("SCJ")).

Path parameter

numero string · path · obrigatório SCJ.CJ_NUM

CJ_NUM exato.

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSCJ/000000123
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Orçamento encontrado. Envelope { success: true, data: { cabecalho: OrcamentoCabec, itens: OrcamentoItem[] } }.

400

{numero} ausente.

404

Orçamento inexistente. Tier: not-found.

500

Erro interno.

Workflow

Aprovação (efetivação em pedido) e cancelamento via MATA416

POST /WsSCJ/APROVAR/{numero} Efetiva o orçamento e gera pedido (MATA416 op 4)

Descrição

Efetiva o orçamento via MATA416 em modo 4, gerando o pedido de venda (SC5/SC6). Cabeçalho e itens são reconstruídos pelo wrapper U_MT416EX a partir do registro SCJ/SCK posicionado — não há body.

Efeito colateral não reversível. Uma vez efetivado, o orçamento gera um pedido real. O smoke test do projeto mantém esta rota comentada de propósito.

Bloqueio SIGAGSP (ADV0066). Em ambientes com SIGAGSP ativo, a rotina é rejeitada pelo MsExecAuto com 422.

Path parameter

numero string · path · obrigatório SCJ.CJ_NUM

CJ_NUM existente.

Chamada de exemplo

RequestHTTP/1.1 · sem body

POST https://erpapi.jetme.com.br/api/99/01/WsSCJ/APROVAR/000000123
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Orçamento efetivado. Envelope CrudResponse; data.numero ecoa CJ_NUM. Pedido gerado em SC5/SC6.

404

Orçamento inexistente. Tier: not-found.

422

SIGAGSP ativo (ADV0066); orçamento já efetivado; estoque indisponível; ou outras regras do MATA416. Tier: business-error.

500

Erro interno.

POST /WsSCJ/CANCELAR/{numero} Cancela orçamento (MATA416 op 6)

Descrição

Cancela um orçamento existente via MATA416 em modo 6. Sem body — cabeçalho e itens reconstruídos pelo U_MT416EX a partir do registro posicionado.

Requer release ≥ 28/03/2025. A operação de cancelamento só existe em fontes MATA415/MATA416 a partir dessa data. Em ambientes anteriores, o MsExecAuto falha e o endpoint devolve 422 com o log de lMsErroAuto.

Path parameter

numero string · path · obrigatório SCJ.CJ_NUM

CJ_NUM existente.

Chamada de exemplo

RequestHTTP/1.1 · sem body

POST https://erpapi.jetme.com.br/api/99/01/WsSCJ/CANCELAR/000000123
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Orçamento cancelado. Envelope CrudResponse.

404

Orçamento inexistente. Tier: not-found.

422

Fontes anteriores a 28/03/2025; orçamento já cancelado/efetivado; outras regras do MATA416. Tier: business-error.

500

Erro interno.

Listagem

Listagem paginada com filtros por número, cliente e emissão

GET /WsSCJ/_list Lista orçamentos com filtros e paginação

Descrição

Retorna lista enxuta de orçamentos (campos do schema OrcamentoLista): CJ_NUM, CJ_CLIENTE, CJ_LOJACLI, CJ_EMISSAO. Filtros opcionais por prefixo de num, cliente/loja e data exata de emissão.

Query parameters

num string · query · opcional SCJ.CJ_NUM

Prefixo de CJ_NUM.

cliente string · query · opcional SCJ.CJ_CLIENTE

CJ_CLIENTE exato.

loja string · query · opcional SCJ.CJ_LOJACLI

Loja do cliente. Usar combinado com cliente.

emissao string · query · opcional SCJ.CJ_EMISSAO

Data exata em formato AAAAMMDD. Pattern: ^\d{8}$.

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 · primeira páginaHTTP/1.1 · sem body

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

Request · filtra por cliente e emissãoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSCJ/_list?cliente=000001&loja=01&emissao=20260507
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de orçamentos. Envelope com data (array de OrcamentoLista), page, pageSize, count.

400

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

500

Erro interno.

Schemas

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

OrcamentoInput

object

Payload de inclusão. Composto por cabecalho (campos da SCJ) e itens (array com pelo menos um OrcamentoItemInput). Whitelist do cabeçalho em CAMPOS_CAB_ALLOW.

cabecalhoobject · obrigatório

Cabeçalho do orçamento. Campos: CJ_CLIENTE, CJ_LOJACLI, CJ_LOJAENT, CJ_CONDPAG, CJ_TIPO, CJ_TIPOCLI, CJ_TABELA, CJ_VEND1, CJ_TRANSP, CJ_OBS. CJ_CLIENTE + CJ_LOJACLI são obrigatórios.

cabecalho.CJ_CLIENTEstring · obrigatórioSCJ.CJ_CLIENTE

Código do cliente. Deve existir em SA1.

cabecalho.CJ_LOJACLIstring · obrigatórioSCJ.CJ_LOJACLI

Loja do cliente.

cabecalho.CJ_LOJAENTstring · opcionalSCJ.CJ_LOJAENT

Loja de entrega (default = CJ_LOJACLI).

cabecalho.CJ_CONDPAGstring · opcionalSCJ.CJ_CONDPAG

Condição de pagamento. Deve existir em SE4.

cabecalho.CJ_TIPOstring · opcionalSCJ.CJ_TIPO

Tipo do orçamento (ex: N=Normal, B=Bonificação).

cabecalho.CJ_TIPOCLIstring · opcionalSCJ.CJ_TIPOCLI

Tipo do cliente (espelha A1_TIPO).

cabecalho.CJ_TABELAstring · opcionalSCJ.CJ_TABELA

Tabela de preço (DA0).

cabecalho.CJ_VEND1string · opcionalSCJ.CJ_VEND1

Vendedor principal (SA3).

cabecalho.CJ_TRANSPstring · opcionalSCJ.CJ_TRANSP

Transportadora (SA4).

cabecalho.CJ_OBSstring · opcionalSCJ.CJ_OBS

Observação livre.

itensarray<OrcamentoItemInput> · obrigatório · min 1

Lista de itens. Cada item deve obedecer OrcamentoItemInput.

OrcamentoAlterInput

object

Payload de alteração — todos os campos opcionais. itens aceita tanto novas linhas (OrcamentoItemInput) quanto remoções (OrcamentoItemDelete) na mesma chamada.

cabecalhoobject · opcional

Subconjunto do cabeçalho a alterar (whitelist CJ_CLIENTE, CJ_LOJACLI, CJ_CONDPAG, CJ_VEND1, CJ_OBS; demais campos do whitelist completo também são aceitos).

itensarray · opcional

Lista de operações de item: adição (OrcamentoItemInput) e/ou remoção (OrcamentoItemDelete).

OrcamentoItemInput

object

Linha de item para inclusão ou adição em alteração. Whitelist em CAMPOS_ITEM_ALLOW.

CK_PRODUTOstring · obrigatórioSCK.CK_PRODUTO

Código do produto. Deve existir em SB1.

CK_QTDVENnumber · obrigatórioSCK.CK_QTDVEN

Quantidade vendida.

CK_PRCVENnumber · opcionalSCK.CK_PRCVEN

Preço de venda unitário.

CK_PRUNITnumber · opcionalSCK.CK_PRUNIT

Preço unitário (base para cálculo).

CK_VALORnumber · opcionalSCK.CK_VALOR

Valor total da linha (CK_QTDVEN × CK_PRCVEN).

CK_TESstring · opcionalSCK.CK_TES

Tipo de Entrada/Saída. Deve existir em SF4.

CK_LOCALstring · opcionalSCK.CK_LOCAL

Local/armazém de saída (default "01").

CK_DESC1number · opcionalSCK.CK_DESC1

Percentual de desconto (1).

OrcamentoItemDelete

object

Forma de remover uma linha existente dentro do PUT. Convive no mesmo array itens que OrcamentoItemInput.

LINPOSstring · obrigatórioSCK.CK_ITEM

Número do CK_ITEM existente na linha que será removida.

AUTDELETAstring · obrigatório · const

Marcador de remoção. Único valor aceito: "S".

S

OrcamentoCabec

object

Cabeçalho retornado nos GETs. Campos efetivamente devolvidos conforme CAMPOS_CAB_GET.

CJ_NUMstring · opcionalSCJ.CJ_NUM

Número do orçamento (chave gerada por GetSXENum).

CJ_CLIENTEstring · opcionalSCJ.CJ_CLIENTE

Código do cliente.

CJ_LOJACLIstring · opcionalSCJ.CJ_LOJACLI

Loja do cliente.

CJ_LOJAENTstring · opcionalSCJ.CJ_LOJAENT

Loja de entrega.

CJ_CONDPAGstring · opcionalSCJ.CJ_CONDPAG

Condição de pagamento.

CJ_EMISSAOstring · opcionalSCJ.CJ_EMISSAO

Data de emissão (formato AAAAMMDD).

CJ_VEND1string · opcionalSCJ.CJ_VEND1

Vendedor principal.

CJ_TIPOstring · opcionalSCJ.CJ_TIPO

Tipo do orçamento.

CJ_OBSstring · opcionalSCJ.CJ_OBS

Observação.

CJ_STATUSstring · opcionalSCJ.CJ_STATUS

Status do orçamento (aberto / efetivado / cancelado conforme regras do MATA416).

OrcamentoItem

object

Linha de item retornada no GET. Campos conforme CAMPOS_ITEM_GET; ordenado por CK_ITEM.

CK_ITEMstring · opcionalSCK.CK_ITEM

Posição sequencial do item (0001, 0002…). Usar como LINPOS para remoção no PUT.

CK_PRODUTOstring · opcionalSCK.CK_PRODUTO

Código do produto.

CK_QTDVENnumber · opcionalSCK.CK_QTDVEN

Quantidade vendida.

CK_PRCVENnumber · opcionalSCK.CK_PRCVEN

Preço de venda.

CK_PRUNITnumber · opcionalSCK.CK_PRUNIT

Preço unitário.

CK_VALORnumber · opcionalSCK.CK_VALOR

Valor total da linha.

CK_TESstring · opcionalSCK.CK_TES

TES.

CK_LOCALstring · opcionalSCK.CK_LOCAL

Local/armazém.

CK_DESC1number · opcionalSCK.CK_DESC1

Desconto (%).

OrcamentoLista

object

Item enxuto devolvido pela rota /_list.

CJ_NUMstring · opcionalSCJ.CJ_NUM

Número do orçamento.

CJ_CLIENTEstring · opcionalSCJ.CJ_CLIENTE

Cliente.

CJ_LOJACLIstring · opcionalSCJ.CJ_LOJACLI

Loja do cliente.

CJ_EMISSAOstring · opcionalSCJ.CJ_EMISSAO

Data de emissão (AAAAMMDD).

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. data.numero traz o CJ_NUM gerado (INCLUIR) ou ecoa o existente (demais).

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

dataobject · opcional

Objeto com numero = CJ_NUM gerado / referenciado.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter o token interno da causa (log do NomeAutoLog / lMsErroAuto) 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 (log do MsExecAuto).