rev1-2026-05-03 Protheus 12.1.33

ApontamentoMaoObra

Execução de Apontamento de Mão de Obra / Tempo (rotina automática MATA681) e consulta dos apontamentos resultantes na tabela SH6. Substitui a User Function legada U_GAIZ681 (_incorporar/Execauto/GAIZ_MATA681.prw) por um endpoint REST no padrão da biblioteca, na forma ação + read-only: apenas POST de execução e três rotas GET de consulta — sem PUT nem DELETE, porque apontamento é movimento irreversível pelo próprio MATA681.

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

Convenções

Ação irreversível. O POST dispara MATA681, que grava em SH6 e atualiza SC2 (C2_QUJE/C2_QUREFUG). Não há rotina de estorno automática nesta revisão (ver PROXIMOS-PASSOS.md §8). Por esta razão o endpoint não expõe PUT nem DELETE — só execução e consulta. Para "desfazer" um apontamento equivocado é necessário rodar a rotina inversa manualmente no ERP.

Quatro modos de apontamento. O campo tipo (1..4) seleciona o modo, herdado sem alteração semântica do legado GAIZ681:

tipo=1 — normal (default): horaIni + horaFin + qtd + perda.
tipo=2 — tempo com horas e datas: horaIni + horaFin (sem quantidade).
tipo=3 — tempo total: tempo (string HH:MM; sem horas individuais).
tipo=4 — apenas quantidade: qtd (datas para auditoria).

Quando tipo é omitido, assume 1.

Marker H6_OBSERVA. O legado preenchia H6_OBSERVA = "GMATA681|<ident>|<seq>" para permitir reconciliação posterior. Comportamento preservado: o endpoint aceita ident e seq opcionais no payload e monta o marker. Se ambos ausentes, vira "GMATA681||".

Formato de datas e horas. emissao é string YYYYMMDD de 8 dígitos (pattern ^\d{8}$) — preenche H6_DTAPONT/H6_DATAINI/H6_DATAFIN. horaIni/horaFin/tempo são strings HH:MM. Não há conversão ISO — o formato é o mesmo do dicionário Protheus.

Paginação e delta-sync. /_list usa page/pageSize (default 50, máx 500). Para sincronização incremental, alterne para orderBy=recno e use since/cursor conforme o nextCursor retornado.

Identificador externo. A rota /WsApontamentoMaoObra/{op} usa o número da Ordem de Produção (H6_OP) como chave. Para resolver uma linha específica de SH6 use /_byid?tipo=recno&valor=… (msuid ainda não está disponível no padrão atual da tabela — retorna 501).

Apontamento

Execução do MATA681 (movimento irreversível)

POST /WsApontamentoMaoObra Executa apontamento de mão de obra (MATA681)

Descrição

Executa MsExecAuto sobre MATA681. O wrapper U_MT681Exc aplica Pergunte("MTA680",.F.) antes da chamada, neutralizando o grupo de perguntas interativo. O modo do apontamento é controlado pelo campo tipo (1..4) — ver Convenções.

Pré-checks aplicados antes do MsExecAuto:

Produto (SB1) existe e não está bloqueado (B1_MSBLQL).
Operação (SG2) existe para o produto.
Recurso (SH1) cadastrado.
Ordem de Produção (SC2) existente, em aberto e com saldo.
Local (SBE) cadastrado — só quando local é informado.

Request body

application/json ApontamentoPayload · obrigatório

Payload plano com op, produto, operacao, recurso, emissao obrigatórios. Campos opcionais variam conforme tipo — ver ApontamentoPayload.

Tipo 1 — apontamento normal — datas, horas, quantidade e perda. Fixture: fixtures/post-tipo1-valid.json.

RequestHTTP/1.1 · application/json

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

{
  "tipo": 1,
  "op": "TST00100101",
  "produto": "PA001",
  "operacao": "10",
  "recurso": "REC001",
  "emissao": "20991231",
  "horaIni": "08:00",
  "horaFin": "10:00",
  "qtd": 1.0,
  "perda": 0.0,
  "local": "01",
  "ident": "TST",
  "seq": "0001"
}

