Com o Controle de Lote e Validade, você acompanha cada lote dos seus produtos de forma organizada, registrando datas de fabricação e validade.
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.
🔑 Chaves de Integração da API: Saiba como obter e utilizar suas credenciais de acesso para autenticar as requisições.
⚙️ 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.
🧪 Aplicativo Teste: Aprenda a criar um Aplicativo Teste gratuito e descubra, na prática, como utilizar nossas APIs e aproveitar ao máximo os nossos 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:
2) E também é necessário ativar a utilização de Lotes para os produtos de interesse:
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":
5) Nesta aba, você terá os dois métodos principais para monitorar os Lotes de seus produtos: ConsultarLote (1) e ListarLotes (2):
Verificando os Lotes que possuo no sistema
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"
}
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 ativa.
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".
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
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".
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 informada, será utilizada 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.
🔎 Especificidades da Ordem de Produção
Para os métodos "IncluirOrdemProducao" e "AlterarOrdemProdução", especificamente, o array utilizado para o Produto Principal (Produto Pai) é o "
lote_validade_op".Para o array "lote_validade_op", o parâmetro nIdLote é opcional. Porém, quando não informada, o parâmetro cNumLote torna-se obrigatório, e o "lote_validade_op" passa a aceitar cCodAgreg, dDataFab e dDataVal como parâmetros.
O "
lote_validade" é referente aos Itens do Produto (Produtos Filhos).
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": "OP-81040-NOVO-01",
"nCodProduto": 0,
"dDtPrevisao": "30/09/2026",
"nQtde": 10,
"codigo_local_estoque": 0,
"lote_validade_op": {
"cNumLote": "LOTE-81040-A",
"cCodAgreg": "AGREG-81040",
"dDataFab": "01/09/2026",
"dDataVal": "01/09/2027"
}
},
"itens": [
{
"nIdProdutoMalha": 14112838,
"cUtilizarDoEstoque": "N",
"lote_validade": [
{
"nIdLote": 26977390,
"nQtdLote": 1
}
]
}
]
}