rev2-2026-05-05 Protheus 12.1.27+

LocalEstoque

CRUD de locais de estoque (armazéns) — tabela NNR — via wrapper sobre a rotina padrão AGRA045 (FwModel/MsExecAuto). O identificador externo é o próprio código do armazém (NNR_CODIGO, 2 caracteres). Grids de usuários autorizados (SGQUSER) e de produtos vinculados (SGQPROD) são aceitos opcionalmente no POST e PUT.

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

Vinculação com o ERP

Tabela mestre NNR Locais de estoque (armazéns)

Rotina automática AGRA045 FwModel · MsExecAuto

Wrappers AdvPL U_AG045MVC src/lib/MAT/AG045MVC.prw

Operações & modos

POST Op=3 PUT Op=4 DEL Op=5

Dependências de ambiente

Release mínimo

Protheus 12.1.27+

patch DT 9011865 / DMANMAT01-27731
necessário para que a gravação dos grids SGQUSER/SGQPROD via rotina automática funcione corretamente

Cadastro

Bloqueio (sem MSBLQD nesta base)

tabela NNR · campo NNR_MSBLQL
"1"=Bloqueado · "2"=Liberado (default) · o par NNR_MSBLQD não existe no SX3 desta base

Grids (filhas)

SGQUSER · SGQPROD

SGQUSER: usuários ou grupos autorizados (GQ_USER) · SGQPROD: produtos ou grupos vinculados (GQ_PRODUTO) · ambos opcionais no POST; no PUT, array vazio limpa o grid e omissão mantém o existente

Convenções

Identificador externo. O código do armazém (NNR_CODIGO, máx 2 caracteres) é o próprio identificador na URL: /WsNNR/{codigo}. Não há chave interna separada — a rota plural /WsNNR/ sem código retorna a lista da filial.

Filial. Todas as rotas aceitam ?filial= opcional (default "01"). A URL /api/99/01 já fixa empresa/filial no path do AppServer, mas o query param filial permite alternar dentro do escopo da empresa quando o ambiente compartilha o cadastro entre filiais.

Bloqueio TOTVS — só NNR_MSBLQL. Nesta base, a tabela NNR expõe somente o flag de bloqueio ("1" = Bloqueado, "2" = Liberado, default). O campo NNR_MSBLQD (data de bloqueio) não existe no SX3, ao contrário de outras tabelas TOTVS — portanto não há "caminho de desbloqueio" baseado em vigência aqui, apenas bloqueio manual via flag.

Contrato planejado (padrão WsSA1): em armazém bloqueado, o PUT deve aceitar exclusivamente Bloqueado (caminho de desbloqueio); payload tocando Descricao ou grids responde 422. DELETE em armazém bloqueado também deve ser rejeitado pelo MVC.

PEN — wrapper pendente (2026-05-14). O wrapper U_AG045Exc/U_AG045MVC hoje só grava NNR_MSBLQL="2" como default na inclusão; não lê Bloqueado no payload nem aplica o gate em PUT/DELETE. Esta seção documenta o contrato alvo, validado via test-local-estoque.sh (passo 4b PEN).

Grids opcionais. No POST, omitir Usuarios/Produtos grava o registro sem grids. No PUT: omitir mantém o conteúdo atual; enviar array vazio [] limpa o grid; enviar itens substitui o conteúdo (não há merge incremental).

FwModel direto. O wrapper U_AG045MVC monta o model nativo do AGRA045 (não usa MsExecAuto legado) — comportamento validado para release ≥ 12.1.27. Em Op=DELETE, o wrapper pula SetValue nos campos (caso contrário o FwLoadModel rejeita a deleção). Ver Vinculação com o ERP para o caminho do fonte.

LocalEstoque

CRUD por código do armazém

GET /WsNNR/ Lista locais de estoque da filial

Descrição

Retorna todos os locais de estoque da filial corrente em uma única lista (não há paginação — o cadastro de armazéns é tipicamente pequeno). Para consultar um único local, use a rota irmã /WsNNR/{codigo}.

Query parameters

filial string · query · opcional

Filial Protheus (default "01").

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Lista de locais. Envelope { success: true, data: { total, locais[] } } — itens em LocalEstoqueItem.

500

Erro interno. Tier: business-error.

GET /WsNNR/{codigo} Consulta local de estoque por código

Descrição

Retorna os dados do local de estoque identificado por {codigo} (NNR_CODIGO, 2 caracteres). A resposta traz codigo, descricao e bloqueado; grids SGQUSER/SGQPROD não são serializados nesta versão.

