rev1-2026-05-07 Protheus 12.1.33

PesquisaLotes

Inclusão, consulta e exclusão de lotes (tabela SD5) via rotina automática MATA390. O identificador externo é composto por D5_PRODUTO + D5_LOTECTL, ambos vindos do path da URL. PUT (alteração de validade) não é suportado nesta versão — ver Convenções.

Bloqueio TOTVS: tabela SD5 — lotes, nesta base sem MSBLQL.

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

Vinculação com o ERP

Tabela mestre SD5 Saldos por Lote

Rotina automática MATA390 ExecAuto · inclusão e exclusão manual

Wrapper AdvPL U_MT390Exc src/lib/MT390EXC.prw

Operações & modos

POST op 3 DEL op 5 PUT n/d

Dependências de ambiente

Cadastro

Produto rastreado por lote

tabela SB1 · campo B1_RASTRO = "L" (Lote)
inclusão em produto sem rastro é rejeitada pelo próprio MATA390

Índice

SD5 ordem 1

chave D5_FILIAL+D5_PRODUTO+D5_LOTECTL+D5_NUMSERI+D5_LOCAL+…
seek soft + iteração filtrando produto/lote (D5_NUMSERI não usado em rastro tipo Lote)

Restrição · MATA390

Exclusão somente manual

apenas lotes incluídos manualmente podem ser excluídos
lote gerado por movimentação retorna 422 com mensagem do lMsErroAuto

Convenções

Identificador externo composto. Todas as rotas de manutenção usam dois segmentos no path: {produto} = D5_PRODUTO e {lote} = D5_LOTECTL. Os tamanhos seguem o TamSX3 do dicionário. Se enviados também no body, são ignorados — o path sempre vence.

PUT (alteração) não é suportado. O TDN do MATA390 menciona a possibilidade de alterar D5_DTVALID pela rotina padrão, mas o exemplo formal de ExecAuto só cobre op=3 (inclusão). A frente será revisitada quando houver demanda real, com log do AppServer capturando a rotina padrão em modo alteração para parear via ExecAuto.

Exclusão restrita a lotes manuais. Lotes gerados por movimentação de estoque (entrada, produção, etc) não podem ser excluídos pelo MATA390 — o MsExecAuto retorna falha e o endpoint responde 422 com a mensagem propagada de aRet[2].

Formato de datas no payload. D5_DATA e D5_DTVALID entram como string no formato AAAAMMDD (8 dígitos, sem separadores). No GET são serializados pela mesma representação compacta retornada pelo dicionário SX3.

Paginação. /_list usa page/pageSize (default 50, máx 500). Não há cursor de delta-sync nesta versão; o índice 1 do SD5 inclui D5_NUMSERI, o que torna scan incremental por recno menos previsível — usar página direta.

Lote

CRUD por (D5_PRODUTO, D5_LOTECTL)

GET /WsLote/{produto}/{lote} Consulta lote por produto + lote

Descrição

Retorna o lote pesquisado por D5_PRODUTO + D5_LOTECTL. Aplica filtro de filial (xFilial("SD5")) e respeita o whitelist de CAMPOS_GET definido no .prw. O parâmetro opcional fields reduz o conjunto de campos retornados.

Path parameters

produto string · path · obrigatório SD5.D5_PRODUTO

Código do produto. Tamanho conforme TamSX3("D5_PRODUTO") (até 15).

lote string · path · obrigatório SD5.D5_LOTECTL

Código do lote. Tamanho conforme TamSX3("D5_LOTECTL") (até 10).

Query parameter

fields string · query · opcional

Lista de campos separados por vírgula. Validados contra CAMPOS_GET.

Chamada de exemplo

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsLote/LOTETEST01/_TEST_001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Request · com fieldsHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsLote/LOTETEST01/_TEST_001?fields=D5_PRODUTO,D5_LOTECTL,D5_QUANT,D5_DTVALID
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lote encontrado. Envelope { success: true, data: Lote }.

400

Produto/lote ausentes ou maiores que o TamSX3. Tier: validation-error.

404

Lote inexistente para o par informado. Tier: not-found.

500

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

POST /WsLote/INCLUIR/{produto}/{lote} Inclui lote (MATA390 op=3)

Descrição

Inclui um novo lote via MATA390 em modo 3 (inclusão). As chaves D5_PRODUTO e D5_LOTECTL vêm do path; o body traz os campos auxiliares do whitelist CAMPOS_ALLOW.

Whitelist de campos: ver LotePayload.
Produto precisa existir no SB1 com B1_RASTRO="L"; caso contrário, o próprio MATA390 rejeita e devolvemos 422.
Se já existir um lote com o par (produto, lote), o endpoint responde 409 antes de chamar o ExecAuto.

Path parameters

produto string · path · obrigatório SD5.D5_PRODUTO

Código do produto (até 15 chars).

lote string · path · obrigatório SD5.D5_LOTECTL

Código do lote (até 10 chars).

Request body

application/json LotePayload · obrigatório

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

Payload mínimo — campos típicos de saldo inicial por lote. Fixture: fixtures/create.json.

RequestHTTP/1.1 · application/json

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

{
  "D5_LOTEFOR": "TST001",
  "D5_LOCAL": "01",
  "D5_DOC": "000000001",
  "D5_SERIE": "UNI",
  "D5_DATA": "20260507",
  "D5_QUANT": 100,
  "D5_DTVALID": "20281231"
}

Respostas

201

Lote incluído. Envelope CrudResponse com data = { D5_PRODUTO, D5_LOTECTL }.

400

Produto/lote inválidos ou body JSON ausente/inválido. Tier: validation-error.

409

Lote já cadastrado para este produto. Tier: business-error.

