rev5-2026-05-13 Protheus 12.1.33

Inventario

Serviço REST para registro de contagens de inventário físico (tabela SB7) via rotina automática MATA270. Não é CRUD. É um endpoint de processamento dentro do fluxo de inventário do Protheus — cobre exclusivamente a etapa de lançamento e estorno de contagens.

Bloqueio TOTVS: endpoint de processo (contagem SB7), sem MSBLQL.

Vinculação com o ERP

Tabela mestre SB7 Contagens de inventário físico

Rotina automática MATA270 MsExecAuto · array aRotAuto

Wrapper AdvPL U_MT270Exc src/lib/MAT/MT270EXC.prw

Operações & modos

POST op 3 (inclusão) DEL op 5 (exclusão) PUT não suportado

Dependências de ambiente

Pré-requisito · ETAPA 1

Geração de inventário (MATA275/MATA276)

cria registros zerados em SB7 com base no saldo de SB2 · disparada uma vez via menu/job, fora deste endpoint

Cadastro · produto

Produto (SB1)

B7_COD deve referenciar produto existente em SB1 · validação aplicada pelo MsExecAuto do MATA270

Cadastro · local

Local de estoque (NNR)

B7_LOCAL deve referenciar local cadastrado em NNR; pelo menos um produto/local deve ter saldo registrado em SB2

Posteriori · ETAPA 3

Acerto de inventário (MATA340)

aplica as diferenças contagem × saldo em SD3 · fora deste endpoint, executado depois de fechadas as contagens

Convenções

Endpoint de processo, não CRUD. Este serviço não cria inventário do zero — pressupõe que a etapa 1 (geração via MATA275/MATA276) já criou os registros em SB7 a partir do saldo de SB2. Aqui se lança a contagem efetiva (op=3) ou se estorna (op=5). A etapa 3 (MATA340) aplica as diferenças no estoque.

Sem PUT. A rotina automática MATA270 não expõe operação 4 (alteração) de forma confiável. Para corrigir uma contagem já lançada, DELETE o lançamento e POST o valor correto.

Chave do índice 1 da SB7 — B7_FILIAL + B7_COD + B7_LOCAL + B7_DATA. O TDN do MATA270 exige que esses campos cheguem no MsExecAuto com tamanho exato de SX3. O endpoint aplica PadR(..., TamSX3(...)[1]) automaticamente; clones devem manter essa garantia.

Formato de datas. B7_DATA e B7_DTVALID trafegam como string AAAAMMDD (ex: "20260507"). Conversão interna usa sToD(cString). Datas com hífen (2026-05-07) são rejeitadas.

Flag escolha. Cada produto/local/data pode ter múltiplas contagens (1ª, 2ª, 3ª) — útil para conferência cruzada. A flag escolha no payload indica qual delas é a oficial (lEscolha no MATA270); default true para a primeira contagem.

Path placeholder auto. Em POST /WsSB7/LANCAR/{produto}, se você não quiser repetir o produto na URL, use auto como placeholder e informe B7_COD no payload. Se ambos vierem, o path prevalece.

Contagem

Processamento — lançamento e estorno via MATA270

POST /WsSB7/LANCAR/{produto} Lança contagem de inventário

Descrição

Executa MATA270 em operação 3 para registrar a quantidade efetivamente contada no chão de fábrica para um produto/local/data/documento.

Pré-validações aplicadas antes do MsExecAuto:

Produto existe em SB1 e não bloqueado (B1_MSBLQL != "1").
B7_LOCAL obrigatório e existe em NNR.
BLQINVENT(produto, armazém, data) = .F. (respeita B2_DTINV/B2_DINVFIM).
Existe saldo inicial em SB2 para o par produto+armazém (evita HELP MA270NSB2). Quando não há, criar via WsMata220 (saldo zerado) ou WsMata241 (entrada).
Se B1_RASTRO ∈ {L,S}: B7_LOTECTL e B7_DTVALID obrigatórios; se =S, também B7_NUMLOTE.
Se B1_LOCALIZ='S': B7_LOCALIZ obrigatório.
Se MV_CONTINV=.T.: B7_CONTAGE obrigatório (HELP MT270CNTOBR).

