rev1-2026-05-07 Protheus 12.1.33

PreEstrutura

CRUD de pré-estrutura de produtos (tabela SGG) via rotina automática PCPA135 do módulo SIGAPCP. Identificador externo é GG_COD (código do produto pai); a árvore de componentes é informada de forma plana — a treeview interna é montada a partir do par GG_COD (pai) + GG_COMP (filho). O workflow de aprovação (Aprovar / Rejeitar / Criar Estrutura) não está exposto: a rotina automática não cobre essas ações.

Bloqueio TOTVS: tabela SGG — pre-estrutura/template, sem MSBLQL nativo; gate via GG_STATUS.

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

Vinculação com o ERP

Tabela mestre SGG Pré-estrutura (cabeçalho + componentes)

Rotina automática PCPA135 SIGAPCP · MsExecAuto

Wrapper AdvPL U_PC135Exc src/lib/PC135EXC.prw

Operações & modos

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

Dependências de ambiente

Cadastro · obrigatório

Produtos (pai e componentes em SB1)

produto pai (cabecalho.GG_COD) e cada GG_COMP precisam existir em SB1 antes do POST; valida-se antes do MsExecAuto para evitar 422 genérico do PCPA135.

Estado · editável

GG_STATUS — "Em criação"

PUT só processa quando GG_STATUS está em estado editável. Submetida / Aprovada / Rejeitada / Estrutura criada são silenciosamente bloqueadas pela rotina automática; o endpoint converte em 422 lendo NomeAutoLog().

Workflow · NÃO exposto

Aprovar / Rejeitar / Criar Estrutura

PCPA135 não tem rotina automática para o workflow de aprovação. Promoção SGG → SG1 exige chamada separada à PCPA200. Ver PCPA135-TDN.md §4.2.

LINPOS · consistência

Trio GG_COD / GG_COMP / GG_TRT

No PUT delta, o LINPOS calculado para alterar / excluir precisa casar exatamente com o trio no aGets. Divergência falha silenciosamente — wrapper valida e propaga erro.

Convenções

Identificador externo. Todas as rotas /WsSGG/{codigo} usam GG_COD — código do produto pai. O path param da operação de inclusão (/WsSGG/INCLUIR/{codigo}) é apenas placeholder do roteador WSRESTFUL (build 240223P exige {param} para Self ser válido); o código realmente persistido vem de cabecalho.GG_COD. Use "auto" ou repita o GG_COD da capa.

Payload plano, árvore inferida. Os itens (itens[]) são informados em formato plano. A treeview multinível é montada internamente pelo PCPA135 a partir do par GG_COD (pai) + GG_COMP (filho) — basta que cada componente referencie corretamente seu pai. Não há nesting recursivo no JSON.

PUT é delta. Cada item do array itens[] em PUT aceita o atributo _acao com três valores: incluir (default, adiciona componente novo), alterar (gera LINPOS + atualiza), excluir (gera LINPOS + AUTDELETA="S"). Apenas os itens informados são processados; o restante permanece intacto.

DELETE não é cascata. Op 5 apaga apenas os componentes do GG_COD informado. Sub-árvores (produtos intermediários filhos com pré-estrutura própria) não são removidas — chamadas separadas para cada nível. Use o GET para descobrir as sub-árvores existentes antes de excluir.

Formato de datas. GG_INI e GG_FIM usam string compacta AAAAMMDD (8 dígitos sem separador), não ISO. Exemplo: "20240101" para 01/01/2024.

Pré-estrutura é sandbox. Empenhos de OP, MRP e relatórios de estrutura não consultam SGG. Para produção, a pré-estrutura precisa ser promovida para SG1 via PCPA200 — fluxo externo a este endpoint. Pontos de entrada (PEs) do antigo MATA202 (A202UNDO/A202BOK/MTA202) não têm equivalente no PCPA135.

Paginação. /_list retorna 1 linha por GG_COD pai. Use page/pageSize (default 50, máx 500). Filtros opcionais: cod (prefixo) e status (código de GG_STATUS).

Pré-Estrutura

CRUD via PCPA135 / SGG

GET /WsSGG/{codigo} Consulta pré-estrutura por GG_COD

Descrição

Retorna a pré-estrutura completa do produto pai informado em {codigo} — cabeçalho (GG_COD, GG_QUANT, GG_STATUS) e array itens[] com todos os componentes. Aplica filtro de filial (xFilial("SGG")) e respeita o whitelist de CAMPOS_CAB_GET / CAMPOS_ITEM_GET definidos no .prw.

