rev4-2026-05-14 Protheus 12.1.33

SolicitacaoCompras

CRUD de Solicitação de Compras (tabela SC1) via rotina automática MATA110. Tabela em modelo 2 — cabeçalho e itens convivem na mesma SC1 (não há SC2). O número C1_NUM é gerado pelo servidor no POST via GetSXENum + ConfirmSX8 e devolvido em data.numero.

Bloqueio TOTVS: tabela SC1 — solicitacao de compras, bloqueio relevante esta em SB1 (produto).

Vinculação com o ERP

Tabela mestre SC1 Solicitação de Compras (modelo 2 · capa + itens)

Rotina automática MATA110 MsExecAuto · ExecAuto clássico

Wrapper AdvPL U_MT110Exc src/lib/MAT/MT110EXC.prw

Operações & modos

POST modo 3 DEL modo 5 GET leitura nativa

Dependências de ambiente

Cadastro

Produto (validação de itens)

tabela SB1 · campo B1_COD
cada C1_PRODUTO no payload precisa existir em SB1 · validação via DbSeek antes do MsExecAuto

Sequência

Numeração SX8

GetSXENum("SC1","C1_NUM") + loop DbSeek + ConfirmSX8
o path param {numero} do POST é ignorado · RollBackSX8 em erro

Integração · condicional

SIGAGSP (gestão de aprovação)

rotina ADV0066 · disparada quando o módulo está ativo
aprovação por operação 7 do MATA110 falha silenciosamente com SIGAGSP — usar fluxo próprio do módulo

Comportamento · runtime

Dialog do MATA110

variável PARAMIXB5 · sempre .F. em REST
fixada no wrapper U_MT110Exc · qualquer caminho que abra MsgYesNo/UI é bloqueado

Convenções

Numeração automática. O C1_NUM é gerado pelo servidor no POST via GetSXENum e devolvido em data.numero. O path param {numero} do POST /WsSC1/INCLUIR/{numero} é placeholder ignorado — convencionalmente passa-se auto para deixar a intenção explícita. Para todas as outras rotas, {numero} é o C1_NUM real (6 chars).

Modelo 2 — cabeçalho e itens na mesma SC1. Não existe SC2. O cabeçalho é representado pelo primeiro registro encontrado via DbSeek(xFilial("SC1")+C1_NUM); os itens repetem o C1_NUM variando C1_ITEM. O GET retorna o envelope agrupado { cabecalho: {...}, itens: [...] }.

Forma do payload aCabec vs aItens. Quirk do MATA110 documentado no TDN: aCabec usa pares {campo, valor} sem o terceiro Nil; aItens usa o 3-tuplo clássico {campo, valor, Nil}. O wrapper U_MT110Exc faz a montagem correta — o consumidor REST só vê JSON.

Formato de datas. C1_EMISSAO e C1_DATPRF aceitam string AAAAMMDD (8 dígitos, sem hífen). Vazio em C1_EMISSAO assume dDataBase do AppServer.

Paginação da listagem. /_list usa page/pageSize (default 50, máx 500) e retorna uma linha por C1_NUM (capa). Para inspecionar os itens de uma SC específica, use GET /WsSC1/{numero}.

DELETE é destrutivo. DELETE /WsSC1/EXCLUIR/{numero} exclui a SC inteira (cabeçalho + todos os itens) via MATA110 em modo 5. SC já aprovada (C1_APROV diferente de em-branco/em-aprovação) ainda não é validada nesta versão (pendência rev2 — ver README).

SolicitacaoCompras

CRUD por C1_NUM

POST /WsSC1/INCLUIR/{numero} Inclui Solicitação de Compras

Descrição

Inclui uma nova SC via MATA110 em modo 3 (Inclusão). O C1_NUM é gerado pelo servidor (GetSXENum("SC1","C1_NUM") + loop com DbSeek até achar slot livre + ConfirmSX8) e devolvido em data.numero. O path param {numero} é placeholder ignorado — convenção é passar auto.

Whitelist de campos do cabeçalho: ver SCPayload.
Whitelist de campos de item: ver SCItem.
Cada C1_PRODUTO é validado em SB1 antes do MsExecAuto.
Dialog do MATA110 fica suprimido (PARAMIXB5 := .F.).