Tipo 2 — tempo com horas e datas — apenas faixa horária, sem quantidade. Fixture: fixtures/post-tipo2-valid.json.

RequestHTTP/1.1 · application/json

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

{
  "tipo": 2,
  "op": "TST00100101",
  "produto": "PA001",
  "operacao": "10",
  "recurso": "REC001",
  "emissao": "20991231",
  "horaIni": "08:00",
  "horaFin": "12:00",
  "ident": "TST",
  "seq": "0002"
}

Tipo 3 — tempo total — usa tempo agregado (HH:MM), sem horas individuais. Fixture: fixtures/post-tipo3-valid.json.

RequestHTTP/1.1 · application/json

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

{
  "tipo": 3,
  "op": "TST00100101",
  "produto": "PA001",
  "operacao": "10",
  "recurso": "REC001",
  "emissao": "20991231",
  "tempo": "04:00",
  "ident": "TST",
  "seq": "0003"
}

Tipo 4 — apenas quantidade — sem horas; datas servem só para auditoria. Fixture: fixtures/post-tipo4-valid.json.

RequestHTTP/1.1 · application/json

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

{
  "tipo": 4,
  "op": "TST00100101",
  "produto": "PA001",
  "operacao": "10",
  "recurso": "REC001",
  "emissao": "20991231",
  "qtd": 0.5,
  "perda": 0.0,
  "ident": "TST",
  "seq": "0004"
}

Respostas

201

Apontamento realizado. Envelope ExecResponse com a chave técnica da SH6 (recno) e flag pt (P=Parcial, T=Total).

400

Payload mal formado / campo obrigatório ausente / emissao fora do pattern ^\d{8}$. Tier: validation-error.

422

Regra de negócio: OP inexistente / fechada / sem saldo, Produto bloqueado, Operação inválida para o produto, Recurso inexistente, Local inexistente. Tier: business-error. Fixtures negativas: post-no-op.json, post-op-fechada.json.

500

Falha do MsExecAuto não classificada (stack do AutoLog em data).

Consulta

Leitura da SH6 — por OP, por filtro paginado, por id técnico

GET /WsApontamentoMaoObra/{op} Consulta apontamentos SH6 da OP

Descrição

Retorna todos os apontamentos (linhas SH6) registrados para a OP informada. Útil para auditar quanto já foi apontado em uma Ordem de Produção, conferir C2_QUJE versus C2_QUANT, ou reconciliar markers H6_OBSERVA.

Path parameter

op string · path · obrigatório SH6.H6_OP

Número da Ordem de Produção (C2_NUM+C2_ITEM+C2_SEQUEN).

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

OP encontrada. Envelope { success: true, data: { filial, op, count, linhas[] } } — cada linha conforme Linha.

400

Path op ausente. Tier: validation-error.

404

Nenhum apontamento encontrado para a OP. Tier: not-found.

GET /WsApontamentoMaoObra/_list Lista apontamentos com filtros e paginação

Descrição

Lista apontamentos com filtros opcionais por filial, op, produto, recurso. Suporta dois modos de ordenação:

orderBy=chave (default) — paginação por page/pageSize.
orderBy=recno — delta-sync, usa since/cursor com nextCursor retornado.

Retorna o schema enxuto ListItem (campos lowercased) — para o registro SH6 completo use /_byid ou /{op}.

Query parameters

filial string · query · opcional SH6.H6_FILIAL

Filtro de filial. Default = xFilial("SH6").

op string · query · opcional SH6.H6_OP

Ordem de Produção exata.

produto string · query · opcional SH6.H6_PRODUTO

Código de produto (B1_COD).

recurso string · query · opcional SH6.H6_RECURSO

Código de recurso (SH1).

page integer · query · opcional

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

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 (válido com orderBy=recno).

cursor integer · query · opcional

Cursor retornado em nextCursor de página anterior.