Path parameter

codigo string · path · obrigatório SGG.GG_COD

GG_COD — código do produto pai (whitespace é trimado).

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Pré-estrutura encontrada. Envelope RespostaPreEstrutura com data.cabecalho e data.itens[].

400

{codigo} ausente ou vazio. Tier: validation-error.

404

Não existe pré-estrutura para o GG_COD informado. Tier: not-found.

POST /WsSGG/INCLUIR/{codigo} Inclui pré-estrutura completa (PCPA135 Op=3)

Descrição

Cria a pré-estrutura para o produto pai informado em cabecalho.GG_COD via PCPA135 em Op=3. O array itens deve conter todos os componentes em todos os níveis — a treeview é montada internamente a partir do par GG_COD (pai) + GG_COMP (filho), então componentes de produtos intermediários (PIs) entram no mesmo array, com GG_COD apontando para o PI ao qual pertencem.

Path param {codigo} é placeholder (use "auto" ou repita GG_COD).
Whitelist de campos: ver Cabecalho e Item.
Pré-condições validadas antes do MsExecAuto: produto pai e cada componente existem em SB1; não existe pré-estrutura prévia para o GG_COD informado.

Path parameter

codigo string · path · obrigatório

Placeholder do roteador WSRESTFUL (build 240223P exige {param} para Self ser válido). Use "auto" ou repita o GG_COD da capa.

Request body

application/json PreEstruturaInclusao · obrigatório

Objeto com cabecalho (capa do produto pai) e itens[] (todos os componentes, mínimo 1). Schema em PreEstruturaInclusao.

Inclusão mínima (2 componentes) — produto pai Z_TEST_PA com dois componentes diretos. Capa só com GG_COD + GG_QUANT. Fixture: fixtures/post-inclusao.json.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "GG_COD": "Z_TEST_PA",
    "GG_QUANT": 1
  },
  "itens": [
    {
      "GG_COD":    "Z_TEST_PA",
      "GG_COMP":   "Z_TEST_MP1",
      "GG_TRT":    "",
      "GG_QUANT":  2,
      "GG_PERDA":  0,
      "GG_INI":    "20240101",
      "GG_FIM":    "20491231"
    },
    {
      "GG_COD":    "Z_TEST_PA",
      "GG_COMP":   "Z_TEST_MP2",
      "GG_TRT":    "",
      "GG_QUANT":  1,
      "GG_PERDA":  0,
      "GG_INI":    "20240101",
      "GG_FIM":    "20491231"
    }
  ]
}

Multinível (PA → PI → MP) — produto acabado PA001 com 1 PI intermediário e 2 matérias-primas; a árvore é inferida do par GG_COD + GG_COMP. Note como o terceiro item tem GG_COD="PI001" (PI vira pai do MP002).

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "GG_COD": "PA001",
    "GG_QUANT": 1
  },
  "itens": [
    {
      "GG_COD":   "PA001",
      "GG_COMP":  "PI001",
      "GG_QUANT": 1,
      "GG_INI":   "20240101",
      "GG_FIM":   "20491231"
    },
    {
      "GG_COD":   "PA001",
      "GG_COMP":  "MP001",
      "GG_QUANT": 2,
      "GG_INI":   "20240101",
      "GG_FIM":   "20491231"
    },
    {
      "GG_COD":   "PI001",
      "GG_COMP":  "MP002",
      "GG_QUANT": 1,
      "GG_INI":   "20240101",
      "GG_FIM":   "20491231"
    }
  ]
}

Respostas

201

Pré-estrutura criada. Envelope RespostaSucesso com data.codigo = GG_COD persistido.

400

Payload malformado (JSON inválido, cabecalho.GG_COD ausente, itens vazio). Tier: validation-error.

422

Produto pai/componente não existe em SB1, pré-estrutura já existe para o GG_COD, ou MsExecAuto do PCPA135 rejeitou (log via NomeAutoLog). Tier: business-error.

500

Erro interno (deserialização, falha de transação). Tier: business-error.

PUT /WsSGG/ALTERAR/{codigo} Altera pré-estrutura (delta) (PCPA135 Op=4)

Descrição

Operação delta: apenas os itens informados são processados. Cada item aceita o atributo opcional _acao:

incluir (default) — adiciona componente novo;
alterar — altera componente existente (gera LINPOS);
excluir — remove componente existente (gera LINPOS + AUTDELETA="S").