Path parameter

numero string · path · obrigatório (placeholder)

Placeholder; o C1_NUM real é gerado pelo servidor. Convenção: passe auto.

Request body

application/json SCPayload · obrigatório

Objeto com cabecalho (subconjunto de CAMPOS_CAB_ALLOW) e itens[] (mínimo 1, cada item subconjunto de CAMPOS_ITEM_ALLOW). Schema completo em SCPayload.

Payload mínimo — apenas C1_SOLICIT no cabeçalho e um item com C1_PRODUTO + C1_QUANT. Demais campos assumem default do dicionário. Fixture: fixtures/create.json.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "C1_SOLICIT": "TESTE_REST"
  },
  "itens": [
    { "C1_PRODUTO": "PROD001", "C1_QUANT": 1 },
    { "C1_PRODUTO": "PROD001", "C1_QUANT": 2.5 }
  ]
}

Payload realista — cabeçalho com emissão e data de necessidade; dois itens com armazém, centro de custo e descrição complementar.

RequestHTTP/1.1 · application/json

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

{
  "cabecalho": {
    "C1_SOLICIT": "Administrador",
    "C1_EMISSAO": "20260507",
    "C1_DATPRF": "20260514",
    "C1_OBS": "Solicitacao de teste via REST"
  },
  "itens": [
    {
      "C1_PRODUTO": "PROD001",
      "C1_QUANT": 10,
      "C1_LOCAL": "01",
      "C1_CC": "1010101",
      "C1_DATPRF": "20260514"
    },
    {
      "C1_PRODUTO": "PROD002",
      "C1_QUANT": 5,
      "C1_LOCAL": "01",
      "C1_DESCRI": "Descricao complementar"
    }
  ]
}

Respostas

201

SC incluída. Envelope CrudResponse com data.numero = C1_NUM gerado.

400

JSON mal formado, itens vazio ou ausente, ou campo fora do whitelist. Tier: validation-error.

422

Produto inexistente em SB1, ou MsExecAuto do MATA110 rejeitou (campo inválido, regras de negócio). Tier: business-error.

500

Erro interno (falha em GetSXENum, deserialização, etc).

GET /WsSC1/{numero} Consulta SC (cabeçalho + itens)

Descrição

Retorna a SC inteira a partir do C1_NUM. O cabeçalho é montado a partir do primeiro registro encontrado via DbSeek; os itens são iterados enquanto SC1->C1_NUM permanecer igual ao número solicitado. Os campos retornados seguem CAMPOS_CAB_GET e CAMPOS_ITEM_GET.

Path parameter

numero string · path · obrigatório SC1.C1_NUM

C1_NUM da SC (6 chars). Aceita string sem padding; o endpoint completa com espaços via PadR.

Cenario

Exemplo da requisicao (cenario ativo)

Consulta direta — retorna cabecalho + todos os itens da SC.

RequestHTTP/1.1 · sem body

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

Respostas

200

SC encontrada. Envelope SCDetalhe com data: { cabecalho, itens[] }.

400

numero vazio ou maior que o tamanho do campo. Tier: validation-error.

404

SC inexistente para o C1_NUM informado. Tier: not-found.

500

Erro interno (DbSeek, serialização).

DEL /WsSC1/EXCLUIR/{numero} Exclui SC inteira (cabeçalho + itens)

Descrição

Exclui a SC inteira (cabeçalho + todos os itens) via MATA110 em modo 5. A operação carrega aCabec = [ {"C1_NUM", numero} ] e aItens = [] — o ExecAuto resolve a remoção do conjunto.

Sem validação de aprovação nesta versão. A rejeição de SC já aprovada ainda não é tratada (próxima rev2 retornará 409). Hoje o MATA110 pode aceitar a exclusão dependendo do estado de C1_APROV.

Path parameter

numero string · path · obrigatório SC1.C1_NUM

C1_NUM da SC a excluir (6 chars).

Cenario

Exemplo da requisicao (cenario ativo)

Exclusao direta — remove SC inteira (cabecalho + itens) via MATA110 op=5.

RequestHTTP/1.1 · sem body

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

Respostas

200