Path parameter

codigo string · path · obrigatório NNR.NNR_CODIGO

Código do armazém (máx 2 caracteres).

Query parameters

filial string · query · opcional

Filial Protheus (default "01").

Chamada de exemplo

RequestHTTP/1.1 · sem body

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

Respostas

200

Local encontrado. Envelope { success: true, data: LocalEstoqueItem }.

404

Local de estoque não localizado. Tier: not-found.

500

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

POST /WsNNR/ Inclui novo local de estoque

Descrição

Inclui um novo local de estoque via AGRA045 em modo 3 (MODEL_OPERATION_INSERT). O cliente informa o código (NNR_CODIGO) — não há geração automática por GetSXENum aqui. Grids Usuarios (SGQUSER) e Produtos (SGQPROD) são opcionais.

Schema completo do body: LocalEstoqueRequest.
Tentativa de incluir código já existente retorna 422.

Request body

application/json LocalEstoqueRequest · obrigatório

Campos obrigatórios: Filial, Codigo, Descricao. Grids opcionais. Schema em LocalEstoqueRequest.

Payload mínimo — apenas os campos obrigatórios; grids omitidos. Fixture: fixtures/create-minimal.json.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "Codigo": "10",
  "Descricao": "ARMAZEM 10",
  "Bloqueado": "2"
}

Com grids — payload realista incluindo usuários autorizados (SGQUSER) e produtos vinculados (SGQPROD). Fixture: fixtures/create.json.

RequestHTTP/1.1 · application/json

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

{
  "Filial": "01",
  "Codigo": "10",
  "Descricao": "ARMAZEM 10",
  "Bloqueado": "2",
  "Usuarios": [
    { "Usuario": "000000" }
  ],
  "Produtos": [
    { "Produto": "0000001000" }
  ]
}

Respostas

201

Local incluído. Envelope com data.codigo = código do armazém criado.

400

Campo obrigatório ausente ou JSON malformado. Tier: validation-error.

422

AGRA045 rejeitou a operação (ex: código já existente, valor inválido em Bloqueado). Tier: business-error.

500

Erro interno.

PUT /WsNNR/{codigo} Altera local de estoque existente

Descrição

Altera o local de estoque via AGRA045 em modo 4 (MODEL_OPERATION_UPDATE). Apenas os campos informados no body são alterados — campos omitidos mantêm o valor atual.

Comportamento dos grids no PUT:

Omitir Usuarios/Produtos → mantém o conteúdo atual.
Enviar [] → limpa o grid.
Enviar itens → substitui o grid (não há merge).
Bloqueado="1" bloqueia; "2" libera (não há vigência).

Path parameter

codigo string · path · obrigatório NNR.NNR_CODIGO

Código do armazém a alterar.

Query parameters

filial string · query · opcional

Filial Protheus (default "01").

Request body

application/json LocalEstoquePutRequest · obrigatório

Subconjunto dos campos editáveis. Schema em LocalEstoquePutRequest.

Alteração simples — atualiza descrição mantendo grids e bloqueio. Fixture: fixtures/update.json.

RequestHTTP/1.1 · application/json

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

{
  "Descricao": "ARMAZEM 10 REVISADO"
}

Bloquear armazém — define Bloqueado="1" (Inativo). Não há vigência por data nesta tabela.

RequestHTTP/1.1 · application/json

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

{
  "Bloqueado": "1"
}

Liberar registro bloqueado — caminho de desbloqueio. Em armazém bloqueado (NNR_MSBLQL="1"), esse é o único payload aceito pelo contrato; qualquer outro campo provoca 422. PEN: gate ainda não implementado no wrapper.

RequestHTTP/1.1 · application/json

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

{
  "NNR_MSBLQL": "2"
}

Limpar os dois grids — envia array vazio em Usuarios e Produtos para remover todos os vínculos.

RequestHTTP/1.1 · application/json

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

{
  "Usuarios": [],
  "Produtos": []
}

Respostas

200

Local alterado. Envelope RespostaSucesso.

400

Código ausente no path ou body inválido. Tier: validation-error.

404

Local não localizado. Tier: not-found.

422

AGRA045 rejeitou a alteração (validação de domínio, restrição de negócio) ou registro bloqueado (NNR_MSBLQL="1") com payload tocando campo fora do caminho de desbloqueio — só Bloqueado permitido. Tier: business-error. PEN: gate de bloqueio ainda não implementado.

500

Erro interno.

DEL /WsNNR/{codigo} Exclui local de estoque

Descrição

