rev1-2026-05-07 Protheus 12.1.33

PrevisaoVendas

CRUD de Previsão de Vendas (tabela SC4) via rotina automática MATA700. A chave de negócio é composta — C4_PRODUTO + C4_DATA — e ambos são obrigatórios em todas as rotas que tocam um registro específico. A data trafega no path sempre como string numérica de 8 dígitos (AAAAMMDD); a conversão para Date é feita internamente via SToD.

Bloqueio TOTVS: tabela SC4 — chave imutavel produto+data; sem MSBLQL nativo; bloqueio relevante esta em SB1 (produto).

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

Vinculação com o ERP

Tabela mestre SC4 Previsão de vendas

Rotina automática MATA700 MsExecAuto · array plano

Wrapper AdvPL U_MT700Exc src/lib/MAT/MT700EXC.prw

Operações & modos

POST modo 3 PUT modo 4 DEL modo 5

Dependências de ambiente

Cadastro

Produto (SB1)

C4_PRODUTO deve existir em SB1 com B1_FILIAL = xFilial("SB1"); MATA700 rejeita previsão para produto inexistente ou bloqueado.

Cadastro · opcional

Armazém (NNR)

C4_LOCAL default "01"; valor diferente exige armazém cadastrado em NNR.

Chave lógica

Composta produto+data

índice 1 = C4_FILIAL+C4_PRODUTO+C4_DATA; C4_DATA é imutável — alteração precisa enviar a mesma data do registro original.

Log

AutoLog desativado

lAutoErrNoFile := .T. evita escrita em disco; erros do MsExecAuto ficam acessíveis via NomeAutoLog.

Convenções

Chave composta na URL. As rotas que tocam um registro específico (GET, POST, PUT, DELETE) recebem dois path params: {produto} (código C4_PRODUTO) e {data} (string numérica de 8 dígitos no formato AAAAMMDD). Pontuação na data (-, /) é rejeitada com 400.

C4_DATA é imutável. A combinação C4_PRODUTO + C4_DATA é a chave lógica do registro. No PUT, a data enviada no path precisa ser idêntica à da inclusão; tentar "mover" a data equivale a criar uma previsão nova — use DELETE seguido de POST.

Sem cabeçalho/itens. Diferente de pedidos (SC5/SC6), MATA700 trabalha com um aArray plano único — não há estrutura mestre/detalhe. O payload é um JSON simples e o DELETE envia C4_PRODUTO + C4_DATA no array para que o MsExecAuto localize a chave correta (exigência da TDN MATA700).

Path params no body são ignorados. C4_PRODUTO e C4_DATA vêm sempre do path; se aparecerem no body de POST/PUT, são descartados silenciosamente — não há erro, mas tampouco efeito.

Paginação. /_list usa page/pageSize (default 50, máx 500). Filtro por cod aproveita o índice 1 (prefixo de C4_PRODUTO); a faixa dataIni/dataFim aplica-se sobre C4_DATA em scan filial.

Previsão

CRUD por produto + data

GET /WsPrevVenda/{produto}/{data} Consulta previsão por chave composta

Descrição

Retorna uma previsão pesquisada pela chave composta C4_PRODUTO + C4_DATA. Aplica filtro de filial (xFilial("SC4")) e respeita o whitelist CAMPOS_GET. O campo C4_DATA é serializado como string AAAAMMDD via DToS.

Path parameters

produto string · path · obrigatório SC4.C4_PRODUTO

Código do produto (SB1.B1_COD). Tamanho conforme TamSX3("C4_PRODUTO").

data string · path · obrigatório SC4.C4_DATA

Data da previsão no formato AAAAMMDD. Pattern: ^\d{8}$.

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Previsão encontrada. Envelope { success: true, data: Previsao }.

400

Produto vazio/excede TamSX3 ou data fora do pattern. Tier: validation-error.

404

Previsão inexistente para o par produto+data. Tier: not-found.

500

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

POST /WsPrevVenda/INCLUIR/{produto}/{data} Inclui nova previsão de vendas

Descrição

Inclui uma previsão nova via MATA700 em modo 3 (nOper=3). A chave lógica é composta: produto + data; ambos vêm do path. Tentar incluir um par já existente retorna 409.

