Passar para o conteúdo principal

Utilizando o Controle de Lote e Validade via API

Neste artigo, descubra como utilizar/cadastrar Lotes para suas Ordens de Produção, Pedidos de Venda, Compras de Produtos e demais processos via API.

Ygor Bastos avatar
Escrito por Ygor Bastos
Atualizado há mais de uma semana

Com o Controle de Lote e Validade, você acompanha cada lote dos seus produtos de forma organizada, registrando datas de fabricação e validade.

E para tornar sua gestão ainda mais ágil e integrada, agora é possível utilizar esse recurso também via API, permitindo que seu sistema se conecte ao Omie e mantenha todas as informações sempre atualizadas, sem esforço manual.

Tópicos do Artigo:

Informações Importantes sobre as APIs do Omie

Antes de iniciar seus testes com a nossa API, é fundamental conhecer alguns processos básicos:

  • ✅ Acessando a documentação: Consulte nossa documentação oficial para entender os endpoints disponíveis e seus respectivos parâmetros.

  • ⚙️ Características e Recomendações: Fique por dentro das melhores práticas para otimizar sua experiência com a API da Omie
    ​

  • 🔐 Login no Portal: Para testar suas requisições no Portal do Desenvolvedor é necessário fazer login na plataforma com o mesmo e-mail e senha que você já usa no ERP. Fácil, né? 😉
    ​

  • 🧪 Aplicativo Teste: Aprenda a criar um Aplicativo Teste gratuito e descubra, na prática, como utilizar nossas APIs e aproveitar ao máximo os nosso recursos.

💡 Dica Omie: Você pode testar nossas APIs diretamente no nosso Portal do Desenvolvedor. Além disso, ferramentas como Postman, Insomnia e ThunderClient (extensão do VS Code) também são ótimas opções para realizar testes.

Conhecendo recurso de Lote e Validade via API

1) Para interagir via API com o Controle de Lote e Validade, é necessário que o Controle de Lotes esteja ativo em seu aplicativo.
​
Confira nossa documentação completa sobre o processo de configuração:
​

Configurando o Controle de Lote e Validade

2) E também, é necessário ativar a utilização de Lotes para os produtos que de interesse:

Ativando o Controle de Lote e Validade no produto

3) Após configurar o Controle de Lotes, acesse o Portal do Desenvolvedor, e acesse a lista de APIs:

4) No tópico "Compras, Estoque e Produção", selecione a opção "Produtos - Lote":

💡 Também é possível acessar este método no tópico "Vendas e NF-e":

5) Nesta aba, você terá os dois métodos principais para monitorar o Lote de seus produtos.

Verificando os Lotes que possuo no sistema

Listando todos os Lotes que possuo

Com o método “ListarLotes”, você pode consultar todos os lotes cadastrados dos produtos que possuem a gestão de Lotes ativada.

Esta requisição utiliza os seguintes parâmetros:

  • nPagina (Obrigatório)

  • nRegPorPagina (Obrigatório)

  • cFiltrarApenasInclusao (Opcional)

  • cFiltrarApenasAlteracao (Opcional)

  • cFiltrarPorDataAte (Opcional)
    ​

Como retorno, essa requisição terá as informações do produto dentro do Array "ident" e as informações do lote relacionados a ele pelo array "lotes".
​

Consultando o Lote de um produto específico

Utilizando o método "ConsultarLote" é possível verificar os Lotes cadastrados de um produto em específico que você possui a gestão de Lote ativada.

Esta requisição utiliza os seguintes parâmetros:

  • nCodProd (Obrigatório)
    ​

    ou
    ​

  • cCodIntProd(Obrigatório)

Como retorno, essa requisição terá as informações do produto dentro do Array "ident" e as informações do lote relacionados a ele pelo array "lotes".

💡 Boas práticas na utilização da API

Para evitar bloqueios por rate limit e também manter uma consulta otimizada, é recomendado utilizar o método "ConsultarLote" apenas em situações necessárias.
​
​As consultas recorrentes que mantém atualizado seu registro interno de Lotes precisam ser realizadas pelo método "ListarLotes". Nele, você poderá, de forma incremental, realizar a consulta usando os parâmetros:

  • "cFiltrarPorDataDe": Data de sua última consulta

  • "cFiltrarPorDataAte": Data atual

Exemplo


Considerando que minha última consulta tenha sido feita no dia 11/09:

