rev1-2026-05-07 Protheus 12.1.33

EstruturaProduto

CRUD de Estrutura de Produto (Bill of Materials — tabela SG1) via rotina automática MATA200. Modelo BOM: uma capa (G1_COD = produto pai) com grade de relações pai/filho (G1_COMP = componente). O produto pai e cada componente devem existir previamente em SB1. Exclusão em cascata (PA → PI → MP) é responsabilidade do consumidor; o endpoint remove apenas o nível informado.

Bloqueio TOTVS: tabela SG1 — BOM; bloqueio relevante esta no produto pai e componentes (B1_MSBLQL pre-check via MATA200).

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

Vinculação com o ERP

Tabela mestre SG1 Estruturas (BOM) · capa + grade

Rotina automática MATA200 MsExecAuto

Wrapper AdvPL U_MT200Exc src/lib/MAT/MT200EXC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Cadastro · obrigatório

Produto pai (G1_COD)

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

Cadastro · obrigatório

Componentes (G1_COMP)

cada componente do payload validado em SB1
campo G1_QUANT também obrigatório por item

Parâmetro · opcional

MV_CONSDUM

define unidades aceitas na validação de quantidade base
default kg · unidades divergentes podem provocar 422

Convenções

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. Não há chave técnica adicional exposta; cada estrutura é endereçada exclusivamente pelo seu produto pai.

Modelo BOM (capa + grade). Em SG1 a "capa" e a "grade" compartilham a mesma tabela: registros do mesmo G1_COD repetem os campos de capa (ex: G1_QUANT) e variam apenas G1_COMP e atributos do componente. O GET por produto agrupa: devolve cabecalho a partir do primeiro registro e componentes[] com todos os filhos.

Exclusão sem cascata. A TDN destaca: para apagar uma árvore completa (PA → PI → MP), o consumidor chama DELETE do nível mais alto para o mais baixo. O endpoint não encadeia exclusões automaticamente; cada DELETE remove apenas o nível informado.

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

Datas de vigência. G1_INI e G1_FIM no payload aceitam string no formato AAAAMMDD (passada a SToD). Quando ausentes, o endpoint aplica os defaults TDN: G1_INI = 01/01/01 e G1_FIM = 31/12/49.

Build 240223P — POST sem Begin Sequence. O WSMETHOD POST não envelopa em Begin Sequence porque o build perde Locals dentro do Recover Using. Em falha não tratada, a resposta é 500 cru com stack completo no console_rest.log. PUT e DELETE mantêm Recover Using para captura de exceções de DB.

Substituição total no PUT. O modo 4 do MATA200 trabalha como replace: a grade enviada substitui inteiramente a grade existente. Para alterações incrementais, monte o payload completo a partir de um GET /WsSG1/{produto} prévio.

Estrutura

CRUD por produto pai (G1_COD)

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

Descrição

Retorna a estrutura completa do produto pai informado: cabeçalho (campos de capa) e array de componentes (relações pai/filho). Aplica filtro de filial (xFilial("SG1")) e respeita o whitelist de CAMPOS_CAB_GET / CAMPOS_ITM_GET definidos no .prw.

Se o produto pai existe em SB1 mas não há registros em SG1, o endpoint responde 404 — "Estrutura não encontrada para o produto: …".

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/WsSG1/_T_PA01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Estrutura encontrada. Envelope { success, message, data: { cabecalho, componentes[] } }. Veja EstruturaConsulta.

400

Produto vazio ou maior que o tamanho de G1_COD. Tier: validation-error.

404

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

500

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

POST /WsSG1/INCLUIR/{produto} Inclui nova estrutura de produto

Descrição

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

Valida produto pai (G1_COD) em SB1 — 422 se ausente.
Valida cada componente (G1_COMP) em SB1 — 422 se ausente.
Aplica defaults TDN: G1_QUANT=1, NIVALT="S", G1_TRT=Space(3), G1_PERDA=0, G1_INI=01/01/01, G1_FIM=31/12/49.
Repassa para U_MT200Exc que executa MsExecAuto(MATA200,…,3).