Whitelist de campos: ver PrevisaoPayload.
C4_PRODUTO e C4_DATA no body são ignorados — sempre lidos do path.

Path parameters

produto string · path · obrigatório SC4.C4_PRODUTO

Código do produto. Deve existir em SB1.

data string · path · obrigatório SC4.C4_DATA

Data da previsão (AAAAMMDD). Pattern: ^\d{8}$.

Request body

application/json PrevisaoPayload · obrigatório

Payload plano com campos do whitelist CAMPOS_ALLOW. Schema completo em PrevisaoPayload.

Payload mínimo — apenas armazém, quantidade e valor. Fixture: fixtures/post.json.

RequestHTTP/1.1 · application/json

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

{
  "C4_LOCAL": "01",
  "C4_DOC": "PREV TESTE",
  "C4_QUANT": 10,
  "C4_VALOR": 100.50,
  "C4_OBS": "TESTE_PREP"
}

Payload com observação editorial — uso realista para integração com previsão consolidada de planejamento.

RequestHTTP/1.1 · application/json

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

{
  "C4_LOCAL": "01",
  "C4_DOC": "PCP-2026-Q2",
  "C4_QUANT": 250,
  "C4_VALOR": 12500.00,
  "C4_OBS": "Previsao consolidada plano comercial"
}

Respostas

201

Previsão incluída. Envelope CrudResponse com data = string vazia (a chave já é conhecida do path).

400

Produto inválido ou data fora do pattern AAAAMMDD. Tier: validation-error.

409

Par produto+data já existe na filial. Tier: business-error.

422

Payload rejeitado pelo MsExecAuto da MATA700 (produto inexistente em SB1, armazém inválido, regra de negócio). Tier: business-error.

500

Erro interno.

PUT /WsPrevVenda/ALTERAR/{produto}/{data} Altera previsão existente

Descrição

Altera campos de uma previsão existente via MATA700 em modo 4 (nOper=4). Aceita qualquer subconjunto do whitelist CAMPOS_ALLOW, exceto a chave lógica.

Atenção: C4_DATA é imutável. A data no path tem que ser a mesma da inclusão; tentar alterar para outra data exige DELETE + POST com nova chave.

Path parameters

produto string · path · obrigatório SC4.C4_PRODUTO

Código do produto.

data string · path · obrigatório SC4.C4_DATA

Data idêntica à do registro original (AAAAMMDD).

Request body

application/json PrevisaoPayload · obrigatório

Subconjunto do whitelist (quantidade, valor, observação, armazém).

Revisão de previsão — atualiza quantidade, valor e observação. Fixture: fixtures/put.json.

RequestHTTP/1.1 · application/json

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

{
  "C4_LOCAL": "01",
  "C4_DOC": "PREV TESTE",
  "C4_QUANT": 25,
  "C4_VALOR": 250.75,
  "C4_OBS": "TESTE_PREP_UPD"
}

Ajuste parcial — só corrige a quantidade sem mexer nos demais campos.

RequestHTTP/1.1 · application/json

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

{
  "C4_QUANT": 30
}

Respostas

200

Previsão alterada. Envelope CrudResponse.

400

Produto inválido ou data fora do pattern. Tier: validation-error.

404

Par produto+data inexistente. Tier: not-found.

422

Validação de payload (whitelist, enum) ou regra de negócio do MATA700. Tier: business-error.

500

Erro interno.

DEL /WsPrevVenda/EXCLUIR/{produto}/{data} Exclui previsão

Descrição

Exclui a previsão via MATA700 em modo 5 (nOper=5). O wrapper monta um aArray com C4_PRODUTO e C4_DATA — ambos exigidos pela TDN para que o MsExecAuto localize o registro correto.

Path parameters

produto string · path · obrigatório SC4.C4_PRODUTO

Código do produto.

data string · path · obrigatório SC4.C4_DATA

Data da previsão (AAAAMMDD).

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Previsão excluída. Envelope CrudResponse.

400

Produto ou data inválidos. Tier: validation-error.

404

Par produto+data inexistente. Tier: not-found.

422

Exclusão rejeitada pela MATA700 (dependências, regra de negócio). Tier: business-error.

500

