rev1-2026-05-03 Protheus 12.1.33

ApontamentoProducao

Executa Apontamento de Produção (rotina automática MATA250, modo 3) sobre uma Ordem de Produção (SC2) e consulta os movimentos resultantes na SD3. Substitui a User Function legada U_GAIZ250. Operação irreversível pelo próprio MATA250 — só expõe POST (executar) e GETs read-only; não há PUT nem DELETE.

Bloqueio TOTVS: tabela de movimento (SD3 — apontamento), sem MSBLQL.

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

Vinculação com o ERP

Tabela mestre SD3 Movimentos internos (apontamento)

Tabelas relacionadas SC2 · SD4 · SB2/SBF OP · empenhos · saldos atualizados

Rotina automática MATA250 MsExecAuto · modo 3 (inclusão)

Wrapper AdvPL U_MT250Exc src/lib/MT250EXC.prw

Operações & modos

POST modo 3 sem PUT/DELETE

Origem legada U_GAIZ250 _incorporar/Execauto/GAIZ_MATA250.prw

Dependências de ambiente

Cadastro

Ordem de Produção (SC2)

OP cadastrada e aberta · C2_QUANT - C2_QUJE > 0
fonte da quantidade pendente, do produto e do local de apontamento

Bloqueio · condicional

Empenhos em SD4

regra herdada do GAIZ250 · OP com qualquer D4_QUANT > 0 rejeita apontamento (422)

Saldo

Estoque SB2 / SBF

saldo disponível para o produto da OP no local do apontamento · sem isso o MATA250 volta 422

Parâmetro

Tipo de movimento (TM)

resolução em ordem: payload tipoMovimento → header X-TipoMovimento → GetNewPar("GAIZ_MIAP","010")

Convenções

Ação irreversível. POST aciona o MATA250, que grava movimento na SD3, atualiza saldos em SB2/SBF e incrementa SC2.C2_QUJE. Não há endpoint de estorno aqui — para desfazer é necessária rotina dedicada (a identificar). Tratar como qualquer integração que altera estoque + produção: revisar payload antes de chamar e não rodar em PROD sem aprovação.

Identificador do documento. O D3_DOC gerado pelo MATA250 é o identificador externo. A consulta GET /WsApontamentoProducao/{doc} usa o índice 2 da SD3 (D3_FILIAL+D3_DOC+D3_COD+…) e retorna todas as linhas do documento. Para buscar uma linha específica use /_byid?tipo=recno|msuid&valor=….

Quantidade default = pendente. Quando qtd é omitido (ou 0), o endpoint aponta toda a quantidade pendente (C2_QUANT - C2_QUJE). Se informado, qtd precisa ser menor ou igual à pendente — fora disso retorna 422 com motivo explícito.

Resolução do tipo de movimento (TM). O D3_TM é decidido em três níveis (primeiro não-vazio vence): payload tipoMovimento → header HTTP X-TipoMovimento → parâmetro de ambiente GAIZ_MIAP (default "010"). O TM precisa existir cadastrado (SF5) e ser compatível com apontamento de produção.

Paginação e ordenação em /_list. orderBy=chave (default) usa page/pageSize agrupando por D3_DOC distintos. orderBy=recno usa cursor/nextCursor sobre RecNo da SD3 — útil para delta-sync incremental.

Colisão de alias com Desmontagem. O fonte se chama WSSD3P.prw (P = Produção) para não colidir com WSSD3 (Desmontagem), que também consome a SD3. O WSRESTFUL e o path REST permanecem em linguagem de negócio: WsApontamentoProducao e /WsApontamentoProducao.

ApontamentoProducao

Execução do MATA250 e consulta da SD3 resultante

POST /WsApontamentoProducao Executa apontamento (MATA250 modo 3)

Descrição

Aponta produção de uma OP existente em SC2 via MATA250 modo 3 (inclusão). O endpoint valida o payload (op, emissao; qtd opcional), confere se a OP está aberta e sem empenhos pendentes em SD4, monta o array do MsExecAuto e dispara via U_MT250Exc.

Sempre cria — não há update; pode ser chamado várias vezes na mesma OP até C2_QUJE = C2_QUANT.
Quando bem-sucedido, retorna a chave técnica do movimento gerado: doc (D3_DOC) e recno (RecNo da SD3).
O TM efetivo aparece em data.tipoMovimento na resposta.

Header opcional

X-TipoMovimento string (max 3) · header · opcional SD3.D3_TM

Override do TM (vence sobre o parâmetro GAIZ_MIAP mas perde para o campo tipoMovimento no payload).

Request body

application/json ApontamentoPayload · obrigatório

Schema completo em ApontamentoPayload.

Payload mínimo — só op e emissao; qtd omitida aponta toda a pendente. TM cai no default (GAIZ_MIAP = "010"). Fixture: fixtures/post-valid.json.

RequestHTTP/1.1 · application/json

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

{
  "op": "TST00001001001",
  "emissao": "20991231",
  "qtd": 1.0
}

