rev1-2026-05-07 Protheus 12.1.27+ · NEWPCP

EstruturaProdutoMVC

CRUD de Estrutura de Produto (Bill of Materials — tabela SG1) via rotina automática PCPA200 (módulo SIGAPCP / NEWPCP). É a variante MVC do EstruturaProduto (MATA200), recomendada para ambientes com NEWPCP ativo (Protheus 12.1.27+). Modelo 2: cabeçalho do produto pai + array de itens cobrindo todos os componentes em todos os níveis (PA → PI → MP). PUT trabalha em modo delta — cada item declara _acao ∈ incluir | alterar | excluir.

Bloqueio TOTVS: tabela SG1 — variante MVC do MATA200; bloqueio relevante esta no produto (B1_MSBLQL).

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

Vinculação com o ERP

Tabela mestre SG1 Estruturas (BOM) · cabeçalho + itens

Rotina automática PCPA200 NEWPCP · MsExecAuto

Wrapper AdvPL U_PC200Exc src/lib/PC200EXC.prw

Operações & modos

POST modo 3 PUT modo 4 (delta) DEL modo 5

Dependências de ambiente

Cadastro · obrigatório

Produto pai (G1_COD)

registro em SB1 · validado via DbSeek antes do PCPA200
ausência retorna 422 com mensagem explícita

Cadastro · obrigatório

Componentes (G1_COMP)

cada componente do payload validado em SB1
componentes intermediários (sub-níveis) também

Parâmetro · relevante

MV_REVAUT

modo de controle de revisão (auto / manual)
influencia o uso de ATUREVSB1 e AUTREVPAI

Parâmetro · opcional

MV_NEGESTR · MV_CONSDUM

MV_NEGESTR permite quantidade negativa em componente
MV_CONSDUM define UMs válidas para proporção pai/componente

Convenções

Quando usar este endpoint vs. EstruturaProduto. Use o WsSG1Nw (este, PCPA200) quando o cliente tem NEWPCP ativo e nenhuma (ou pouca) customização via PE no MATA200. Mantenha o WsSG1 (MATA200) em ambientes com PCP clássico ou PE pesado sem equivalente liberado no NEWPCP. Nunca aponte os dois para o mesmo SG1 simultaneamente. Veja PCPA200-TDN.md no diretório do endpoint para a tabela completa de PEs e histórico de descontinuação do MATA200 (31/08/2022).

Identificador externo. Todas as rotas usam {produto} = G1_COD (produto pai), até 15 caracteres. O endpoint faz PadR para o tamanho de TamSX3("G1_COD") antes do DbSeek. A chave real da requisição em POST/PUT é o cabecalho.G1_COD do body — o path param funciona como placeholder visual obrigatório do roteador.

Modelo 2 — cabeçalho + itens em todos os níveis. O cabeçalho descreve o produto pai (quantidade base e flags de revisão). O array itens carrega todos os componentes em todos os níveis da estrutura — para uma árvore PA → PI → MP, o consumidor envia tanto os itens de PA (G1_COD=PA, G1_COMP=PI/MP) quanto os de PI (G1_COD=PI, G1_COMP=MP). Quando omitido, itens[].G1_COD defaulta para cabecalho.G1_COD.

POST recusa duplicata. O endpoint pré-valida existência: se já há registros em SG1 para o G1_COD informado, retorna 409 Conflict com mensagem orientando uso de PUT. O modo 3 do PCPA200 nunca é acionado neste caso.

PUT é delta — não substituição total. Cada item carrega _acao ∈ "incluir" | "alterar" | "excluir" (default "incluir"). Para alterar e excluir, a fachada injeta LINPOS automaticamente apontando para G1_COD+G1_COMP+G1_TRT; para excluir, também adiciona AUTDELETA="S". Componentes não enviados permanecem como estão na grade — diferente do PUT do WsSG1 (MATA200), que faz replace.

Flags de revisão (ATUREVSB1, AUTREVPAI). ATUREVSB1 em "S" faz o PCPA200 propagar a alteração para B1_REVATU / B1_UREV em SB1; em "N" (default), apenas SG1 muda. AUTREVPAI é a revisão do pai e só se aplica em modo 4 (alteração); 3 caracteres, padded em branco. O comportamento depende de MV_REVAUT.