{

"nPagina": 1,

"nRegPorPagina": 1000,

"cFiltrarPorDataDe": "11/09/2025",

"cFiltrarPorDataAte": "12/09/2025"

}

Manipulando os Lotes em suas requisições

Após ter seus Produtos e Lotes configurados, é possível em seus processos indicar por meio do array "lote_validade", quais lotes serão consumidos ou cadastrados.

Ele pode ser consumido em um processo de saída, como:

  • Pedidos de Venda

  • Ordens de Produção (caso a matéria-prima tenha Lote)

  • Remessas de Produtos

  • Devoluções ao Fornecedor

  • Movimento Manual de Estoque de Saída

Ou, pode ser adicionado em um processo de entrada:

  • Movimento Manual de Estoque de Entrada ou Ajuste

  • Recebimento de Notas Fiscais do Fornecedor

  • Notas de Entrada

  • Devolução de Venda

  • Nota de Importação

Os lotes apenas podem ser adicionados por meio de Operações de Entrada de seus Produtos, a seguir, demonstraremos como utilizar este array em cada operação.

💡 A manipulação dos lotes via API é obrigatória em seu processo caso a configuração de lotes esteja como "Manual - INFO"

Pois, esta parametrização define que em cada movimentação será necessário informar manualmente qual lote será utilizado:

Para as demais opções:

  • Primeiro a vencer, primeiro a sair - FEFO (First expired, first out)

  • Primeiro a entrar, primeiro a sair - FIFO (First in, first out)

  • Último a entrar, primeiro a sair - LIFO (Last In, first out)

Não é obrigatório o preenchimento dos parâmetros de Lote no momento de realizar a requisição de seus processos, pois ele obedecerá ao método de consumo do lote escolhido

Métodos que realizam Movimentos de Entrada do Lote

Ao utilizar o array "lote_validade" para representar o novo Lote em processos de entrada, você terá os seguintes parâmetros a serem informados:

  • nIdLote (Opcional caso preencha apenas "cNumLote") - ID do Lote

  • nQtdLote (Obrigatório) - Quantidade que será adicionada ao Lote

  • cNumLote (Opcional caso "nIdLote" não informado) - Número do Lote

  • cCodAgreg (Opcional caso "nIdLote" não informado) - Código de Agregação do lote do produto

  • dDataFab (Opcional) - Data de Fabricação do Produto, caso não informado será utilizado a data atual

  • dDataVal (Opcional) - Data de validade do produto

Exemplo:

Veja um exemplo de requisição indicando o Lote que será adicionado no Produto em uma Movimentação Manual de Estoque, utilizando o método "IncluirAjusteEstoque":

{
            "codigo_local_estoque": 740798,
            "id_prod": 14112838,
            "data": "10/09/2025",
            "quan": "15",
            "obs": "Ajuste feito pela ferramenta de Teste de API (52846)",
            "origem": "AJU",
            "tipo": "ENT",
            "motivo": "INV",
            "valor": 10,
            "lote_validade": [
                {
                    "cNumLote": 55556,
                    "nQtdLote": 1,
                    "cCodAgreg": 56567
                },
                {
                    "cNumLote": 55557,
                    "nQtdLote": 14,
                    "cCodAgreg": 5656
                }
            ]
        }

Métodos que realizam Movimentos de Saída do Lote

Ao utilizar o array "lote_validade" para consumir um Lote em processos de saída, os seguintes parâmetros terão de ser informados:

  • nIdLote (Obrigatório) - Id do Lote a ser utilizado

  • nQtdLote (Obrigatório) - Quantidade deste Lote que será utilizado

Exemplo:

Veja um exemplo de requisição indicando o Lote que será consumido de uma matéria-prima, em uma Ordem de Produção, utilizando o método "IncluirOrdemProducao":

    {
      "identificacao": {
        "cCodIntOP": "OP0022012",
        "dDtPrevisao": "08/09/2025",
        "nCodProduto": "1470659",
        "nQtde": 3
      },
      "itens": [
        {
          "nIdProdutoMalha": 14112838,
          "cUtilizarDoEstoque": "N",
          "lote_validade": [
            {
              "nIdLote": 26977390,
              "nQtdLote": 1.1
            },
            {
              "nIdLote": 25800063,
              "nQtdLote": 0.9
            }
          ]
        }
      ]
    }

📚 Artigos Relacionados

Assinatura.png
Respondeu à sua pergunta?