Campos da chave (B7_COD, B7_LOCAL, B7_DATA) são PadR no tamanho exato do SX3 antes do seek.
Flag escolha determina lEscolha no MATA270 (qual contagem é a oficial).
Path {produto} = "auto" delega ao B7_COD do payload.
B7_DOC tem 9 chars máximo — sentinels com mais que isso são truncados silenciosamente.

Path parameter

produto string · path · obrigatório SB7.B7_COD

Código do produto a contar. Use auto como placeholder se for informar via B7_COD no payload.

Cenário

A escolha do cenário acima filtra os campos do body abaixo e o HTTP raw de exemplo. Cada cenário usa o mesmo schema (ContagemPayload) — varia apenas a combinação de campos enviada.

Request body

application/json ContagemPayload · obrigatório

Os campos abaixo refletem o cenário selecionado. Os inputs dirigem o valor no exemplo da aba ativa (sync via placeholder ↔ valor original).

B7_LOCAL string · obrigatório SB7.B7_LOCAL · NNR

Armazém (existe em NNR).

B7_DATA string · obrigatório SB7.B7_DATA

Data da contagem (AAAAMMDD).

B7_DOC string · obrigatório SB7.B7_DOC

Documento/identificador (máx. 9 chars).

B7_QUANT number · obrigatório SB7.B7_QUANT

Quantidade contada (atua no exemplo minimal).

B7_LOTECTL string SB7.B7_LOTECTL

Lote (obrigatório se B1_RASTRO ∈ {L,S}; só aparece no cenário realistic).

B7_DTVALID string SB7.B7_DTVALID

Validade do lote (AAAAMMDD); atua no exemplo realistic.

Exemplo da requisição (cenário ativo)

Contagem mínima — só os campos obrigatórios da chave + quantidade. Produto declarado via path. escolha=true (default) marca como contagem oficial.

RequestHTTP/1.1 · application/json

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

{
  "B7_LOCAL": "01",
  "B7_DATA":  "20260507",
  "B7_DOC":   "INVENT001_TEST_",
  "B7_QUANT": 10,
  "escolha":  true
}

Contagem com lote e validade — só funciona quando o produto é controlado por lote (B1_RASTRO=L ou S). B7_LOTECTL e B7_DTVALID são obrigatórios nesse caso. Se o produto não controla lote, o endpoint rejeita com 422 antes do MATA270 (evita o HELP A270LOTEIG opaco).

RequestHTTP/1.1 · application/json

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

{
  "B7_LOCAL":   "01",
  "B7_DATA":    "20260507",
  "B7_DOC":     "INVENT001_TEST_",
  "B7_QUANT":   125.5,
  "B7_LOTECTL": "LT2026A",
  "B7_DTVALID": "20271231",
  "escolha":    true
}

Segunda contagem (não oficial) — mesma chave de inventário (mesmo produto/local/data/doc) com escolha=false. Útil para conferência cruzada quando a primeira contagem é divergente.

RequestHTTP/1.1 · application/json

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

{
  "B7_LOCAL": "01",
  "B7_DATA":  "20260507",
  "B7_DOC":   "INVENT001_TEST_",
  "B7_QUANT": 12,
  "escolha":  false
}

Respostas

201

Contagem lançada. Envelope CrudResponse com data contendo a chave composta gravada.

400

Body inválido (JSON malformado, campos obrigatórios ausentes, formato de data fora de AAAAMMDD). Tier: validation-error.

422

Validação de negócio falhou — produto inexistente/bloqueado em SB1, armazém ausente/inválido em NNR, bloqueio BLQINVENT, saldo inicial ausente em SB2 (HELP MA270NSB2), rastro/endereço/contagem obrigatórios omitidos, ou rejeição pelo MsExecAuto do MATA270. Tier: business-error.

500

Erro interno (deserialização, runtime do AdvPL).

PUT /WsSB7/ALTERAR/{produto}/{local}/{dataref}/{doc} Altera campos editáveis de uma contagem

Descrição