Recálculo de níveis (NIVALT). Default "S" — recalcula a estrutura ao gravar (consistente, porém mais caro). Em carga em massa considere "N" e dispare o recálculo dedicado depois. Em DELETE o endpoint fixa NIVALT="S" no cabeçalho mínimo passado ao PCPA200.

Datas de vigência. G1_INI e G1_FIM no payload aceitam string no formato AAAAMMDD ou YYYY-MM-DD (o endpoint remove os hífens antes do SToD). Quando ausentes, aplica os defaults TDN: G1_INI = 01/01/2000 e G1_FIM = 31/12/2049.

DELETE não atualiza SB1. Comportamento da rotina PCPA200: a exclusão integral da estrutura (modo 5) não propaga para B1_REVATU / B1_UREV, mesmo com revisão automática ligada. Detalhe na TDN seção 4.3.3.

Tuplas com 3º elemento Nil. O wrapper U_PC200Exc monta cabeçalho e itens como tuplas { campo, valor, Nil } conforme exige a PCPA200. Diferente do MATA200, este 3º slot é obrigatório mesmo quando vazio.

Estrutura

CRUD por produto pai (G1_COD) via PCPA200

GET /WsSG1Nw/{produto} Consulta estrutura de um produto pai

Descrição

Se o DbSeek em SG1 falha — ou posiciona mas não retorna nenhuma linha sob o mesmo G1_COD + filial — o endpoint responde 404 com mensagem editorial ("Estrutura não encontrada." / "Estrutura sem componentes.").

Path parameter

produto string · path · obrigatório SG1.G1_COD

Código do produto pai. Até 15 caracteres. O endpoint faz PadR para o tamanho do SX3 antes do DbSeek.

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Estrutura encontrada. Envelope { success, message, data: { produto, itens[] } }. Veja EstruturaConsulta.

400

Produto vazio ou maior que o tamanho de G1_COD; para listagem use /WsSG1Nw/_list. Tier: validation-error.

404

Estrutura inexistente ou sem componentes para o produto pai informado. Tier: not-found.

POST /WsSG1Nw/INCLUIR/{produto} Inclui nova estrutura completa de produto

Descrição

Inclui uma nova estrutura via PCPA200 em modo 3 (insert completo). O endpoint:

Pré-valida que não existe estrutura prévia em SG1 para o G1_COD — caso contrário retorna 409.
Valida produto pai e cada componente em SB1 — 422 se ausente.
Aplica defaults: NIVALT="S", ATUREVSB1="N", G1_TRT=Space(3), G1_PERDA=0, G1_INI=01/01/2000, G1_FIM=31/12/2049.
Quando itens[].G1_COD está vazio, defaulta para cabecalho.G1_COD.
Repassa para U_PC200Exc, que invoca MsExecAuto({|x,y,z| PCPA200(x,y,z)},aCab,aItem,3) sob transação.

Exceções não tratadas viram 500 com mensagem editorial "Erro interno: …"; stack completo em console_rest.log.

Path parameter

produto string · path · obrigatório SG1.G1_COD

Placeholder visual do roteador. A chave real é cabecalho.G1_COD do body.

Request body

application/json PayloadInclusao · obrigatório

Payload composto: bloco cabecalho (produto pai + flags de revisão) + array itens com 1+ componentes em todos os níveis. Schema completo em PayloadInclusao.

Estrutura mínima — 1 nível. Produto pai PA001 com dois componentes diretos. Usa defaults TDN para datas, perda e tratamento.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "G1_COD":     "PA001",
    "G1_QUANT":   5,
    "ATUREVSB1": "N",
    "NIVALT":    "S"
  },
  "itens": [
    { "G1_COD": "PA001", "G1_COMP": "MP001", "G1_QUANT": 1 },
    { "G1_COD": "PA001", "G1_COMP": "MP002", "G1_QUANT": 2 }
  ]
}