Chamada de exemplo

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

GET https://erpapi.jetme.com.br/api/99/01/WsApontamentoMaoObra/_list?op=TST00100101&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/WsApontamentoMaoObra/_list?orderBy=recno&since=0&pageSize=200
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de apontamentos. Envelope com data (array de ListItem), page, pageSize, count, opcionalmente nextCursor.

400

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

GET /WsApontamentoMaoObra/_byid Consulta linha SH6 por id técnico (recno|msuid)

Descrição

Busca uma linha específica da SH6 por id técnico — útil para integrações que persistem recno (ou msuid quando disponível na release) e querem reconfirmar o registro sem reconstruir a chave de negócio.

Disponibilidade: msuid requer índice/coluna específica que pode não estar presente na release atual — retorna 501 nesse caso. recno sempre disponível.

Query parameters

tipo string · query · obrigatório

Indica qual id técnico está sendo usado.

recnomsuid

valor string · query · obrigatório

Valor do id (inteiro 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/WsApontamentoMaoObra/_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/WsApontamentoMaoObra/_byid?tipo=msuid&valor=9f7a3e2c4b8d1a0e
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

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

400

Parâmetros tipo/valor ausentes ou tipo fora do enum.

404

Linha não localizada. Tier: not-found.

501

Busca por msuid requer índice/coluna não disponível no ambiente.

500

Erro interno.

Schemas

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

ApontamentoPayload

object

Payload aceito em POST /WsApontamentoMaoObra. Obrigatórios: op, produto, operacao, recurso, emissao. Demais campos variam conforme o valor de tipo — ver Convenções.

tipointeger · opcional

Modo do apontamento. Default 1. 1=normal · 2=tempo com horas · 3=tempo total · 4=apenas qtd.

1234

opstring · obrigatórioSH6.H6_OP

Número da Ordem de Produção (C2_NUM+C2_ITEM+C2_SEQUEN).

produtostring · obrigatórioSH6.H6_PRODUTO

Código do produto acabado / semiacabado (chave do SB1).

operacaostring · obrigatórioSH6.H6_OPERAC

Operação do roteiro (SG2 índice 3: filial+produto+operação).

recursostring · obrigatórioSH6.H6_RECURSO

Código do recurso (SH1) — máquina, posto, célula.

emissaostring · obrigatórioSH6.H6_DTAPONT

Data do apontamento no formato YYYYMMDD (8 dígitos). Pattern ^\d{8}$. Preenche também H6_DATAINI e H6_DATAFIN.

horaInistring · opcionalSH6.H6_HORAINI

Hora de início (HH:MM). Obrigatório em tipo=1 e tipo=2.

horaFinstring · opcionalSH6.H6_HORAFIN

Hora de fim (HH:MM). Obrigatório em tipo=1 e tipo=2.

tempostring · opcionalSH6.H6_TEMPO

Tempo total agregado (HH:MM). Obrigatório em tipo=3.

qtdnumber · opcionalSH6.H6_QTDPROD

Quantidade produzida. Obrigatório > 0 em tipo=1 e tipo=4.

perdanumber · opcionalSH6.H6_QTDPERD

Quantidade de perda. Default 0.

localstring · opcionalSH6.H6_LOCAL

Local de estoque (SBE). Quando informado, é validado no pré-check.

identstring · opcional

Identificador externo para o marker H6_OBSERVA = "GMATA681|<ident>|<seq>". Útil para reconciliar com sistemas externos.

seqstring · opcional

Sequência do marker (ver PROXIMOS-PASSOS.md §8 — geração automática planejada).

Linha

object

Representação completa de uma linha de SH6 — retornada nos GETs /{op} e /_byid. Composição allOf = campos H6_* + ids técnicos (recno, msuid, msuidt).

H6_FILIALstring · opcionalSH6.H6_FILIAL

Filial do apontamento.

H6_OPstring · opcionalSH6.H6_OP

Ordem de Produção.

H6_PRODUTOstring · opcionalSH6.H6_PRODUTO

Produto apontado.

H6_OPERACstring · opcionalSH6.H6_OPERAC

Operação do roteiro.

H6_RECURSOstring · opcionalSH6.H6_RECURSO

Recurso utilizado.

H6_DATAINIstring · opcionalSH6.H6_DATAINI

Data inicial do apontamento.

H6_HORAINIstring · opcionalSH6.H6_HORAINI

Hora inicial (HH:MM).

H6_DATAFINstring · opcionalSH6.H6_DATAFIN

Data final.

H6_HORAFINstring · opcionalSH6.H6_HORAFIN

Hora final (HH:MM).

H6_TEMPOstring · opcionalSH6.H6_TEMPO

Tempo total apontado.

H6_QTDPRODnumber · opcionalSH6.H6_QTDPROD

Quantidade produzida.

H6_QTDPERDnumber · opcionalSH6.H6_QTDPERD

Quantidade de perda.

H6_PTstring · opcionalSH6.H6_PT

Status do apontamento. P=Parcial · T=Total (encerra a operação).

H6_DTAPONTstring · opcionalSH6.H6_DTAPONT

Data do apontamento (referência).

H6_OPERADOstring · opcionalSH6.H6_OPERADO

Operador / responsável.

H6_LOCALstring · opcionalSH6.H6_LOCAL

Local de estoque.

H6_OBSERVAstring · opcionalSH6.H6_OBSERVA

Marker editorial — formato "GMATA681|<ident>|<seq>" quando vindo deste endpoint.

recnointeger · opcional

Id técnico da linha (RecNo do AdvPL na SH6).

msuidstring · opcional

Identificador universal MS_UID (quando disponível na release).

msuidtstring · opcional

Timestamp técnico associado ao msuid.

ListItem

object

Schema enxuto usado em /_list. Campos lowercased (sem prefixo H6_) para reduzir payload em listagens longas. Para o registro completo da SH6 use Linha.

filialstring · opcionalSH6.H6_FILIAL

Filial.

opstring · opcionalSH6.H6_OP

Ordem de Produção.

produtostring · opcionalSH6.H6_PRODUTO

Produto.

operacstring · opcionalSH6.H6_OPERAC

Operação do roteiro.

recursostring · opcionalSH6.H6_RECURSO

Recurso.

qtdprodnumber · opcionalSH6.H6_QTDPROD

Quantidade produzida.

qtdperdnumber · opcionalSH6.H6_QTDPERD

Quantidade de perda.

tempostring · opcionalSH6.H6_TEMPO

Tempo total apontado.

dtapontstring · opcionalSH6.H6_DTAPONT

Data do apontamento.

observastring · opcionalSH6.H6_OBSERVA

Marker editorial ("GMATA681|...").

recnointeger · opcional

Id técnico da linha.

msuidstring · opcional

MS_UID (quando disponível).

msuidtstring · opcional

Timestamp do MS_UID.

ExecResponse

object · envelope

Envelope padrão da resposta do POST. data traz o resumo do apontamento gerado (chave da SH6 + flag parcial/total), suficiente para o cliente referenciar a linha sem novo GET.

successboolean · const: true

Sempre true em resposta de sucesso.

messagestring · obrigatório

Mensagem editorial ("Apontamento realizado").

data.filialstring · opcional

Filial onde o apontamento foi gravado.

data.opstring · opcional

OP apontada.

data.produtostring · opcional

Produto.

data.operacstring · opcional

Operação.

data.recursostring · opcional

Recurso.

data.tipointeger · opcional

Modo do apontamento usado.

1234

data.ptstring · opcional

Parcial (P) ou Total (T). T indica encerramento da operação na SC2.

PT

data.recnointeger · opcional

Id técnico da linha SH6 recém-gerada — pode ser usado em /_byid?tipo=recno&valor=….

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter o NomeAutoLog do MsExecAuto (stack do MATA681) quando aplicável, útil para diagnóstico 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: stack do NomeAutoLog).