Altera apenas campos do whitelist CAMPOS_PUT. A chave (B7_COD/B7_LOCAL/B7_DATA/B7_DOC) é imutável: identidade vem da URL; se vier no payload, é silenciosamente ignorada.

Campos read-only (cinza na tela ALTERAR padrão) recusados: B7_DESC, B7_DTVALID, B7_ORIGEM, B7_STATUS, B7_SLDTERC.

Pré-condição: B7_STATUS != "2". Inventário já processado retorna 422.

Path parameters

produto string · path · obrigatório SB7.B7_COD

Código do produto.

local string · path · obrigatório SB7.B7_LOCAL

Armazém.

dataref string · path · obrigatório SB7.B7_DATA

Data da contagem (AAAAMMDD).

doc string · path · obrigatório SB7.B7_DOC

Documento (máx. 9 chars).

Cenário

A escolha do cenário filtra os campos do body abaixo (chave da URL nunca é alterável; campos read-only da tela ALTERAR não aparecem).

Request body — campos editáveis

B7_QUANTnumberSB7.B7_QUANT

Quantidade contada.

B7_TIPOstringSB7.B7_TIPO

Tipo de material.

B7_QTSEGUMnumberSB7.B7_QTSEGUM

Quantidade na 2ª UM.

B7_LOTECTLstringSB7.B7_LOTECTL

Lote.

B7_NUMLOTEstringSB7.B7_NUMLOTE

Sublote.

B7_LOCALIZstringSB7.B7_LOCALIZ

Endereço.

B7_NUMSERIstringSB7.B7_NUMSERI

Número de série.

B7_TPESTRstringSB7.B7_TPESTR

Estrutura física.

B7_CONTAGEstringSB7.B7_CONTAGE

Número da contagem (1ª/2ª/3ª).

B7_CODUNIstringSB7.B7_CODUNI

Tipo de unitizador.

B7_IDUNITstringSB7.B7_IDUNIT

ID do unitizador.

B7_OKstringSB7.B7_OK

Marcação.

B7_ESCOLHAstringSB7.B7_ESCOLHA

Contagem escolhida (S/N/espaço).

Exemplo da requisição (cenário ativo)

Ajuste de quantidade — caso mais frequente: apenas B7_QUANT. Demais campos preservados.

RequestHTTP/1.1

PUT https://erpapi.jetme.com.br/api/99/01/WsSB7/ALTERAR/MP01/01/20260513/T130821
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "B7_QUANT": 99.5
}

Contagem rápida — registra a quantidade e já marca como contagem escolhida em uma única chamada. Útil para contagens únicas (sem múltiplas rodadas).

RequestHTTP/1.1

PUT https://erpapi.jetme.com.br/api/99/01/WsSB7/ALTERAR/MP01/01/20260513/T130821
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "B7_QUANT":   99.5,
  "B7_ESCOLHA": "S"
}

Selecionar contagem — entre múltiplas contagens existentes para a mesma chave, marca esta como a oficial (B7_ESCOLHA="S"). Não altera quantidade. Útil quando o acerto (MATA340) não conseguiu selecionar automaticamente porque havia divergência.

RequestHTTP/1.1

PUT https://erpapi.jetme.com.br/api/99/01/WsSB7/ALTERAR/MP01/01/20260513/T130821
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "B7_ESCOLHA": "S"
}

Todos os campos editáveis — payload com todo o whitelist CAMPOS_PUT; útil para operações administrativas / correções amplas.

RequestHTTP/1.1

PUT https://erpapi.jetme.com.br/api/99/01/WsSB7/ALTERAR/MP01/01/20260513/T130821
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Content-Type: application/json
Accept: application/json

{
  "B7_QUANT":   99.5,
  "B7_TIPO":    "MP",
  "B7_CONTAGE": "001",
  "B7_ESCOLHA": "S"
}

Respostas

200

Alteração aplicada. data.alterados traz o número de campos efetivamente atualizados (0 = nenhum campo do whitelist veio no payload).

400

URL ou payload mal formado. Tier: validation-error.

404

Lançamento não encontrado. Tier: not-found.

422