Estrutura 2 níveis com sub-pai. Inclui componente intermediário PI001 e sua decomposição em MP003. Note como o item final tem G1_COD = "PI001" (não "PA001"), declarando o sub-nível.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "G1_COD":    "PA001",
    "G1_QUANT":  5,
    "ATUREVSB1": "N",
    "NIVALT":    "S"
  },
  "itens": [
    {
      "G1_COD":   "PA001",
      "G1_COMP":  "MP001",
      "G1_TRT":   "",
      "G1_QUANT": 1,
      "G1_PERDA": 0,
      "G1_INI":   "20000101",
      "G1_FIM":   "20491231"
    },
    { "G1_COD": "PA001", "G1_COMP": "PI001", "G1_QUANT": 1 },
    { "G1_COD": "PI001", "G1_COMP": "MP003", "G1_QUANT": 3 }
  ]
}

Respostas

201

Estrutura incluída. Envelope RespOk com data.produto = código do produto pai.

400

Body JSON ausente/inválido, bloco cabecalho ou itens faltando, G1_COD ausente. Tier: validation-error.

409

Estrutura já existe para o produto pai — use PUT em vez disso. Tier: business-error.

422

Produto pai/componente ausente em SB1, G1_QUANT ≤ 0 no cabeçalho, ou rejeição do MsExecAuto (unidade incompatível, regra de negócio NEWPCP, MV_NEGESTR bloqueia quantidade negativa, etc). Tier: business-error.

500

Erro interno (exceção AdvPL). Mensagem editorial; stack em console_rest.log.

PUT /WsSG1Nw/ALTERAR/{produto} Altera estrutura existente — delta por item

Descrição

Altera a estrutura via PCPA200 em modo 4 (delta). O endpoint verifica que a estrutura existe (DbSeek em SG1) antes de invocar a rotina automática; caso contrário, 404.

Delta por item. Cada item declara _acao ∈ "incluir" | "alterar" | "excluir" (default "incluir"). A fachada injeta automaticamente:

LINPOS = "G1_COD+G1_COMP+G1_TRT" com os 3 valores correspondentes para alterar e excluir;
AUTDELETA = "S" adicional para excluir.

Componentes não enviados permanecem na grade (diferente do PUT do WsSG1/MATA200, que faz replace total). Para alterações exclusivamente em campos do cabeçalho do pai (ex: G1_QUANT base, revisão), ainda é necessário enviar o array itens com pelo menos uma linha — o validador rejeita itens vazio em modo 4.

Path parameter

produto string · path · obrigatório SG1.G1_COD

Código do produto pai. Deve ter estrutura existente em SG1 (caso contrário 404).

Request body

application/json PayloadAlteracao · obrigatório

Mesma estrutura do PayloadInclusao; cada item pode trazer _acao. Ver PayloadAlteracao.

Delta misturado — altera quantidade de MP001, exclui MP002 e inclui PI003 (default _acao implícito). Componentes que não aparecem aqui (ex: outros itens existentes) permanecem inalterados.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "G1_COD":    "PA001",
    "G1_QUANT":  5,
    "ATUREVSB1": "S",
    "NIVALT":    "S"
  },
  "itens": [
    { "G1_COD": "PA001", "G1_COMP": "MP001", "G1_TRT": "", "G1_QUANT": 10, "_acao": "alterar" },
    { "G1_COD": "PA001", "G1_COMP": "MP002", "G1_TRT": "",                  "_acao": "excluir" },
    { "G1_COD": "PA001", "G1_COMP": "PI003", "G1_QUANT": 5 }
  ]
}

Apenas alteração + propagação de revisão. Ajusta perda em um único componente e força a propagação ao SB1 via ATUREVSB1="S" e AUTREVPAI="A01". Útil quando MV_REVAUT exige revisão manual do pai.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "G1_COD":     "PA001",
    "G1_QUANT":   5,
    "ATUREVSB1": "S",
    "AUTREVPAI": "A01",
    "NIVALT":    "S"
  },
  "itens": [
    {
      "G1_COD":   "PA001",
      "G1_COMP":  "MP001",
      "G1_TRT":   "",
      "G1_QUANT": 10,
      "G1_PERDA": 3.5,
      "_acao":    "alterar"
    }
  ]
}

Respostas

200

Estrutura alterada. Envelope RespOk com data.produto.

400

Produto inválido na URL ou payload mal-formado (cabeçalho/itens ausentes). Tier: validation-error.

404

Estrutura inexistente para o produto pai informado. Tier: not-found.

422

Componente ausente em SB1, item alvo do _acao="alterar" sem LINPOS resolvido, validação PCPA200 falhou (revisão, datas, regra NEWPCP). Tier: business-error.

500

