Estoques

A entidade Estoque representa um local ou origem de estoque da indústria, como um centro de distribuição, um depósito ou uma importação a caminho. Cada estoque pertence a uma representada/divisão.

Um estoque pode ser:

  • Físico: mercadoria disponível para pronta entrega.
  • Futuro: mercadoria com previsão de chegada. O estoque futuro tem uma data_previsao_chegada e deixa de ser contado como ativo depois dessa data.

Cada estoque pode ser identificado pelo seu id no Mercos e, opcionalmente, pelo codigo_integracao, o código do estoque no sistema que está integrando.

⚠️

Importante

  1. Toda divisão/representada possui um estoque padrão, que existe automaticamente e não é um registro desta entidade. Ele NÃO é
    retornado pelo GET e NÃO pode ser alterado nem excluído por este endpoint.
  2. Cada requisição ao criar e alterar manipula apenas um estoque, e para excluir é só utilizar o método PUT enviando o campo excluido = true no corpo da requisição. Um estoque excluído não pode mais ser alterado.
  3. O controle de estoque precisa estar ativo na divisão/representada para criar ou alterar estoques. A exclusão é permitida mesmo com o controle desativado.

Estrutura de Retorno (GET)

CampoTipoDescrição
idIntegerIdentificador único do estoque no Mercos.
codigo_integracaoString: 60Código único do estoque no sistema que está integrando ao Mercos.
nomeString: 30Nome do estoque.
ativoBooleanIndica se o estoque está ativo.
estoque_futuroBooleantrue quando o estoque possui data_previsao_chegada (estoque futuro); false para estoque físico.
data_previsao_chegadaDatePrevisão de chegada da mercadoria, no formato AAAA-MM-DD. null para estoque físico.
informacoes_adicionaisString: 100Observações sobre o estoque. null quando não informado.
excluidoBooleanIndica se o estoque está excluído.
ultima_alteracaoDateTimeData e hora da última modificação do estoque.
representada_idIntegerIdentificador da representada do registro. Retornado quando a sua conta não é uma indústria com divisões.
divisao_idIntegerIdentificador da divisão do registro. Retornado no lugar de representada_id quando a sua conta é uma indústria com divisões.
💡

Quando a data_previsao_chegada de um estoque futuro passa, o estoque deixa de contar como ativo, mas a ultima_alteracao não muda.
Use a data_previsao_chegada para identificar estoques futuros vencidos.


Consulta por id

GET /v1/estoques/{id} retorna o estoque mesmo quando excluído, com excluido = true.

Filtros disponíveis

Você pode aplicar os seguintes filtros na consulta GET, de forma independente ou combinada. Sem filtros, a consulta retorna todos os estoques da conta.

  • alterado_apos: retorna apenas os estoques alterados após a data e hora informadas, no formato AAAA-MM-DD HH:MM:SS. Sem este filtro, os estoques excluídos não são retornados.
  • ultimo_id: usado junto com alterado_apos para percorrer as páginas da consulta. Veja o guia Paginação.
  • divisao_id: retorna apenas os estoques da divisão informada. Disponível apenas nas contas de indústria com divisões.

Parâmetros de Envio (POST / PUT)

O POST requer um JSON com um objeto no body, representando o estoque a ser criado.

CampoTipoDescrição
codigo_integracaoString: 60Código do estoque no seu sistema. Quando informado, precisa ser único entre os estoques não excluídos da conta.
nome (obrigatório)String: 30Nome do estoque, com 1 a 30 caracteres.
ativo (obrigatório)BooleanIndica se o estoque está ativo.
estoque_futuroBooleanIndica se o estoque é futuro. Valor padrão: false.
data_previsao_chegadaDatePrevisão de chegada, no formato AAAA-MM-DD. Obrigatória quando estoque_futuro = true e não permitida quando estoque_futuro = false. Não pode ser anterior à data atual.
informacoes_adicionaisString: 100Observações sobre o estoque.
divisao_idIntegerIdentificador da divisão à qual o estoque pertence. Disponível apenas nas contas de indústria com divisões. Opcional: quando não informado, o Mercos usa a divisão associada à integração. Não pode ser alterado no PUT.

Os campos booleanos precisam ser enviados como booleanos JSON (true/false), e não como texto. Campos fora da tabela, inclusive os campos somente leitura do retorno (id e ultima_alteracao), respondem 422, com exceção de excluido no PUT.

⚠️

Importante

Cada divisão/representada tem um limite de estoques ativos conforme o plano: 5 no Performance e 15 no Enterprise. O estoque padrão conta no limite.

Alteração (PUT)

A alteração é feita pelo id do estoque no Mercos (/v1/estoques/{id}). O PUT é parcial: apenas os campos enviados são alterados e os demais são mantidos.

  • Para transformar um estoque futuro em físico, envie estoque_futuro = false e data_previsao_chegada = null.
  • Para transformar um estoque físico em futuro, envie estoque_futuro = true e a data_previsao_chegada.
  • A data mínima (data atual) só é validada quando a data_previsao_chegada muda. Um estoque futuro vencido pode ser alterado sem reenviar a data.
  • codigo_integracao enviado como null remove o código do estoque.
  • excluido = true exclui o estoque; os demais campos do corpo são ignorados. A resposta traz o estoque com excluido = true, e o codigo_integracao fica livre para reuso.
  • O estoque não pode mudar de divisão. Nas contas de indústria com divisões, o divisao_id enviado no PUT precisa ser o da divisão atual do estoque.

Erros

Estoque não encontrado (id inexistente, ou estoque já excluído no PUT) responde 404 com o corpo {"mensagem": "Estoque 123 inexistente para conta 456"}.

Erros de validação respondem 422 no formato {"mensagem": "Ocorreram erros de validação", "erros": [[campo, mensagem]], "url": "..."}. Erros de regra de negócio respondem 422 apenas com {"mensagem": "..."}. As principais mensagens são:

MensagemQuando ocorre
Os seguintes atributos são inválidos: "campo".O corpo traz uma chave fora das listadas em Parâmetros de Envio.
Atributo obrigatório não informadonome ou ativo ausente no POST.
Já existe um estoque com o código para esta empresa.O codigo_integracao já pertence a outro estoque não excluído.
Obrigatório para estoque futuro.estoque_futuro = true sem data_previsao_chegada.
Permitido apenas para estoque futuro.data_previsao_chegada informada em um estoque físico.
Não pode ser anterior a hoje.data_previsao_chegada anterior à data atual.
O limite de 5 estoques ativos do seu plano foi atingido.Limite de estoques ativos da divisão/representada atingido (veja Limite de estoques ativos).
O controle de estoque está desativado na representada 123POST ou PUT em uma divisão/representada sem controle de estoque.
O estoque não pertence à representada.PUT com divisao_id diferente da divisão atual do estoque.
Divisão inexistente.divisao_id que não pertence à conta.
Use divisao_id no lugar de representada_id.Conta de indústria com divisões enviando representada_id.

Contas sem acesso ao recurso respondem 412 com o corpo {"mensagem": "recurso não autorizado para o plano desta empresa"}.

Nas contas de indústria com divisões, o filtro ?divisao_id= inválido na consulta responde 412, como descrito no guia Indústrias com divisões.