Inventário já processado (B7_STATUS=2). Alteração não permitida. Tier: business-error.

500

Erro interno.

DEL /WsSB7/EXCLUIR/{produto}/{local}/{dataref}/{doc} Exclui lançamento de inventário

Descrição

Exclusão lógica direta (RecLock/DbDelete em transação). A op=5 do MATA270 é silenciosa no build 240223P (retorna OK sem marcar D_E_L_E_T_), por isso a biblioteca aplica o delete sem passar pela rotina automática.

Pré-condição: B7_STATUS != "2". Inventário já processado pelo MATA340 retorna 422 — para estornar, use WsMata241 sobre o movimento INVENT em SD3.

Path parameters

produto string · path · obrigatório SB7.B7_COD

Código do produto. PadR(TamSX3("B7_COD")).

local string · path · obrigatório SB7.B7_LOCAL

Local de estoque. PadR(TamSX3("B7_LOCAL")).

dataref string · path · obrigatório SB7.B7_DATA

Data da contagem no formato AAAAMMDD. (Nome dataref porque data é palavra reservada em WSDATA.)

doc string · path · obrigatório SB7.B7_DOC

Documento/identificador do inventário. Máx. 9 caracteres (TamSX3("B7_DOC")).

Cenário

DELETE não tem body — o cenário existe apenas por uniformidade do padrão. Path params acima dirigem o exemplo abaixo.

Exemplo da requisição (cenário ativo)

Estorno padrão — exclui o lançamento identificado pela chave da URL. Falha com 422 se B7_STATUS="2".

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsSB7/EXCLUIR/MP01/01/20260513/T130821
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lançamento excluído. Envelope CrudResponse.

400

URL ou parâmetros inválidos (data fora de AAAAMMDD, segmento ausente). Tier: validation-error.

404

Lançamento não encontrado para a chave composta. Tier: not-found.

422

Inventário já processado (B7_STATUS=2). Para estornar, use WsMata241 sobre o movimento INVENT em SD3. Tier: business-error.

500

Erro interno.

Consulta

Leitura de lançamentos já gravados em SB7

GET /WsSB7/{produto} Lista lançamentos do produto

Descrição

Retorna todos os lançamentos de contagem registrados em SB7 para o produto informado, na filial corrente (xFilial("SB7")). Útil para validar visualmente uma contagem recém-lançada ou para auditar histórico de inventário do produto.

Path parameter

produto string · path · obrigatório SB7.B7_COD

Código do produto. Match exato em B7_COD.

Cenário

GET por produto não tem variantes operacionais; o cenário existe para uniformidade do padrão.

Exemplo da requisição (cenário ativo)

RequestHTTP/1.1 · sem body

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

Respostas

200

Array de Contagem sob data. Envelope inclui count.

404

Produto sem lançamentos em SB7 na filial corrente. Tier: not-found.

500

Erro interno.

GET /WsSB7/_porDoc Lista contagens por documento + número da contagem

Descrição

Listagem ancorada em doc + contagem (ambos obrigatórios). Filtros adicionais opcionais: cod (prefixo), loc, dt, lote, endereco.

Útil para conferir uma rodada específica (1ª/2ª/3ª) sob um único documento de inventário.

Cenário

Query parameters

docstring · query · obrigatórioSB7.B7_DOC

Documento exato.

contagemstring · query · obrigatórioSB7.B7_CONTAGE

Número da contagem (ex. "001").

codstring · querySB7.B7_COD

Prefixo de produto.

locstring · querySB7.B7_LOCAL

Armazém exato.

dtstring · querySB7.B7_DATA

Data exata (AAAAMMDD).

lotestring · querySB7.B7_LOTECTL

Lote exato.

enderecostring · querySB7.B7_LOCALIZ

Endereço exato.

Exemplo da requisição (cenário ativo)

Por doc + contagem — mínimo necessário.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB7/_porDoc?doc=INVENT001&contagem=001
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Com filtros adicionais — produto + armazém.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB7/_porDoc?doc=INVENT001&contagem=001&cod=MP&loc=01
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Listagem filtrada (pode vir vazia).

400

doc ou contagem ausentes.