Erro interno.

DEL /WsSG1Nw/EXCLUIR/{produto} Exclusão integral da estrutura

Descrição

Remove integralmente a estrutura do produto pai (todos os componentes em todos os níveis) via PCPA200 em modo 5. O endpoint posiciona SG1 em xFilial+G1_COD antes de chamar o wrapper, e monta apenas o cabeçalho mínimo (G1_COD + NIVALT="S") — itens são ignorados pela rotina em modo 5.

Não atualiza SB1. Por design do PCPA200, a exclusão não altera B1_REVATU / B1_UREV mesmo com revisão automática ligada (TDN seção 4.3.3). Para uma árvore PA → PI → MP, o consumidor deve chamar DELETE em cada nível, do mais alto para o mais baixo — o endpoint não percorre filhos automaticamente.

Path parameter

produto string · path · obrigatório SG1.G1_COD

Código do produto pai cuja estrutura será removida.

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Estrutura excluída. Envelope simples { success: true, message } — sem bloco data.

400

Produto inválido na URL (vazio ou maior que G1_COD). Tier: validation-error.

404

Estrutura inexistente para o produto pai. Tier: not-found.

422

Rejeição do MsExecAuto (estrutura referenciada por OP, planejamento, etc). Tier: business-error.

500

Erro interno (capturado por Recover Using).

Listagem

Produtos-pai com estrutura cadastrada

GET /WsSG1Nw/_list Lista produtos-pai com estrutura (1 linha por G1_COD)

Descrição

Lista produtos-pai distintos (1 linha por G1_COD) com estrutura cadastrada em SG1. Aplica filtro de filial e suporta prefixo de G1_COD via query param cod (usado em DbSeek(.T.) para posicionar o início do scan).

Paginação simples via page / pageSize; não há cursor / delta-sync nesta versão. A resposta atual traz apenas o código do produto pai — para detalhar uma estrutura específica, encadeie com GET /WsSG1Nw/{produto}.

Query parameters

cod string · query · opcional SG1.G1_COD

Prefixo de G1_COD — usado em DbSeek(.T.) para posicionar o início do scan (filtro server-side).

page integer · query · opcional · default: 1

Página (mínimo 1).

pageSize integer · query · opcional · default: 50 · máx 500

Tamanho da página. Valores ≤ 0 retornam ao default; acima de 500 são truncados.

Chamada de exemplo

Request · prefixoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSG1Nw/_list?cod=PA&pageSize=10
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Request · página 2HTTP/1.1 · sem body

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

Respostas

200

Página de produtos-pai. Envelope com data (array de ListagemItem), page, pageSize, count.

500

Erro interno.

Schemas

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

PayloadInclusao

object

Payload aceito em POST /WsSG1Nw/INCLUIR/{produto}. Composto pelos blocos cabecalho (Cabecalho) e itens (array de Item — mínimo 1).

cabecalhoobject · obrigatório

Produto pai + flags de revisão. Ver Cabecalho.

itensarray · obrigatório · minItems: 1

Componentes em todos os níveis. Ver Item.

PayloadAlteracao

object

Payload aceito em PUT /WsSG1Nw/ALTERAR/{produto}. Composição idêntica ao PayloadInclusao (allOf), porém cada item pode declarar a propriedade extra _acao ∈ incluir | alterar | excluir que decide o comportamento do PCPA200 modo 4. Campos do cabeçalho específicos do modo 4 (AUTREVPAI) também só fazem sentido aqui.

Cabecalho

object

Bloco de cabeçalho — identifica o produto pai e configura flags de revisão / recálculo. Convertido pelo endpoint em tuplas { campo, valor, Nil } para a PCPA200.

G1_CODstring · obrigatórioSG1.G1_COD

Código do produto pai. Deve existir em SB1.

G1_QUANTnumber · obrigatório em modo 3/4 · > 0SG1.G1_QUANT

Quantidade base da estrutura (denominador das proporções). Validação nQuant ≤ 0 retorna 422.

ATUREVSB1string · opcional · default: "N"

Propaga revisão para SB1 (B1_REVATU/B1_UREV).

SN

AUTREVPAIstring · opcional · só modo 4 · 3 chars

Revisão a aplicar ao pai. Padded em branco. Comportamento condicionado por MV_REVAUT.