SC excluída. Envelope CrudResponse com data vazio.

400

numero vazio ou maior que o tamanho do campo. Tier: validation-error.

404

SC inexistente. Tier: not-found.

422

MsExecAuto do MATA110 rejeitou (regras de negócio: itens em pedido, dependências). Tier: business-error.

500

Erro interno.

Listagem

Listagem paginada de cabeçalhos

GET /WsSC1/_list Lista SCs (capa) com filtros e paginação

Descrição

Lista SCs em formato compacto — uma linha por C1_NUM (capa). Suporta filtros por prefixo de número, solicitante e data de emissão. Para inspecionar os itens de uma SC, use GET /WsSC1/{numero}.

Query parameters

num string · query · opcional SC1.C1_NUM

Prefixo de C1_NUM.

solicit string · query · opcional SC1.C1_SOLICIT

Filtro por C1_SOLICIT (igualdade, case-insensitive).

emissao string · query · opcional SC1.C1_EMISSAO

Data de emissão exata. Formato AAAAMMDD.

page integer · query · opcional

Página (default 1, mínimo 1).

pageSize integer · query · opcional

Tamanho da página (default 50, máx 500).

Cenarios

Exemplo da requisicao (cenario ativo)

Paginacao simples — retorna primeira pagina de SCs (uma linha por C1_NUM).

RequestHTTP/1.1 · sem body

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

Filtros combinados — filtra por solicitante e data de emissao.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSC1/_list?solicit=Administrador&emissao=20260507&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de SCs. Envelope com data[] (capa com C1_NUM, C1_SOLICIT, C1_EMISSAO, ...), page, pageSize, count.

400

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

500

Erro interno.

Schemas

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

SCDetalhe

object · envelope

Envelope retornado por GET /WsSC1/{numero}. O campo data agrupa cabeçalho e itens da SC.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · opcional

Mensagem editorial de sucesso.

data.cabecalhoobject · obrigatório

Cabeçalho da SC, com campos de CAMPOS_CAB_GET (C1_NUM, C1_SOLICIT, C1_EMISSAO, C1_OBS, C1_FILENT, C1_DATPRF).

data.itensarray<object> · obrigatório

Itens da SC, cada um com campos de CAMPOS_ITEM_GET (C1_ITEM, C1_PRODUTO, C1_QUANT, C1_LOCAL, C1_OBS, C1_DATPRF, C1_CC, C1_DESCRI, C1_UM).

SCPayload

object

Payload aceito em POST /WsSC1/INCLUIR/{numero}. Cabeçalho com campos do whitelist CAMPOS_CAB_ALLOW e array de itens (mínimo 1) com campos do whitelist CAMPOS_ITEM_ALLOW. O C1_NUM é gerado pelo servidor — não inclua no payload.

cabecalhoobject · obrigatório

Objeto com campos do cabeçalho. Whitelist: C1_SOLICIT, C1_EMISSAO, C1_OBS, C1_FILENT, C1_DATPRF.

cabecalho.C1_SOLICITstring · opcionalSC1.C1_SOLICIT

Nome do solicitante (usuário ou apelido).

cabecalho.C1_EMISSAOstring · opcionalSC1.C1_EMISSAO

Data de emissão, formato AAAAMMDD. Default = dDataBase.

cabecalho.C1_OBSstring · opcionalSC1.C1_OBS

Observação livre do cabeçalho.

cabecalho.C1_FILENTstring · opcionalSC1.C1_FILENT

Filial de entrega.

cabecalho.C1_DATPRFstring · opcionalSC1.C1_DATPRF

Data de necessidade (cabeçalho). Formato AAAAMMDD.

itensarray<SCItem> · obrigatório (min 1)

Lista de itens da SC. Cada item segue o schema SCItem.

SCItem

object

Item da SC. Whitelist CAMPOS_ITEM_ALLOW. C1_PRODUTO e C1_QUANT são obrigatórios; demais aceitam default do dicionário.

C1_PRODUTOstring · obrigatórioSC1.C1_PRODUTO

Código do produto (B1_COD); o produto precisa existir em SB1.

C1_QUANTnumber · obrigatórioSC1.C1_QUANT

Quantidade solicitada (aceita decimal).