GET /WsSB7/_pendentes Lista contagens não processadas (B7_STATUS ≠ "2")

Descrição

Lista todos os lançamentos com B7_STATUS != "2" (ainda não processados pelo acerto MATA340). Cada item devolve B7_DOC + B7_CONTAGE para o front saber o que ainda precisa inventariar/processar.

Cenário

Query parameters (todos opcionais)

docstring · querySB7.B7_DOC

Documento exato.

codstring · querySB7.B7_COD

Prefixo de produto.

locstring · querySB7.B7_LOCAL

Armazém exato.

dtInistring · querySB7.B7_DATA

Início (AAAAMMDD).

dtFimstring · querySB7.B7_DATA

Fim (AAAAMMDD).

Exemplo da requisição (cenário ativo)

Todos pendentes — primeira página, default 50.

RequestHTTP/1.1 · sem body

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

Por doc + intervalo — pendentes de um documento num mês.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB7/_pendentes?doc=INVENT001&dtIni=20260501&dtFim=20260531
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Lista paginada com pendentes; cada item traz B7_DOC + B7_CONTAGE para identificação.

GET /WsSB7/_list Lista lançamentos com filtros e paginação

Descrição

Lista lançamentos de inventário com filtros opcionais por produto (prefix), local e data (exata ou intervalo).

Combinação dt = data exata; dtIni/dtFim = intervalo (inclusive).
Quando dt é informado, dtIni/dtFim são ignorados.
Paginação por page/pageSize (default 50, máx 500).

Query parameters

cod string · query · opcional SB7.B7_COD

Prefix de B7_COD.

loc string · query · opcional SB7.B7_LOCAL

Local exato.

dt string · query · opcional SB7.B7_DATA

Data exata, formato AAAAMMDD.

dtIni string · query · opcional

Início do intervalo (AAAAMMDD). Ignorado se dt presente.

dtFim string · query · opcional

Fim do intervalo (AAAAMMDD), inclusive.

page integer · query · opcional

Página (default 1).

pageSize integer · query · opcional

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

Cenário

Filtros opcionais combinados: cod (prefixo de B7_COD), loc (armazém exato), dt (data exata) ou dtIni/dtFim (intervalo). page e pageSize para paginação.

Exemplo da requisição (cenário ativo)

Por intervalo — filtra um armazém num mês inteiro, pagina maior para conferência.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB7/_list?loc=01&dtIni=20260501&dtFim=20260531&pageSize=100
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Data exata + prefixo de produto — busca pontual em uma data específica filtrando produtos por prefixo do código.

RequestHTTP/1.1 · sem body

GET https://erpapi.jetme.com.br/api/99/01/WsSB7/_list?cod=PROD&dt=20260507
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Página de contagens. Envelope com data (array de Contagem), page, pageSize, count.

400

Parâmetro fora do domínio (data inválida, pageSize > 500).

500

Erro interno.

Schemas

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

Contagem

object

Representação retornada nos GETs (/{produto} e /_list). Campos efetivamente serializados dependem de CAMPOS_GET definido no .prw.

B7_CODstring · opcionalSB7.B7_COD

Código do produto contado (chave parcial índice 1).

B7_LOCALstring · opcionalSB7.B7_LOCAL

Local de estoque (chave parcial índice 1). FK informal para NNR.

B7_DATAstring · opcionalSB7.B7_DATA

Data da contagem (chave parcial índice 1), formato AAAAMMDD.

B7_DOCstring · opcionalSB7.B7_DOC

Documento/identificador do inventário (parte da chave única do registro).

B7_QUANTnumber · opcionalSB7.B7_QUANT

Quantidade efetivamente contada.

B7_LOTECTLstring · opcionalSB7.B7_LOTECTL

Lote (preenchido quando o produto controla lote via B1_RASTRO).

B7_NUMSERIstring · opcionalSB7.B7_NUMSERI

Número de série (controle por unidade serializada).

B7_LOCALIZstring · opcionalSB7.B7_LOCALIZ

Endereçamento físico (controle por endereço habilitado).

B7_DTVALIDstring · opcionalSB7.B7_DTVALID