NIVALTstring · opcional · default: "S"

Recalcula níveis ao gravar ("S") ou não ("N"). Em DELETE, fixado em "S" pelo endpoint.

SN

Item

object

Linha de componente. G1_COD aqui pode diferir do cabecalho.G1_COD para declarar sub-níveis (intermediários). Quando ausente, o endpoint o iguala ao cabecalho.G1_COD.

G1_CODstring · opcional · default: cabecalho.G1_CODSG1.G1_COD

Pai do componente (suporte a sub-níveis). Igual ao pai raiz para componentes diretos.

G1_COMPstring · obrigatórioSG1.G1_COMP

Código do componente. Deve existir em SB1 — validado antes do PCPA200; ausência retorna 422.

G1_TRTstring · opcional · default: Space(3) · maxLength: 3SG1.G1_TRT

Tratamento (3 chars). Participa do LINPOS no PUT delta.

G1_QUANTnumber · opcional · default: 0SG1.G1_QUANT

Quantidade do componente para a quantidade base do cabeçalho. Permite negativo se MV_NEGESTR=.T..

G1_PERDAnumber · opcional · default: 0SG1.G1_PERDA

Percentual de perda aplicado ao componente.

G1_INIstring · opcional · default: 01/01/2000SG1.G1_INI

Início da vigência. Formato AAAAMMDD ou YYYY-MM-DD; conversão interna via SToD após remover hífens.

G1_FIMstring · opcional · default: 31/12/2049SG1.G1_FIM

Fim da vigência. Mesmo formato de G1_INI.

_acaostring · opcional · só modo 4 · default: "incluir"

Decide o comportamento do delta no PUT. alterar/excluir disparam injeção automática de LINPOS (e AUTDELETA="S" em exclusão).

incluiralterarexcluir

ItemRetorno

object

Item retornado pelo GET /WsSG1Nw/{produto} em data.itens[]. Whitelist CAMPOS_ITEM_GET definido no .prw. Datas serializadas como AAAAMMDD via DToS.

G1_CODstringSG1.G1_COD

Pai do componente (sub-nível quando difere do produto raiz).

G1_COMPstringSG1.G1_COMP

Código do componente.

G1_TRTstringSG1.G1_TRT

Tratamento (3 chars).

G1_QUANTnumberSG1.G1_QUANT

Quantidade gravada.

G1_PERDAnumberSG1.G1_PERDA

Percentual de perda gravado.

G1_INIstringSG1.G1_INI

Início da vigência (AAAAMMDD).

G1_FIMstringSG1.G1_FIM

Fim da vigência (AAAAMMDD).

G1_REVINIstringSG1.G1_REVINI

Revisão inicial do componente (preenchida pelo NEWPCP quando ATUREVSB1="S").

G1_REVFIMstringSG1.G1_REVFIM

Revisão final do componente (substituída).

EstruturaConsulta

object · envelope

Envelope retornado pelo GET /WsSG1Nw/{produto}. data.itens[] traz todos os componentes em todos os níveis encontrados em SG1, na ordem natural do índice 1 (filial + G1_COD).

successboolean · const: true

Sempre true em respostas 200.

messagestring · opcional

Mensagem editorial (geralmente vazia em GET de sucesso).

data.produtostring

Eco do G1_COD consultado, trimmed.

data.itens[]array<ItemRetorno>

Componentes serializados. Ver ItemRetorno.

ListagemItem

object

Item enxuto retornado pelo GET /WsSG1Nw/_list — uma linha por produto-pai distinto. Não traz componentes; para detalhar a estrutura, chame GET /WsSG1Nw/{produto} com o G1_COD retornado.

G1_CODstringSG1.G1_COD

Código do produto pai.

RespOk

object · envelope

Envelope padrão das respostas de POST e PUT. O DELETE omite o bloco data (envelope simples só com success + message).

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial ("Estrutura de Produto incluida com sucesso." / "… alterada com sucesso." / "… excluida com sucesso.").

data.produtostring · opcional

Código do produto pai (eco do cabecalho.G1_COD) — presente em POST e PUT, ausente em DELETE.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. message traz o motivo em linguagem editorial; em 422 carrega o retorno do MsExecAuto via U_PC200Exc (lendo NomeAutoLog()) quando aplicável.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial do erro (apresentável ao usuário final).