Pré-requisito de estado. Se a pré-estrutura não estiver em GG_STATUS "Em criação", o PCPA135 rejeita silenciosamente; o endpoint converte em 422 com o log do NomeAutoLog(). Estados Submetida / Aprovada / Rejeitada / Estrutura criada são bloqueados.

Consistência de LINPOS. Os valores GG_COD / GG_COMP / GG_TRT em alterar / excluir precisam casar exatamente com os do registro original — divergência falha silenciosamente.

Path parameter

codigo string · path · obrigatório SGG.GG_COD

GG_COD do produto pai cuja pré-estrutura será alterada.

Request body

application/json PreEstruturaAlteracao · obrigatório

cabecalho (referência ao pai) + itens[] contendo apenas os componentes a processar, com _acao opcional por item. Schema em PreEstruturaAlteracao.

Delta misto — altera MP1 (nova quantidade e perda), exclui MP2, adiciona MP3 num único PUT. Fixture: fixtures/put-delta.json.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": { "GG_COD": "Z_TEST_PA" },
  "itens": [
    {
      "GG_COD":    "Z_TEST_PA",
      "GG_COMP":   "Z_TEST_MP1",
      "GG_TRT":    "",
      "GG_QUANT":  5,
      "GG_PERDA":  1,
      "GG_INI":    "20240120",
      "GG_FIM":    "20491231",
      "_acao":     "alterar"
    },
    {
      "GG_COD":    "Z_TEST_PA",
      "GG_COMP":   "Z_TEST_MP2",
      "GG_TRT":    "",
      "_acao":     "excluir"
    },
    {
      "GG_COD":    "Z_TEST_PA",
      "GG_COMP":   "Z_TEST_MP3",
      "GG_TRT":    "",
      "GG_QUANT":  3,
      "GG_PERDA":  0,
      "GG_INI":    "20240120",
      "GG_FIM":    "20491231"
    }
  ]
}

Apenas inclusão — sem _acao, o default é incluir; o componente é adicionado à estrutura existente.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": { "GG_COD": "Z_TEST_PA" },
  "itens": [
    {
      "GG_COD":    "Z_TEST_PA",
      "GG_COMP":   "Z_TEST_MP4",
      "GG_QUANT":  1,
      "GG_INI":    "20240120",
      "GG_FIM":    "20491231"
    }
  ]
}

Respostas

200

Pré-estrutura alterada. Envelope RespostaSucesso.

400

Payload malformado, {codigo} ausente, itens vazio. Tier: validation-error.

404

Pré-estrutura inexistente para o GG_COD informado. Tier: not-found.

422

GG_STATUS não-editável (Submetida/Aprovada/etc.), LINPOS inconsistente, ou MsExecAuto do PCPA135 rejeitou. Tier: business-error.

500

Erro interno.

DEL /WsSGG/EXCLUIR/{codigo} Exclui pré-estrutura do produto pai (PCPA135 Op=5)

Descrição

Exclui todos os componentes do produto pai informado em {codigo} via PCPA135 em Op=5. Não é cascata — sub-árvores (PIs filhos com pré-estrutura própria) precisam ser excluídas em chamadas separadas. Use o GET para descobrir o que existe antes de excluir.

Path parameter

codigo string · path · obrigatório SGG.GG_COD

GG_COD do produto pai.

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Pré-estrutura excluída. Envelope simples com success/message/data.

400

{codigo} ausente. Tier: validation-error.

404

Pré-estrutura inexistente. Tier: not-found.

422

GG_STATUS bloqueia a exclusão ou MsExecAuto rejeitou. Tier: business-error.

500

Erro interno.

Listagem

Listagem paginada (1 linha por GG_COD pai)

GET /WsSGG/_list Lista pré-estruturas com filtros e paginação

Descrição

Retorna uma linha por GG_COD pai — apenas os cabeçalhos, sem expandir o array de componentes. Para descer ao nível dos itens, use GET /WsSGG/{codigo}. Suporta filtro de prefixo por cod e filtro exato por status (código de GG_STATUS).

Query parameters

cod string · query · opcional SGG.GG_COD

Prefixo de GG_COD (busca por início).

status string · query · opcional SGG.GG_STATUS

Código de GG_STATUS (combobox SX3).

12345

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

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

Request · filtro por statusHTTP/1.1 · sem body

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

Respostas

200

Página com cabeçalhos. Envelope RespostaListagem com data[], page, pageSize, count.

400

Parâmetro fora do domínio (pageSize > 500, page < 1).

500

Erro interno.

Schemas

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

Cabecalho

object