Data de validade do lote (AAAAMMDD).

B7_TIPOstring · opcionalSB7.B7_TIPO

Tipo do inventário (classificação configurável no SX3 do cliente).

B7_ORIGEMstring · opcionalSB7.B7_ORIGEM

Origem do lançamento (manual, automático, importação).

recnointeger · opcional

Id técnico do registro (RecNo do AdvPL).

ContagemPayload

object

Payload aceito em POST /WsSB7/LANCAR/{produto}. Whitelist CAMPOS_ALLOW + flag de controle escolha. Campos da chave (B7_COD, B7_LOCAL, B7_DATA, B7_DOC) são obrigatórios; o endpoint aplica PadR no tamanho do SX3.

B7_CODstring · opcionalSB7.B7_COD

Código do produto. Opcional se path {produto} ≠ auto; nesse caso o path prevalece.

B7_LOCALstring · obrigatórioSB7.B7_LOCAL

Local de estoque (deve existir em NNR).

B7_DATAstring · obrigatórioSB7.B7_DATA

Data da contagem no formato AAAAMMDD.

B7_DOCstring · obrigatórioSB7.B7_DOC

Documento/identificador do inventário. Em smoke, use sufixo _TEST_ para limpeza trivial.

B7_QUANTnumber · obrigatórioSB7.B7_QUANT

Quantidade efetivamente contada (aceita decimal).

B7_LOTECTLstring · opcionalSB7.B7_LOTECTL

Lote — obrigatório quando o produto controla lote (B1_RASTRO=L).

B7_NUMSERIstring · opcionalSB7.B7_NUMSERI

Número de série, se aplicável.

B7_LOCALIZstring · opcionalSB7.B7_LOCALIZ

Endereçamento físico, se o local usa endereço.

B7_DTVALIDstring · opcionalSB7.B7_DTVALID

Data de validade do lote (AAAAMMDD).

B7_TIPOstring · opcionalSB7.B7_TIPO

Tipo do inventário (uso conforme parametrização do cliente).

B7_ORIGEMstring · opcionalSB7.B7_ORIGEM

Origem do lançamento.

escolhaboolean · opcional · default true

Define lEscolha no MATA270. true = contagem oficial; false = contagem auxiliar (2ª, 3ª, conferência cruzada).

CrudResponse

object · envelope

Envelope padrão das respostas de POST e DELETE. Em POST, data contém a chave composta gravada em SB7; em DELETE, geralmente string vazia.

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso.

datastring | object · opcional

Em POST, identificação da chave composta. Em DELETE, vazia ou objeto auxiliar.

Erro

object · envelope

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

Cenários

Catálogo de combinações de payload reconhecidas pelos métodos. Cada cenário usa o mesmo schema mas demonstra um uso típico distinto.

contagem-minima

POST /LANCAR

Caminho feliz mínimo do POST. Só os campos obrigatórios da chave (B7_LOCAL, B7_DATA, B7_DOC) + B7_QUANT. Sem lote, sem endereço, sem contagem numerada (MV_CONTINV=.F.). Produto declarado via path. escolha=true marca como contagem oficial.

Quando usar: inventário simples, produto sem rastro/endereço, contagem única.
Resultado: 201 com envelope CrudResponse trazendo a chave gravada.

B7_LOCALstring · obrigatórioSB7.B7_LOCAL

Armazém — deve existir em NNR e ter saldo inicial em SB2.

B7_DATAstring · obrigatórioSB7.B7_DATA

Data da contagem em AAAAMMDD.

B7_DOCstring · obrigatórioSB7.B7_DOC

Identificador (máx. 9 chars).

B7_QUANTnumber · obrigatórioSB7.B7_QUANT

Quantidade contada.

escolhaboolean · opcional— (flag lEscolha)

Default true = contagem oficial.

contagem-com-lote

POST /LANCAR

POST para produto controlado por lote (B1_RASTRO=L ou S). Acrescenta B7_LOTECTL e B7_DTVALID (ambos obrigatórios pela política do MATA270).