Erro interno.

Listagem

Listagem paginada e typeahead

GET /WsPrevVenda/_list Lista previsões com filtros e paginação

Descrição

Lista previsões aplicando filtros opcionais por prefixo de C4_PRODUTO (índice 1) e faixa de C4_DATA. Quando cod não é informado o método cai em scan filial. fields permite reduzir o conjunto de campos retornados (validados contra CAMPOS_GET).

Query parameters

cod string · query · opcional SC4.C4_PRODUTO

Prefixo de C4_PRODUTO (usa índice 1 = filial+produto+data).

dataIni string · query · opcional SC4.C4_DATA

Data inicial da faixa (AAAAMMDD).

dataFim string · query · opcional SC4.C4_DATA

Data final da faixa (AAAAMMDD), inclusiva.

fields string · query · opcional

Lista de campos separados por vírgula, validados contra CAMPOS_GET.

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

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

Request · faixa de datasHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsPrevVenda/_list?dataIni=20260601&dataFim=20260630&fields=C4_PRODUTO,C4_DATA,C4_QUANT
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de previsões. Envelope com data (array de Previsao), page, pageSize, count.

400

Parâmetro fora do domínio (datas mal formadas, pageSize > 500).

500

Erro interno.

GET /WsPrevVenda/_search Typeahead por código de produto

Descrição

Busca rápida (typeahead) para autocomplete de UI. Faz prefix match sobre C4_PRODUTO (índice 1) e retorna uma lista enxuta — apenas cod, data e doc; não devolve o schema completo de Previsao.

Query parameters

q string · query · obrigatório

Termo de busca (prefixo de C4_PRODUTO). Mínimo 2 caracteres.

limit integer · query · opcional

Quantidade máxima (default 10, máx 25).

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsPrevVenda/_search?q=PA&limit=10
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lista enxuta de sugestões. Envelope: success, count, data[] com cod/data/doc.

400

q ausente ou com menos de 2 caracteres.

500

Erro interno.

Schemas

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

Previsao

object

Representação retornada pelos GETs (/{produto}/{data} e /_list). Os campos efetivamente retornados dependem de CAMPOS_GET e do filtro fields.

C4_PRODUTOstring · opcionalSC4.C4_PRODUTO

Código do produto (SB1.B1_COD); componente 1 da chave lógica.

C4_LOCALstring · opcionalSC4.C4_LOCAL

Armazém da previsão (NNR.NNR_CODIGO); default "01".

C4_DOCstring · opcionalSC4.C4_DOC

Identificação editorial da previsão (referência ao documento de planejamento).

C4_QUANTnumber · opcionalSC4.C4_QUANT

Quantidade prevista (unidade de medida do produto).

C4_VALORnumber · opcionalSC4.C4_VALOR

Valor monetário previsto.

C4_DATAstring (AAAAMMDD) · opcionalSC4.C4_DATA

Data da previsão; serializada como string AAAAMMDD via DToS. Componente 2 da chave lógica — imutável.

C4_OBSstring · opcionalSC4.C4_OBS

Observação livre (memo).

PrevisaoPayload

object

Payload plano aceito em POST e PUT. Whitelist definida em CAMPOS_ALLOW no .prw. C4_PRODUTO e C4_DATA aparecem no whitelist mas são ignorados quando vêm no body — valem sempre os valores do path.

C4_LOCALstring · opcionalSC4.C4_LOCAL

Armazém (NNR); default "01". MATA700 rejeita armazém inexistente.

C4_DOCstring · opcionalSC4.C4_DOC

Documento de planejamento associado (texto livre).

C4_QUANTnumber · opcionalSC4.C4_QUANT

Quantidade prevista (na unidade de medida do produto).

C4_VALORnumber · opcionalSC4.C4_VALOR

Valor monetário previsto.

C4_OBSstring · opcionalSC4.C4_OBS

Observação editorial / livre.

CrudResponse

object · envelope

Envelope padrão das respostas de POST / PUT / DELETE. Como a chave já vem do path, data tipicamente é string vazia.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

datastring | object · opcional

Auxiliar; em POST/PUT/DELETE de SC4 vem como string vazia (a chave é determinística pelo path).

Erro

object · envelope

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

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