Apontamento parcial com TM customizado — aponta 5 unidades (menor que a pendente) e força o D3_TM via payload.

RequestHTTP/1.1 · application/json

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

{
  "op": "TST00001001001",
  "emissao": "20991231",
  "qtd": 5.0,
  "tipoMovimento": "010"
}

Payload sem op — campo obrigatório ausente; o endpoint rejeita em 400 antes de tocar a SC2. Fixture: fixtures/post-no-op.json.

RequestHTTP/1.1 · application/json

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

{
  "emissao": "20991231",
  "qtd": 1.0
}

OP inexistente — payload válido sintaticamente mas a OP não existe na SC2; retorna 422 com motivo "OP … não encontrada em SC2". Fixture: fixtures/post-invalid-op.json.

RequestHTTP/1.1 · application/json

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

{
  "op": "ZZZZZZZZZZZZZZ",
  "emissao": "20991231",
  "qtd": 1.0
}

Respostas

201

Apontamento realizado. Envelope ExecResponse com data.doc, data.recno, data.tipoMovimento, data.quant.

400

Body ausente / JSON inválido / campo obrigatório faltando (op, emissao). Tier: validation-error.

422

OP inexistente, OP sem pendência, OP com empenhos em SD4, qtd maior que pendente, ou rejeição do MsExecAuto do MATA250 (TM inválido, sem saldo SB2/SBF, etc). Tier: business-error.

500

Erro interno (exception em Begin Sequence / Recover Using).

GET /WsApontamentoProducao/{doc} Consulta linhas SD3 do documento

Descrição

Retorna todas as linhas da SD3 com D3_DOC igual ao informado, dentro da filial corrente (xFilial("SD3")). Usa o índice 2 (D3_FILIAL+D3_DOC+D3_COD+…) e ignora linhas de outras filiais.

Path parameter

doc string · path · obrigatório SD3.D3_DOC

Documento de apontamento gerado pelo POST (D3_DOC). Padding interno via TamSX3("D3_DOC").

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Documento encontrado. Envelope com data.filial, data.doc, data.count e data.linhas[] (array de Linha).

400

Path doc ausente. Tier: validation-error.

404

Documento inexistente para a filial corrente. Tier: not-found.

500

Erro interno.

GET /WsApontamentoProducao/_list Lista documentos com filtros e paginação

Descrição

Lista documentos distintos de apontamento aplicando filtros opcionais (filial, doc, op, produto, emissao). Dois modos:

orderBy=chave (default) — agrupa por D3_DOC, paginação por page/pageSize.
orderBy=recno — varre por RecNo, retorna linhas com nextCursor para delta-sync.

Query parameters

filial string · query · opcional SD3.D3_FILIAL

Filial filtro (default: xFilial("SD3")).

doc string · query · opcional SD3.D3_DOC

Filtro por documento (exato ou prefix conforme posicionamento de índice).

op string · query · opcional SD3.D3_OP

Filtro por código da OP.

produto string · query · opcional SD3.D3_COD

Filtro por código do produto.

emissao string · query · opcional SD3.D3_EMISSAO

Data exata no formato YYYYMMDD. Pattern: ^\d{8}$.

page integer · query · opcional

Página (default 1, mínimo 1). Válida em orderBy=chave.

pageSize integer · query · opcional

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

orderBy string · query · opcional

Modo de ordenação. Default chave.

chaverecno

since integer · query · opcional

Início do delta-sync (ignora RecNo abaixo deste valor). Use com orderBy=recno.

cursor integer · query · opcional

Cursor retornado em nextCursor da página anterior (continuação por RecNo).

Chamada de exemplo

Request · paginação por chaveHTTP/1.1 · sem body

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

Request · delta-sync por recnoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsApontamentoProducao/_list?orderBy=recno&since=0&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Request · filtro compostoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsApontamentoProducao/_list?produto=PA0001&emissao=20991231
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de documentos. Envelope com data[] (array de ListItem), orderBy, page, pageSize, count, opcionalmente nextCursor (modo recno).

400

Parâmetro fora do domínio (orderBy inválido, emissao fora do pattern, pageSize > 500).

500

Erro interno.

GET /WsApontamentoProducao/_byid Consulta linha SD3 por id técnico (recno|msuid)

Descrição

Busca uma linha específica da SD3 por identificador técnico. Útil quando o consumidor persistiu o recno (ou msuid) retornado no POST e quer reconfirmar o registro sem reconstruir o documento. Aplica filtro de filial.

Query parameters

tipo string · query · obrigatório

Qual id técnico está sendo usado.

recnomsuid

valor string · query · obrigatório

Valor do id (inteiro positivo quando tipo=recno; string quando tipo=msuid).

Chamada de exemplo

Request · por recnoHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsApontamentoProducao/_byid?tipo=recno&valor=1234
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Request · por msuidHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsApontamentoProducao/_byid?tipo=msuid&valor=9f7a3e2c4b8d1a0e
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Linha encontrada. Envelope { success: true, data: Linha }.

400