C1_LOCALstring · opcionalSC1.C1_LOCAL

Armazém. Default vem do dicionário (B1_LOCPAD) quando ausente.

C1_OBSstring · opcionalSC1.C1_OBS

Observação do item.

C1_DATPRFstring · opcionalSC1.C1_DATPRF

Data de necessidade do item. Formato AAAAMMDD.

C1_CCstring · opcionalSC1.C1_CC

Centro de custo (CTT_CUSTO).

C1_ITEMCTAstring · opcionalSC1.C1_ITEMCTA

Item contábil.

C1_OPstring · opcionalSC1.C1_OP

Ordem de Produção vinculada (se aplicável).

C1_DESCRIstring · opcionalSC1.C1_DESCRI

Descrição complementar do item.

C1_UMstring · opcionalSC1.C1_UM

Unidade de medida. Default vem de B1_UM do produto.

CrudResponse

object · envelope

Envelope padrão das respostas de POST e DELETE. data.numero traz o C1_NUM gerado (POST) ou string vazia (DELETE).

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso (ex: "Solicitacao de Compras incluida com sucesso.").

data.numerostring · opcional

Em POST, C1_NUM gerado (ex: "000001"). Em DELETE, vazio.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter o token interno da causa (ex: mensagem do NomeAutoLog do MATA110) para tratamento programático, quando aplicável.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

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

datastring · opcional

Token interno / detalhe técnico (ex: log do MsExecAuto).

Cenarios

Combinacoes documentadas (1 por example do openapi.yaml)

payload-minimo-1-item

POST /WsSC1/INCLUIR/{numero}

Inclusao minima: cabecalho so com C1_SOLICIT, um item com C1_PRODUTO + C1_QUANT. Demais campos assumem default do dicionario. Path {numero}=auto (placeholder; servidor gera C1_NUM via GetSXENum). Tier happy-path-minimal.

payload-completo-multi-itens

POST /WsSC1/INCLUIR/{numero}

Inclusao realista com cabecalho expandido (emissao, data de necessidade, observacao) + 2 itens (armazem, centro de custo, descricao). Tier happy-path-realistic.

consulta-direta

GET /WsSC1/{numero}

Consulta por C1_NUM; retorna envelope SCDetalhe com cabecalho + array de itens.

delete-direto

DELETE /WsSC1/EXCLUIR/{numero}

Exclui SC inteira (cabecalho + todos os itens) via MATA110 op=5. Validacao de aprovacao pendente (ver Pendencias).

listagem-paginada

GET /WsSC1/_list?page=...&pageSize=...

Paginacao classica; retorna uma linha por C1_NUM (capa). Default 50, max 500.

listagem-filtrada

GET /WsSC1/_list?solicit=...&emissao=...

Filtros combinados (solicit, emissao AAAAMMDD); util para inbox por solicitante. Sem orderBy=recno nesta versao.

Pendências conhecidas (rev4)

DELETE em SC aprovada nao e validado. Nesta versao, MATA110 op=5 pode aceitar a exclusao mesmo com C1_APROV preenchido. Proxima rev devera retornar 409 quando a SC ja passou por aprovacao.

Aprovacao via op=7 incompativel com SIGAGSP. Em ambientes com o modulo de Gestao de Aprovacao ativo, o MATA110 op=7 (aprovar) falha silenciosamente. Usar fluxo proprio do ADV0066 / SIGAGSP — endpoint REST de aprovacao nao esta implementado nesta versao.

PUT nao implementado. Alteracao de capa ou de item exige reabrir a SC; nesta versao o caminho suportado e DELETE + POST. Considerar PUT incremental em rev futura.

Sem _byid nem _search. Lookup por recno/msuid e typeahead nao estao implementados. Use _list com filtros.

Bloqueio SB1 nao validado. Cada C1_PRODUTO passa por DbSeek em SB1 (existencia), mas nao por U_C980Blq("SB1") — produto bloqueado pode entrar em SC. O MsExecAuto do MATA110 pode ou nao rejeitar dependendo de regras locais.

Sem delta-sync na listagem. _list nao expoe orderBy=recno/cursor/since nesta versao — paginacao apenas por page/pageSize.