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_chegadae 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
- Toda divisão/representada possui um estoque padrão, que existe automaticamente e não é um registro desta entidade. Ele NÃO é
retornado peloGETe NÃO pode ser alterado nem excluído por este endpoint.- Cada requisição ao criar e alterar manipula apenas um estoque, e para excluir é só utilizar o método
PUTenviando o campoexcluido = trueno corpo da requisição. Um estoque excluído não pode mais ser alterado.- 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)
| Campo | Tipo | Descrição |
|---|---|---|
| id | Integer | Identificador único do estoque no Mercos. |
| codigo_integracao | String: 60 | Código único do estoque no sistema que está integrando ao Mercos. |
| nome | String: 30 | Nome do estoque. |
| ativo | Boolean | Indica se o estoque está ativo. |
| estoque_futuro | Boolean | true quando o estoque possui data_previsao_chegada (estoque futuro); false para estoque físico. |
| data_previsao_chegada | Date | Previsão de chegada da mercadoria, no formato AAAA-MM-DD. null para estoque físico. |
| informacoes_adicionais | String: 100 | Observações sobre o estoque. null quando não informado. |
| excluido | Boolean | Indica se o estoque está excluído. |
| ultima_alteracao | DateTime | Data e hora da última modificação do estoque. |
| representada_id | Integer | Identificador da representada do registro. Retornado quando a sua conta não é uma indústria com divisões. |
| divisao_id | Integer | Identificador 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_chegadade um estoque futuro passa, o estoque deixa de contar como ativo, mas aultima_alteracaonão muda.
Use adata_previsao_chegadapara 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 formatoAAAA-MM-DD HH:MM:SS. Sem este filtro, os estoques excluídos não são retornados.ultimo_id: usado junto comalterado_apospara 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.
| Campo | Tipo | Descrição |
|---|---|---|
| codigo_integracao | String: 60 | Código do estoque no seu sistema. Quando informado, precisa ser único entre os estoques não excluídos da conta. |
| nome (obrigatório) | String: 30 | Nome do estoque, com 1 a 30 caracteres. |
| ativo (obrigatório) | Boolean | Indica se o estoque está ativo. |
| estoque_futuro | Boolean | Indica se o estoque é futuro. Valor padrão: false. |
| data_previsao_chegada | Date | Previsã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_adicionais | String: 100 | Observações sobre o estoque. |
| divisao_id | Integer | Identificador 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.
ImportanteCada 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 = falseedata_previsao_chegada = null. - Para transformar um estoque físico em futuro, envie
estoque_futuro = truee adata_previsao_chegada. - A data mínima (data atual) só é validada quando a
data_previsao_chegadamuda. Um estoque futuro vencido pode ser alterado sem reenviar a data. codigo_integracaoenviado comonullremove o código do estoque.excluido = trueexclui o estoque; os demais campos do corpo são ignorados. A resposta traz o estoque comexcluido = true, e ocodigo_integracaofica livre para reuso.- O estoque não pode mudar de divisão. Nas contas de indústria com divisões, o
divisao_idenviado noPUTprecisa 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:
| Mensagem | Quando 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 informado | nome 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 123 | POST 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.