POST não usa Begin Sequence (build 240223P quirk); exceções não tratadas viram 500 cru com stack no console_rest.log.

Path parameter

produto string · path · obrigatório SG1.G1_COD

Código do produto pai, até 15 caracteres. Deve existir em SB1.

Request body

application/json EstruturaPayload · obrigatório

Payload composto: bloco cabecalho (campos da capa) + array componentes com 1+ itens. Schema completo em EstruturaPayload.

Estrutura mínima — produto pai com dois componentes; usa todos os defaults TDN. Payload do test-estrutura-produto.sh.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "G1_QUANT": 1,
    "NIVALT": "S"
  },
  "componentes": [
    { "G1_COMP": "_T_PI01", "G1_QUANT": 1 },
    { "G1_COMP": "_T_MP01", "G1_QUANT": 2, "G1_PERDA": 5 }
  ]
}

Estrutura com perdas e vigência — uso real com G1_PERDA, datas de vigência e tratamento (G1_TRT). NIVALT="N" evita recálculo durante carga em massa.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "G1_QUANT": 1,
    "NIVALT": "N"
  },
  "componentes": [
    {
      "G1_COMP":   "_T_PI01",
      "G1_QUANT":  1,
      "G1_PERDA":  2.5,
      "G1_TRT":    "001",
      "G1_INI":    "20260101",
      "G1_FIM":    "20261231",
      "G1_OBSERV": "linha 1 - vigencia 2026"
    },
    {
      "G1_COMP":  "_T_MP01",
      "G1_QUANT": 2,
      "G1_PERDA": 5,
      "G1_OPC":   "01"
    }
  ]
}

Respostas

201

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

400

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

422

Produto pai ausente em SB1, componente ausente em SB1, G1_QUANT faltando, ou rejeição do MsExecAuto (unidade incompatível com MV_CONSDUM, estrutura já existente em POST, etc). Tier: business-error.

500

Erro interno (exceção AdvPL). Sem Recover Using no POST — stack visível em console_rest.log.

PUT /WsSG1/ALTERAR/{produto} Altera estrutura existente

Descrição

Altera a estrutura via MATA200 em modo 4 (update). O endpoint verifica que a estrutura existe (DbSeek em SG1) antes de invocar a rotina automática.

Substituição total. O modo 4 do MATA200 trabalha como replace: a grade enviada substitui inteiramente a grade existente; componentes não enviados são removidos. Para alterações incrementais, parta de um GET /WsSG1/{produto}.

Mesmo payload do POST — ver EstruturaPayload.

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 EstruturaPayload · obrigatório

Grade completa que substituirá a grade atual. Mínimo 1 componente.

Reduz para 1 componente — payload do smoke test; qualquer componente que estava na grade anterior e não está aqui é removido pela substituição total.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": { "G1_QUANT": 1, "NIVALT": "S" },
  "componentes": [
    { "G1_COMP": "_T_PI01", "G1_QUANT": 3 }
  ]
}

Altera quantidade e perda — mantém os dois componentes mas reajusta quantidade base e percentual de perda do componente principal.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": { "G1_QUANT": 2, "NIVALT": "S" },
  "componentes": [
    { "G1_COMP": "_T_PI01", "G1_QUANT": 1.5, "G1_PERDA": 3 },
    { "G1_COMP": "_T_MP01", "G1_QUANT": 4, "G1_PERDA": 8 }
  ]
}

Respostas

200

Estrutura alterada. Envelope SuccessResponse com data.produto.

400

Produto inválido na URL ou payload mal-formado. Tier: validation-error.

404

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

422

Componente ausente em SB1, validação MATA200 falhou. Tier: business-error.

500

Erro interno (capturado por Recover Using).

DEL /WsSG1/EXCLUIR/{produto} Exclui estrutura (apenas o nível informado)

Descrição

Exclui a estrutura inteira (todos os componentes do produto pai) via MATA200 em modo 5. O endpoint posiciona o alias SG1 no G1_COD alvo antes de chamar o wrapper.

Sem cascata. Para apagar 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/WsSG1/EXCLUIR/_T_PA01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Estrutura excluída. Envelope simples { success: true, message }.

