Passar para o conteúdo principal

Utilizando Variações dos Produtos via API

Neste artigo, descubra como utilizar/cadastrar Variações de seus Produtos para utilização em 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

A Grade de Variações é um recurso que permite o controle dos seus produtos que possuem diferenciações, como cores, tamanhos, modelos ou outras variações.

Em vez de cadastrar cada variação como um produto separado, você organiza tudo em uma única estrutura.

Visando manter toda sua gestão completamente integrada, é 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 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 recursos de Variação via API

1) Para utilizar a Variação via API, é necessário que o Produto que será utilizado esteja configurado utilizar de Variações, e suas Variações também estejam cadastradas em sistema.

Neste processo, para cadastrar um Produto que terá Variações, indique o parâmetro "produto_variacao" como "S". Assim ele estará disponível para receber a Grade de Variações.
​
Confira nossa documentação completa sobre o processo de cadastro de Produto via API:
​

Cadastrando um Produto via API

2) Após ter cadastrado os Produtos que tem Grade de Variações, acesse o Portal do Desenvolvedor, e acesse a lista de APIs:

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

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

4) Nesta aba, você terá os três métodos principais para gerenciar suas Grades de Variação.

No próximo tópico, vamos detalhar cada método para que você saiba exatamente como utilizá-los.

Verificando as Variações de meus Produtos

Listando todas as Variações que possuo

Com o método “ListarVariacoes”, você pode consultar todas as Variações cadastradas dos produtos que possuem a gestão de Grade de Variação ativa.

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

  • nPagina (Obrigatório)

  • nRegPorPagina (Obrigatório)

  • cFiltrarPorDataDe (Opcional)

  • cFiltrarPorDataAte (Opcional)

  • cFiltrarApenasInclusao (Opcional)

  • cFiltrarApenasAlteracao (Opcional)

  • cExibirCaracteristicas (Opcional)

Ao realizar essa requisição, o sistema retornará o array "listaVariacoes".

Dentro dele, você encontrará:

  • O array "ident", que traz as informações do item principal que possui variações;
    ​

  • O array "variacoes", que exibe todas as variações já cadastradas para esse produto, como tamanhos, cores ou outros atributos configurados.

Dessa forma, você terá uma visão tanto do produto principal quanto de todas as suas variações em um único retorno.

Consultando as Variações de um produto específico

Utilizando o método "ConsultarVariacoes" é possível verificar as Variações cadastradas de um produto em específico que você possui a gestão de Grade de Variação ativada.

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

  • nCodProd (Obrigatório)
    ​

    ou
    ​

  • cCodIntProd(Obrigatório)

Como retorno, essa requisição terá o array "ident" contendo as informações do item que tem Variação e o array "variacoes" que exibe as variações cadastradas deste Produto que foi consultado

💡 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 "ConsultarVariacoes" apenas em situações necessárias.
​
​As consultas recorrentes que mantém atualizado seu registro interno de Variações precisam ser realizadas pelo método "ListarVariacoes". 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"

}

Incluindo Variações

A Variação de Produtos é realizada por meio de Características de Produtos cadastradas no Omie, como, por exemplo “Cor”, “Tamanho”, “Material” ou qualquer outro atributo que ajude a diferenciar um item.

Cada produto no Omie pode ter variações configuradas a partir de uma ou duas Características principais, como cor ou tamanho. Nesse processo, você pode optar por deixar que o sistema crie automaticamente cada nova variação com base nessas combinações ou, se preferir, associar um produto já existente à variação que será criada.

Esta inclusão ocorre pelo método "IncluirVariacoes", utilizando os seguintes parâmetros:

  • nCodProd (Obrigatório) - Código do Produto pai da Variação

  • cCodIntProd (Opcional caso não tenha "nCodProd") - Código de integração do Produto

  • aCaracteristicas [Array] (Obrigatório)

    • nIdCaract (Obrigatório) - Código interno da Característica

  • aVariacoes [Array] (Opcional) - Esse array precisa ser preenchido caso precise que algum Produto seja associado ou que alguma alteração, seja necessária na criação da Variação

    • nCodProdAssoc (Opcional) - Código interno do Produto que será associado a essa Variação

    • cDescrProduto (Opcional) - Descrição que o Produto criado pela Variação terá

    • cCodProduto (Opcional) - Código que o Produto criado pela Variação terá

    • 'aValoresCaracteristicas [Array] (Opcional) - Array Necessário para informar qual dos preenchimentos da/s características será alterado ou associado

      • nIdCaract (Opcional) - Código interno da Característica

      • nIdValor (Opcional) - Código interno do valor da Característica