Quando usar: matérias-primas com rastreabilidade, medicamentos, perecíveis.
Pré-validação: se o produto não controla lote, o endpoint rejeita 422 antes do MATA270 (evita HELP A270LOTEIG opaco).

B7_LOCALstring · obrigatórioSB7.B7_LOCAL

Armazém.

B7_DATAstring · obrigatórioSB7.B7_DATA

Data da contagem (AAAAMMDD).

B7_DOCstring · obrigatórioSB7.B7_DOC

Identificador.

B7_QUANTnumber · obrigatórioSB7.B7_QUANT

Quantidade contada do lote.

B7_LOTECTLstring · obrigatório (rastro)SB7.B7_LOTECTL

Número do lote.

B7_DTVALIDstring · obrigatório (rastro)SB7.B7_DTVALID

Validade do lote em AAAAMMDD.

B7_NUMLOTEstring · condicionalSB7.B7_NUMLOTE

Sublote — obrigatório quando B1_RASTRO=S.

escolhaboolean · opcional— (flag lEscolha)

Default true.

segunda-contagem-nao-oficial

POST /LANCAR

Mesma chave de inventário (mesmo produto/local/data/doc) com escolha=false. Útil para conferência cruzada quando a primeira contagem foi divergente do sistema.

Quando usar: processo de "dupla contagem"; só a contagem com B7_ESCOLHA="S" participa do acerto do MATA340.
Pré-requisito: existe registro anterior em SB7 com mesma chave; MV_CONTINV pode estar ligado para diferenciar via B7_CONTAGE.

B7_LOCALstring · obrigatórioSB7.B7_LOCAL

Mesmo armazém da 1ª contagem.

B7_DATAstring · obrigatórioSB7.B7_DATA

Mesma data da 1ª contagem.

B7_DOCstring · obrigatórioSB7.B7_DOC

Mesmo documento.

B7_QUANTnumber · obrigatórioSB7.B7_QUANT

Quantidade desta nova contagem.

escolhaboolean · obrigatório (false)— (flag lEscolha)

false indica que esta NÃO é a oficial.

ajuste-quantidade

PUT /ALTERAR

Caso mais frequente de alteração: corrigir B7_QUANT de uma contagem já lançada.

Pré-condição: B7_STATUS != "2" (não processado pelo MATA340). Senão retorna 422.

B7_QUANTnumber · obrigatórioSB7.B7_QUANT

Nova quantidade.

contagem-rapida

PUT /ALTERAR

Registra a quantidade e já marca como contagem escolhida numa única chamada (B7_QUANT + B7_ESCOLHA="S").

Quando usar: contagens únicas, sem rodadas múltiplas — evita duas requisições (uma para qty, outra para selecionar).

B7_QUANTnumber · obrigatórioSB7.B7_QUANT

Quantidade contada.

B7_ESCOLHAstring · obrigatório ("S")SB7.B7_ESCOLHA

Marca como contagem oficial.

selecionar-contagem

PUT /ALTERAR

Entre múltiplas contagens existentes para a mesma chave (1ª/2ª/3ª), marca esta como a oficial. Não altera B7_QUANT.

Quando usar: o MATA340 só seleciona automaticamente quando todas as contagens são equivalentes; havendo divergência, é necessária seleção manual via este cenário.
Próximo passo: consultar GET /_divergencias (pendência) antes de selecionar.

B7_ESCOLHAstring · obrigatório ("S")SB7.B7_ESCOLHA

Marca esta contagem como oficial.

todos-campos-editaveis

PUT /ALTERAR

Payload com todo o whitelist CAMPOS_PUT. Útil para correções administrativas amplas. Campos read-only (B7_DESC, B7_DTVALID, B7_ORIGEM, B7_STATUS, B7_SLDTERC) são recusados; chave da URL é imutável (se vier no payload, é ignorada).

B7_TIPOstringSB7.B7_TIPO

Tipo de material.

B7_QUANTnumberSB7.B7_QUANT

Quantidade contada.

B7_QTSEGUMnumberSB7.B7_QTSEGUM

Quantidade na 2ª UM.

B7_LOTECTLstringSB7.B7_LOTECTL

Lote.