400

Produto inválido na URL. Tier: validation-error.

404

Estrutura inexistente. Tier: not-found.

422

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

500

Erro interno.

Listagem

Produtos-pai com estrutura cadastrada

GET /WsSG1/_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. Suporta filtro por prefixo de G1_COD e filtro por componente — neste último caso, a varredura interna percorre todos os componentes de cada produto pai antes de decidir se inclui na resposta.

Paginação simples via page / pageSize. Não há cursor / delta-sync nesta versão.

Query parameters

prod string · query · opcional SG1.G1_COD

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

comp string · query · opcional SG1.G1_COMP

Filtra apenas estruturas que contenham este componente. Match exato (com AllTrim) — não prefixo.

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 · prefixoHTTP/1.1 · sem body

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

Request · filtro por componenteHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSG1/_list?comp=_T_MP01&page=1&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

EstruturaPayload

object

Payload aceito em POST e PUT. Composto pelos blocos cabecalho (EstruturaCabecalho) e componentes (array de EstruturaComponente — mínimo 1 item).

cabecalhoobject · obrigatório

Campos de capa. Ver EstruturaCabecalho.

componentesarray · obrigatório · minItems: 1

Lista de relações pai/filho. Ver EstruturaComponente.

EstruturaCabecalho

object

Campos da capa, replicados pelo MATA200 em cada linha da grade do mesmo G1_COD. Whitelist definida em CAMPOS_CAB_ALLOW no .prw. Ambos os campos são opcionais — o endpoint aplica os defaults TDN quando ausentes.

G1_QUANTnumber · opcional · default: 1SG1.G1_QUANT

Quantidade base da estrutura (denominador das proporções de cada componente).

NIVALTstring · opcional · default: "S"

Recalcula níveis ao gravar ("S") ou não ("N"). Use "N" em carga em massa e dispare recálculo dedicado depois.

SN

EstruturaComponente

object

Item da grade (relação pai/filho). Whitelist definida em CAMPOS_ITM_ALLOW no .prw. G1_COMP e G1_QUANT são obrigatórios.

G1_COMPstring · obrigatórioSG1.G1_COMP

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

G1_QUANTnumber · obrigatórioSG1.G1_QUANT

Quantidade do componente para a quantidade base do cabeçalho.

G1_PERDAnumber · opcional · default: 0SG1.G1_PERDA

Percentual de perda aplicado ao componente.

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

Tratamento (3 chars). Vazio por padrão.

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

Início da vigência. Formato AAAAMMDD; conversão interna via SToD.

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

Fim da vigência. Formato AAAAMMDD.

G1_OPCstring · opcionalSG1.G1_OPC

Opcional (código de variante / opcional do produto).

G1_OPCDstring · opcionalSG1.G1_OPCD

Descrição do opcional (par com G1_OPC).

G1_OBSERVstring · opcionalSG1.G1_OBSERV

Observação livre do item.

EstruturaConsulta

object · envelope

Envelope retornado pelo GET /WsSG1/{produto}. Bloco data.cabecalho traz os campos de capa (CAMPOS_CAB_GET) e data.componentes[] traz cada relação pai/filho com CAMPOS_ITM_GET.

successboolean · const: true

Sempre true em respostas 200.

messagestring · opcional

Mensagem editorial (geralmente vazia em GET de sucesso).

data.cabecalhoobject

Campos de capa serializados: G1_COD, G1_QUANT.

data.componentes[]array<object>

Cada item traz: G1_COMP, G1_TRT, G1_QUANT, G1_PERDA, G1_INI, G1_FIM, G1_OPC, G1_OBSERV. Datas em formato AAAAMMDD via DToS.

ListagemItem

object

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

G1_CODstringSG1.G1_COD

Código do produto pai.

G1_QUANTnumberSG1.G1_QUANT

Quantidade base da capa (lida do primeiro registro encontrado para o pai).

SuccessResponse

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." etc).

data.produtostring · opcional

Código do produto pai (eco do path param) — 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_MT200Exc quando aplicável.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

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