422

Rejeitado pelo MsExecAuto do MATA390 (produto sem rastro, local inválido, data fora do calendário etc). Tier: business-error.

500

Erro interno.

DEL /WsLote/EXCLUIR/{produto}/{lote} Exclui lote manual

Descrição

Exclui o lote via MATA390 em modo 5. Apenas lotes incluídos manualmente podem ser excluídos — o MsExecAuto rejeita qualquer lote gerado por movimentação de estoque, e a mensagem original do lMsErroAuto é propagada no envelope de erro.

Path parameters

produto string · path · obrigatório SD5.D5_PRODUTO

Código do produto.

lote string · path · obrigatório SD5.D5_LOTECTL

Código do lote.

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Lote excluído. Envelope CrudResponse.

400

Produto/lote inválidos. Tier: validation-error.

404

Lote inexistente. Tier: not-found.

422

Lote gerado por movimentação (não manual), ou dependências impedem a exclusão. Mensagem propagada do MATA390. Tier: business-error.

500

Erro interno.

Listagem

Listagem paginada e typeahead

GET /WsLote/_list Lista lotes com filtros e paginação

Descrição

Lista lotes com filtros por prod (D5_PRODUTO prefix), loteq (D5_LOTECTL prefix) e local (D5_LOCAL exato). Quando prod é informado, o seek usa esse prefixo no índice 1; sem ele, varre a filial.

Query parameters

prod string · query · opcional SD5.D5_PRODUTO

Prefixo de D5_PRODUTO (índice 1).

loteq string · query · opcional SD5.D5_LOTECTL

Prefixo de D5_LOTECTL.

local string · query · opcional SD5.D5_LOCAL

Código de local de estoque (filtro exato).

fields string · query · opcional

Lista de campos 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 · por produtoHTTP/1.1 · sem body

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

Request · filtro por localHTTP/1.1 · sem body

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

Respostas

200

Página de lotes. Envelope com data (array de Lote), page, pageSize e count.

400

Parâmetro fora do domínio (ex: fields com campo não whitelistado, pageSize > 500).

500

Erro interno.

GET /WsLote/_search Typeahead por D5_LOTECTL

Descrição

Busca rápida (typeahead) para autocomplete de UI. Retorna uma lista enxuta (produto, lote, local) — não devolve o schema completo de Lote. Com prod informado, usa prefixo do índice 1 e exige match exato no produto; sem prod, faz scan da filial com contains em D5_LOTECTL (cap interno de 2000 registros).

Query parameters

q string · query · obrigatório

Termo de busca em D5_LOTECTL. Mínimo 2 caracteres.

prod string · query · opcional SD5.D5_PRODUTO

Filtra por D5_PRODUTO exato.

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/WsLote/_search?q=_TEST&prod=LOTETEST01&limit=10
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lista enxuta de sugestões. Envelope: success, count, data[] com produto/lote/local.

400

q ausente ou < 2 caracteres.

500

Erro interno.

Schemas

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

Lote

object

Representação retornada nos GETs (/{produto}/{lote} e /_list). Campos efetivamente retornados dependem de CAMPOS_GET e do filtro fields.

D5_PRODUTOstring · opcionalSD5.D5_PRODUTO

Código do produto rastreado.

D5_LOTECTLstring · opcionalSD5.D5_LOTECTL

Código do lote.

D5_LOTEFORstring · opcionalSD5.D5_LOTEFOR

Lote do fornecedor (identificador externo do parceiro).

D5_LOCALstring · opcionalSD5.D5_LOCAL

Local de estoque (almoxarifado).

D5_DOCstring · opcionalSD5.D5_DOC

Documento de origem.

D5_SERIEstring · opcionalSD5.D5_SERIE

Série do documento.

D5_DATAstring · opcionalSD5.D5_DATA

Data do movimento (formato AAAAMMDD).

D5_QUANTstring · opcionalSD5.D5_QUANT

Quantidade do saldo inicial (numérico serializado como string via AllTrim).

D5_DTVALIDstring · opcionalSD5.D5_DTVALID

Data de validade do lote (formato AAAAMMDD).

D5_TIPOstring · opcionalSD5.D5_TIPO

Tipo de movimento (categoria interna do SD5).

LotePayload

object

Payload plano aceito em POST. Whitelist definida em CAMPOS_ALLOW no .prw. D5_PRODUTO e D5_LOTECTL vêm do path — se enviados no body são ignorados.

D5_LOTEFORstring · opcionalSD5.D5_LOTEFOR

Lote do fornecedor.

D5_LOCALstring · opcionalSD5.D5_LOCAL

Local de estoque (default operacional "01").

D5_DOCstring · opcionalSD5.D5_DOC

Documento de origem (ex: "000000001").

D5_SERIEstring · opcionalSD5.D5_SERIE

Série do documento.

D5_DATAstring · opcionalSD5.D5_DATA

Data do movimento. Formato AAAAMMDD.

D5_QUANTnumber · opcionalSD5.D5_QUANT

Quantidade. Numérico; convertido para string via cValToChar antes do MsExecAuto.

D5_DTVALIDstring · opcionalSD5.D5_DTVALID

Data de validade do lote. Formato AAAAMMDD.

CrudResponse

object · envelope

Envelope padrão das respostas de POST / DELETE. Em POST, data traz { D5_PRODUTO, D5_LOTECTL } (eco da chave composta do path). Em DELETE, data é string vazia.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

datastring | object · opcional

Em POST, contém a chave composta (D5_PRODUTO/D5_LOTECTL). Em DELETE, string vazia.

Erro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode conter o token interno da causa (ex: mensagem do NomeAutoLog propagada do MATA390) 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).