tipo ausente / fora do enum, ou valor ausente / não-inteiro para tipo=recno.

404

Movimento não encontrado para o id informado, ou não visível pela filial corrente. Tier: not-found.

501

Busca por msuid requer D3_MSUID no dicionário do ambiente (campo opcional).

500

Erro interno.

Schemas

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

ApontamentoPayload

object

Payload do POST. Campos validados antes de qualquer toque em SC2/SD4.

opstring · obrigatórioSD3.D3_OP / SC2.C2_NUM

Código da OP em SC2. Padding interno via TamSX3("D3_OP").

emissaostring · obrigatórioSD3.D3_EMISSAO

Data da emissão no formato YYYYMMDD. Pattern: ^\d{8}$; precisa representar data válida.

qtdnumber · opcionalSD3.D3_QUANT

Quantidade a apontar. Omitido ou 0 = toda a pendente (C2_QUANT - C2_QUJE). Se informado, precisa ser ≤ pendente.

tipoMovimentostring (max 3) · opcionalSD3.D3_TM

Override do TM. Vence sobre header X-TipoMovimento e sobre o parâmetro GAIZ_MIAP.

ExecResponse

object · envelope

Envelope de sucesso do POST. data traz as chaves técnicas geradas pelo MATA250.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial ("Apontamento realizado com sucesso.").

data.filialstring · opcionalSD3.D3_FILIAL

Filial corrente onde o movimento foi gravado.

data.opstring · opcionalSD3.D3_OP

Código da OP apontada.

data.docstring · opcionalSD3.D3_DOC

Documento gerado pelo MATA250 — usar como identificador externo para o GET /{doc}.

data.produtostring · opcionalSD3.D3_COD

Produto apontado (vem da SC2).

data.quantnumber · opcionalSD3.D3_QUANT

Quantidade efetivamente apontada.

data.tipoMovimentostring · opcionalSD3.D3_TM

TM efetivo aplicado (após a resolução em 3 níveis).

data.recnointeger · opcional

RecNo da linha SD3 gerada — usar como id técnico em /_byid?tipo=recno.

Linha

object

Linha completa da SD3 retornada pelo GET /{doc} e pelo GET /_byid. Campos efetivamente serializados vêm de CAMPOS_GET_LIN + ids técnicos opcionais (CAMPOS_TEC_OPC) detectados pelo U_RestCamposOpc.

D3_FILIALstring · opcionalSD3.D3_FILIAL

Filial do movimento.

D3_DOCstring · opcionalSD3.D3_DOC

Documento de apontamento (identificador externo).

D3_OPstring · opcionalSD3.D3_OP

Ordem de produção origem.

D3_CODstring · opcionalSD3.D3_COD

Código do produto apontado.

D3_LOCALstring · opcionalSD3.D3_LOCAL

Armazém / local de estoque movimentado.

D3_QUANTnumber · opcionalSD3.D3_QUANT

Quantidade apontada na 1ª unidade de medida.

D3_QTSEGUMnumber · opcionalSD3.D3_QTSEGUM

Quantidade na 2ª unidade de medida (quando aplicável).

D3_TMstring · opcionalSD3.D3_TM

Tipo de movimento aplicado.

D3_EMISSAOstring · opcionalSD3.D3_EMISSAO

Data de emissão (YYYYMMDD).

D3_NUMSEQstring · opcionalSD3.D3_NUMSEQ

Sequência do movimento dentro do documento.

recnointeger · opcional

Id técnico do registro (RecNo da SD3).

msuidstring · opcionalSD3.D3_MSUID

Identificador universal — opcional, depende do dicionário do ambiente.

msuidtstring · opcionalSD3.D3_MSUIDT

Timestamp técnico associado.

ListItem

object

Item enxuto retornado pelo GET /_list. Nomes em camelCase (sem prefixo D3_) — mantém o shape estável para o consumidor enquanto o dicionário SX3 pode variar entre ambientes.

filialstring · opcionalSD3.D3_FILIAL

Filial do movimento.

docstring · opcionalSD3.D3_DOC

Documento de apontamento.

opstring · opcionalSD3.D3_OP

Ordem de produção.

codstring · opcionalSD3.D3_COD

Produto apontado.

localstring · opcionalSD3.D3_LOCAL

Armazém.

quantnumber · opcionalSD3.D3_QUANT

Quantidade apontada.

emissaostring · opcionalSD3.D3_EMISSAO

Data de emissão (YYYYMMDD).

tmstring · opcionalSD3.D3_TM

Tipo de movimento.

recnointeger · opcional

Id técnico da linha (RecNo).

msuidstring · opcionalSD3.D3_MSUID

Identificador universal (opcional).

msuidtstring · opcionalSD3.D3_MSUIDT

Timestamp técnico.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode trazer o log interno do MsExecAuto do MATA250 quando o erro vier do wrapper U_MT250Exc.

successboolean · const: false

Sempre false em erros.

messagestring · obrigatório

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

datastring · opcional

Detalhe técnico (ex: log do MATA250 / NomeAutoLog).