B7_NUMLOTEstringSB7.B7_NUMLOTE

Sublote.

B7_LOCALIZstringSB7.B7_LOCALIZ

Endereço.

B7_NUMSERIstringSB7.B7_NUMSERI

Número de série.

B7_TPESTRstringSB7.B7_TPESTR

Estrutura física.

B7_CONTAGEstringSB7.B7_CONTAGE

Número da contagem.

B7_CODUNIstringSB7.B7_CODUNI

Tipo de unitizador.

B7_IDUNITstringSB7.B7_IDUNIT

ID do unitizador.

B7_OKstringSB7.B7_OK

Marcação.

B7_ESCOLHAstringSB7.B7_ESCOLHA

Contagem escolhida (S/N/' ').

estorno-padrao

DELETE /EXCLUIR

Exclusão lógica direta da contagem identificada pela chave completa na URL (produto/local/dataref/doc). Sem body.

Pré-condição: B7_STATUS != "2". Inventário já processado pelo MATA340 exige estorno via WsMata241 sobre o movimento INVENT em SD3 — não é possível DELETE direto no SB7.

(sem body)

Toda identidade vem da URL.

consulta-direta

GET /{produto}

Retorna todos os lançamentos em SB7 para o produto informado, em todas as datas/armazéns. Sem paginação — para listas grandes use /_list ou /_porDoc.

produtopathSB7.B7_COD

Código do produto.

por-doc-contagem

GET /_porDoc

Lista contagens ancoradas em documento + número da contagem (ambos obrigatórios). Sem outros filtros.

Quando usar: conferir todos os itens de uma rodada específica (ex.: 1ª contagem do documento INVENT001).

docquery · obrigatórioSB7.B7_DOC

Documento exato.

contagemquery · obrigatórioSB7.B7_CONTAGE

Número da rodada (ex.: 001).

com-filtros-adicionais

GET /_porDoc

doc + contagem obrigatórios; refine com filtros opcionais: produto (prefixo), armazém, data exata, lote, endereço. Todos exatos exceto cod.

docquery · obrigatórioSB7.B7_DOC

Documento exato.

contagemquery · obrigatórioSB7.B7_CONTAGE

Rodada.

codquery · opcionalSB7.B7_COD

Prefixo de produto.

locquery · opcionalSB7.B7_LOCAL

Armazém exato.

dtquery · opcionalSB7.B7_DATA

Data exata.

lotequery · opcionalSB7.B7_LOTECTL

Lote exato.

enderecoquery · opcionalSB7.B7_LOCALIZ

Endereço exato.

todos-pendentes

GET /_pendentes

Lista todas as contagens com B7_STATUS != "2" (não processadas pelo MATA340). Primeira página, default 50 itens.

Quando usar: dashboard / monitor do progresso de inventário.

(sem params)

Use paginação (page/pageSize) para conjuntos grandes.

por-doc-e-intervalo

GET /_pendentes

Pendentes filtrados por documento + intervalo de datas (e/ou armazém, prefixo de produto).

Quando usar: follow-up de um inventário específico — saber o que ainda falta processar.

docquery · opcionalSB7.B7_DOC

Documento exato.

codquery · opcionalSB7.B7_COD

Prefixo de produto.

locquery · opcionalSB7.B7_LOCAL

Armazém exato.

dtIniquery · opcionalSB7.B7_DATA

Início (AAAAMMDD).

dtFimquery · opcionalSB7.B7_DATA

Fim (AAAAMMDD).

por-intervalo

GET /_list

Listagem por armazém em um intervalo de datas. Página maior (100) para conferências mensais.

locquery · opcionalSB7.B7_LOCAL

Armazém exato.

dtIniquery · opcionalSB7.B7_DATA

Início.

dtFimquery · opcionalSB7.B7_DATA

Fim.

pageSizequery · opcional

Default 50, máx 500.

data-exata-prefix-produto

GET /_list

Busca pontual em uma data específica, filtrando produtos por prefixo do código.

codquery · opcionalSB7.B7_COD

Prefixo de produto (ex.: MP).

dtquery · opcionalSB7.B7_DATA

Data exata.