Exclui o local de estoque via AGRA045 em modo 5 (MODEL_OPERATION_DELETE). O AGRA045 rejeita exclusão de armazém com estoque em uso (saldo, movimentações ativas) — caso em que a resposta é 422. O wrapper U_AG045MVC pula SetValue nos campos quando a operação é DELETE (necessário para o FwLoadModel persistir a deleção).

Path parameter

codigo string · path · obrigatório NNR.NNR_CODIGO

Código do armazém a excluir.

Query parameters

filial string · query · opcional

Filial Protheus (default "01").

Chamada de exemplo

RequestHTTP/1.1 · sem body

DELETE https://erpapi.jetme.com.br/api/99/01/WsNNR/10
Authorization: Bearer eyJhbGciOiJIUzI1NiIs…
Accept: application/json

Respostas

200

Local excluído. Envelope RespostaSucesso.

400

Código ausente no path. Tier: validation-error.

404

Local não localizado. Tier: not-found.

422

Armazém com estoque/movimentações em uso — AGRA045 rejeita. Tier: business-error.

500

Erro interno.

Schemas

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

LocalEstoqueItem

object

Forma serializada retornada nos GETs (/ em data.locais[], /{codigo} em data). Apenas campos cabeçalho — grids SGQUSER/SGQPROD não são retornados.

codigostring · opcionalNNR.NNR_CODIGO

Código do armazém (máx 2 caracteres).

descricaostring · opcionalNNR.NNR_DESCRI

Descrição do armazém (máx 30 caracteres).

bloqueadostring · opcionalNNR.NNR_MSBLQL

Estado de bloqueio TOTVS-padrão. "1"=Bloqueado, "2"=Liberado (default).

12

LocalEstoqueRequest

object

Payload aceito em POST /WsNNR/. Filial, Codigo e Descricao são obrigatórios; grids Usuarios/Produtos são opcionais.

Filialstring · obrigatório

Filial Protheus (ex: "01"). Máx 2 caracteres.

Codigostring · obrigatórioNNR.NNR_CODIGO

Código do armazém (máx 2 caracteres). Deve ser único na filial.

Descricaostring · obrigatórioNNR.NNR_DESCRI

Descrição do armazém (máx 30 caracteres).

Bloqueadostring · opcionalNNR.NNR_MSBLQL

Default "2". "1"=Bloqueado, "2"=Liberado.

12

Usuariosarray<ItemUsuario> · opcional

Grid de usuários/grupos autorizados (SGQUSER). Ver ItemUsuario.

Produtosarray<ItemProduto> · opcional

Grid de produtos/grupos vinculados (SGQPROD). Ver ItemProduto.

LocalEstoquePutRequest

object

Payload aceito em PUT /WsNNR/{codigo}. Todos os campos são opcionais — omitir mantém o valor atual; em grids, omitir mantém o conteúdo e [] limpa.

Descricaostring · opcionalNNR.NNR_DESCRI

Nova descrição (máx 30 caracteres). Omitir = mantém atual.

Bloqueadostring · opcionalNNR.NNR_MSBLQL

"1"=Bloqueado, "2"=Liberado. Omitir = mantém atual.

12

Usuariosarray<ItemUsuario> · opcional

Substitui o grid SGQUSER. Omitir = mantém atual. [] = limpa grid.

Produtosarray<ItemProduto> · opcional

Substitui o grid SGQPROD. Omitir = mantém atual. [] = limpa grid.

ItemUsuario

object

Item do grid SGQUSER (usuários/grupos autorizados a operar no armazém).

Usuariostring · obrigatórioSGQ.GQ_USER

Código do usuário ou grupo (máx 6 caracteres).

ItemProduto

object

Item do grid SGQPROD (produtos/grupos vinculados ao armazém).

Produtostring · obrigatórioSGQ.GQ_PRODUTO

Código do produto ou grupo (máx 10 caracteres).

RespostaSucesso

object · envelope

Envelope padrão das respostas de PUT / DELETE (e variantes de POST com data objeto, ver RespostaInclusao no openapi.yaml).

successboolean · const: true

Sempre true em respostas de sucesso.

messagestring · obrigatório

Mensagem editorial de sucesso (ex: "Local de estoque 10 alterado com sucesso.").

datastring | object · opcional

Em POST contém { codigo: NNR_CODIGO }. Em PUT/DELETE é string vazia.

RespostaErro

object · envelope

Envelope padrão de erros 4xx/5xx. data pode trazer detalhe técnico (log do MsExecAuto/NomeAutoLog) 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).