Cadastrando novos produtos para cada variação

Ao informar apenas o Produto Pai e a Característica que deseja utilizar, o Omie gera automaticamente as variações como novos produtos no sistema. Para que isso aconteça, é necessário utilizar os seguintes parâmetros:

  • nCodProd - Código do Produto pai da Variação

  • aCaracteristicas [Array]

    • nIdCaract - Código interno da Característica

Exemplo de Requisição

{
            "nCodProd": 27614191,
            "aCaracteristicas": [
                {
                    "nIdCaract": 1573549
                }
            ]
        }

Associando um produto existe a uma Variação

Imagine que você esteja utilizando a característica “Cor”, com os preenchimentos “Vermelho”, “Amarelo”, “Verde” e “Roxo”.

Por padrão, ao cadastrar as variações, o Omie cria automaticamente novos Produtos para cada combinação de característica. No entanto, pode haver situações em que você já tenha um produto previamente cadastrado e queira associá-lo diretamente a uma dessas variações, em nosso exemplo, a variação “Roxo”.

Para que essa associação ocorra, em vez de cadastrar um novo produto, é necessário informar os parâmetros que indicam ao sistema qual produto existente deve ser vinculado à variação escolhida.

  • nCodProd - Código do Produto pai da Variação

  • aCaracteristicas [Array]

    • nIdCaract - Código interno da Característica

  • aVariacoes [Array]

    • nCodProdAssoc - Código interno do Produto que será associado a essa Variação

    • cDescrProduto - Descrição do produto, o nome pelo qual a nova variação será identificada no sistema.

    • cCodProduto - Código que o Produto criado pela Variação terá

    • 'aValoresCaracteristicas [Array] - Array Necessário para informar qual dos preenchimentos da/s características será alterado ou associado

      • nIdCaract - Código interno da Característica

      • nIdValor - Código interno do valor da Característica

Exemplo de Requisição

{
            "nCodProd": 28648533,
            "aCaracteristicas": [
                {
                    "nIdCaract": 1573549
                }
            ],
            "aVariacoes": [
                {
                    "nCodProdAssoc": 26277790,
                    "aValoresCaracteristicas": [
                        {
                            "nIdCaract": 1573549,
                            "nIdValor": 28647121
                        }
                    ]
                },
                {
                    "cDescrProduto": "Produto teste - Vermelho",
                    "cCodProduto": 12345678,
                    "aValoresCaracteristicas": [
                        {
                            "nIdCaract": 1573549,
                            "nIdValor": 1573577
                        }
                    ]
                },
                {
                    "cDescrProduto": "Produto teste - Verde",
                    "cCodProduto": 1234567,
                    "aValoresCaracteristicas": [
                        {
                            "nIdCaract": 1573549,
                            "nIdValor": 1573570
                        }
                    ]
                },
                {
                    "cDescrProduto": "Produto teste - Amarelo",
                    "cCodProduto": 123456,
                    "aValoresCaracteristicas": [
                        {
                            "nIdCaract": 1573549,
                            "nIdValor": 1573563
                        }
                    ]
                }
            ]
        }

📣 Lembrete

Se você optar por adicionar Variações a um produto já cadastrado, é necessário que este produto não tenha movimentações de estoque.

Manipulando as Variações em suas requisições

As variações substituem o Produto Pai nos processos em que são utilizadas

Ou seja, em qualquer operação de entrada ou saída, o sistema passa a utilizar o código da variação.

  • Exemplo:

    Considere o produto “Camiseta - Roxa”, com codigo_produto: 125789, que é uma variação do produto “Camiseta”, cujo codigo_produto é 125788.
    ​
    Ao utilizar o produto em um Pedido de Venda, o campo codigo_produto deve corresponder à Variação que você está vendendo. No caso da “Camiseta - Roxa”, o código correto é 125789.

    Se você tentar preencher o campo com o código do produto pai em vez da variação, o sistema exibirá o seguinte erro:

    "ERROR: Esse produto possui variações e não pode ser movimentado, nesse caso deve ser informada uma das variações do produto no seu lugar. Tag: [codigo_produto=125789]."

📚 Artigos Relacionados

Respondeu à sua pergunta?