Capa enxuta da pré-estrutura. Em POST, GG_COD identifica o produto pai e GG_QUANT a quantidade-base; em PUT, a capa funciona como referência.

GG_CODstring · obrigatórioSGG.GG_COD

Código do produto pai (precisa existir em SB1).

GG_QUANTnumber · opcionalSGG.GG_QUANT

Quantidade base do produto pai (lote-padrão).

Item

object

Componente da pré-estrutura. O par GG_COD (pai) + GG_COMP (filho) determina a posição na árvore — produtos intermediários aparecem como componentes de seu pai e como pai de seus próprios componentes. Em PUT, o atributo _acao direciona a operação delta.

GG_CODstring · obrigatórioSGG.GG_COD

Pai do componente. Pode ser o produto acabado (PA) ou um intermediário (PI) — multinível.

GG_COMPstring · obrigatórioSGG.GG_COMP

Código do componente (filho). Precisa existir em SB1.

GG_TRTstring · opcionalSGG.GG_TRT

Sequência (3 chars). Em branco = sequência principal; valores distintos discriminam variantes do mesmo componente.

GG_QUANTnumber · opcionalSGG.GG_QUANT

Quantidade do componente (por unidade do pai).

GG_PERDAnumber · opcionalSGG.GG_PERDA

Percentual de perda esperada no consumo.

GG_INIstring · opcionalSGG.GG_INI

Data de início de vigência (AAAAMMDD).

GG_FIMstring · opcionalSGG.GG_FIM

Data de fim de vigência (AAAAMMDD).

GG_FIXVARstring · opcionalSGG.GG_FIXVAR

Consumo fixo (F) ou variável (V) em função da quantidade do pai.

FV

GG_GROPCstring · opcionalSGG.GG_GROPC

Grupo de opcionais (engenharia configurável).

GG_OPCstring · opcionalSGG.GG_OPC

Opcional dentro do grupo.

GG_LOCALstring · opcionalSGG.GG_LOCAL

Armazém-padrão de consumo do componente.

GG_FANTASMstring · opcionalSGG.GG_FANTASM

Indica componente fantasma (explode no MRP sem gerar empenho próprio).

_acaostring · opcional · PUT

Direciona o delta no PUT: incluir (default), alterar, excluir.

incluiralterarexcluir

PreEstruturaInclusao

object

Payload do POST. Contém capa + todos os itens da árvore, em formato plano. Mínimo 1 item.

cabecalhoCabecalho · obrigatório

Capa do produto pai — ver Cabecalho.

itensarray<Item> · obrigatório

Todos os componentes em todos os níveis. minItems: 1.

PreEstruturaAlteracao

object

Payload do PUT (delta). Mesma estrutura de PreEstruturaInclusao; apenas os itens informados são processados, e cada item pode trazer _acao.

cabecalhoCabecalho · obrigatório

Referência ao produto pai. GG_QUANT pode ser omitido.

itensarray<Item> · obrigatório

Apenas os componentes a processar, com _acao por item. minItems: 1.

RespostaPreEstrutura

object · envelope

Envelope retornado pelo GET /WsSGG/{codigo}. data.cabecalho traz a capa (com GG_STATUS) e data.itens[] os componentes.

successboolean · const: true

Sempre true em sucesso.

messagestring · opcional

Mensagem editorial.

data.cabecalhoCabecalho · opcional

Cabeçalho com GG_COD, GG_QUANT e GG_STATUS (combobox SX3).

data.itensarray<Item> · opcional

Todos os componentes do GG_COD informado.

RespostaListagem

object · envelope

Envelope retornado pelo GET /WsSGG/_list. Cada linha de data[] corresponde a um GG_COD pai (cabeçalho, sem componentes).

successboolean · const: true

Sempre true em sucesso.

messagestring · opcional

Mensagem editorial.

pageinteger · opcional

Página retornada.

pageSizeinteger · opcional

Tamanho da página.

countinteger · opcional

Quantidade de linhas retornadas nesta página.

data[]array · opcional

Cada item traz GG_COD, GG_QUANT e GG_STATUS.

RespostaSucesso

object · envelope

Envelope padrão de POST e PUT. data.codigo traz o GG_COD persistido.

successboolean · const: true

Sempre true em sucesso.

messagestring · opcional

Mensagem editorial de sucesso.

data.codigostring · opcional

GG_COD da pré-estrutura criada/alterada.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. Em 422 do PCPA135, message traz o conteúdo de NomeAutoLog() quando disponível.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

Mensagem editorial do erro (apresentável ao usuário final). Em 422 pode incluir o log do MsExecAuto.