Produtos
Criação, atualização, consulta, vínculo, imagens e exclusão de produtos — com suporte a paginação determinística, seleção explícita de store_id, controle de limit e metadados opcionais de paginação.
Visão geral
O endpoint /api2/products é uma rota integracional/administrativa. Ele não se limita a produtos ativos de vitrine — ele expõe o catálogo para sincronização com ERPs, PIMs, marketplaces e rotinas internas. A rota suporta tanto listagem paginada quanto busca individual por id ou sku.
limit.limit é omitido ou inválido.total, last_page, has_next sob include_pagination=1.Criar produto configurável.
{
"attribute_set_id": 4,
"type_id": "configurable",
"visibility": 4,
"store_id": 1,
"sku": "novo_configuravel",
"name": "novo configuravel",
"description": "Descrição do produto configurável",
"short_description": "Curta descrição",
"price": 99.90,
"status": 1,
"tax_class_id": 2,
"categories": [54, 59, 128],
"website_id": [1],
"additional_attributes": {
"single_data": [
{"key": "color", "value": "AZUL"},
{"key": "ncm", "value": "5543"}
]
},
"configurable_attributes": [335]
}
Criar produto simples.
{
"type_id": "simple",
"attribute_set_id": 4,
"sku": "produto_teste",
"store_id": 1,
"name": "Produto teste",
"price": "2000",
"special_price": "150",
"weight": "0.5",
"status": 1,
"visibility": 4,
"categories": [54, 59, 128],
"website_id": [1],
"stock_data": {"qty": "99", "is_in_stock": 1}
}
Atualizar produto.
{
"type": "sku",
"id": "novo_produto",
"name": "Novo nome do produto"
}
invalid_fields, invalid_attributes e invalid_attribute_values.url_key. Para isso, envie o parâmetro opcional create_url_redirect: true. Consulte Redirecionamento permanente (301) ao atualizar URLs para exemplos e regras de utilização.Adicionar ou remover categorias específicas de um produto, sem substituir as demais.
{
"id": "SKU-123",
"type": "sku",
"add_category_ids": [60],
"remove_category_ids": [55]
}
Consultar produto (individual) ou listar com paginação determinística.
?page=1&type=sku&id=novo_produto
Vincular simples a configurável.
{
"type": "sku",
"configurable_id": "novo_produto",
"simples": "novo_configuravel"
}
Excluir produto.
{
"type": "sku",
"id": "novo_produto"
}
Redirecionamento permanente (301) ao atualizar URLs Novo
A API REST da Plataforma Yep permite criar redirecionamentos permanentes (HTTP 301) ao modificar a chave de URL (url_key) de produtos existentes.
Essa funcionalidade permite que integrações com ERPs, PIMs e outros sistemas atualizem URLs de produtos preservando o acesso aos endereços anteriores, quando elegíveis, reduzindo a ocorrência de links quebrados e erros 404.
O recurso utiliza o mecanismo nativo de histórico de URLs da Plataforma Yep e pode ser utilizado mesmo quando a criação automática de redirecionamentos estiver desabilitada nas configurações globais do catálogo.
Atualizar o url_key preservando a URL anterior.
PATCH /api2/products/
Authorization: Bearer {access_token}
Content-Type: application/json
{
"id": "SKU-123",
"type": "sku",
"store_id": 1,
"url_key": "produto-nova-url",
"create_url_redirect": true
}
Parâmetros
id (padrão) ou sku.true ou false). Quando true, solicita a preservação do histórico de URLs em caso de alteração efetiva.Exemplo de resposta — HTTP 200
{
"success": true,
"partial_success": false,
"message": "Produto atualizado com sucesso."
}
Comportamento do redirecionamento
Considere um produto com o endereço original https://loja.exemplo.com/produto-antigo. Após a atualização com create_url_redirect: true, sua nova URL poderá ser https://loja.exemplo.com/produto-nova-url.
Se o histórico puder ser criado pelo mecanismo nativo, o endereço anterior responderá com HTTP 301 apontando para a nova URL.
Alterações sucessivas também são suportadas. Os endereços históricos podem ser atualizados para apontar diretamente à URL mais recente, evitando cadeias desnecessárias de redirecionamentos.
Regras de funcionamento
true: solicita a criação do histórico permanente quando houver mudança efetiva da URL.falseou parâmetro ausente: mantém o comportamento anterior da API, sem solicitar explicitamente a criação do redirecionamento.- URL inalterada: nenhum histórico de URL é criado.
- Multi-store: a geração dos rewrites respeita o mecanismo nativo, incluindo herança de atributos e configurações de URLs das lojas vinculadas.
- Tipo inválido: valores como
"true","false",1,0ounullsão rejeitados com HTTP 400. Utilize exclusivamente os booleanos JSONtrueefalse. - Criação de produto: o parâmetro é exclusivo do PATCH de produtos existentes. No POST de criação ele é ignorado.
{
"error": "create_url_redirect deve ser um booleano JSON."
}
HTTP 200 não certifica o registro 301
A criação do histórico depende da existência de URLs anteriores registradas e das regras nativas de resolução de conflitos. Uma resposta HTTP 200 confirma que a atualização e o processamento solicitado foram concluídos sem exceção, mas não certifica individualmente a existência de um registro 301.
Respostas HTTP relevantes
| Código | Situação |
|---|---|
200 | Produto atualizado com sucesso. |
400 | Parâmetro create_url_redirect inválido, JSON inválido ou id ausente. |
404 | Produto não encontrado. |
409 | Conflito de cadastro, como uma URL já utilizada por outro produto. |
500 | Falha interna durante a operação. |
503 | Indisponibilidade ou bloqueio de processamento relacionado à atualização da URL. |
Falha depois do salvamento
Em situações de falha após o salvamento, o produto poderá ter sua URL atualizada sem a confirmação do redirecionamento. Nesse caso a resposta 500 ou 503 traz a mensagem "O produto pode já ter sido salvo, mas o redirecionamento 301 não foi confirmado." Antes de repetir a requisição, consulte a URL atual e verifique o histórico existente.
Recomendações para integrações
- Para atualizações em massa, envie uma requisição PATCH por produto, utilizando
create_url_redirect: truesomente quando desejar preservar a URL anterior. - Evite requisições simultâneas de atualização de URL para o mesmo produto e trate erros
500e503antes de realizar novas tentativas. - O recurso preserva URLs antigas durante novas alterações, mas não reconstrói automaticamente históricos inexistentes de alterações realizadas anteriormente.
Vínculo incremental de categorias de produtos Novo
A API REST da Plataforma Yep permite adicionar ou remover categorias específicas de um produto, sem substituir ou modificar as demais associações existentes.
Essa funcionalidade é especialmente indicada para integrações com ERPs, PIMs e sistemas externos que sincronizam categorias de produtos, preservando categorias de vitrines, campanhas e menus administradas diretamente na Plataforma Yep.
Diferença entre a atualização tradicional e a incremental
PATCH /api2/products/Ao enviar uma lista válida de categorias em categories ou category_ids, a API usa essa lista para substituir as associações do produto. Categorias que não estiverem na lista poderão ser removidas.PATCH /api2/products/categoriesA API modifica exclusivamente os vínculos informados em add_category_ids e remove_category_ids. As demais categorias permanecem associadas ao produto, independentemente de sua posição na árvore ou da forma como foram cadastradas.Autenticação e permissões
A operação exige autenticação por Bearer Token e a permissão de escrita de produtos (products/write) na ACL da integração.
Adicionar e/ou remover vínculos entre um produto e categorias.
PATCH /api2/products/categories
Authorization: Bearer {access_token}
Content-Type: application/json
Parâmetros aceitos
type.id (padrão) ou sku.- Pelo menos uma das listas deve conter um ID. É permitido enviar somente adições, somente remoções ou ambas na mesma requisição.
- Os IDs das categorias devem ser inteiros positivos ou strings numéricas inteiras. As categorias informadas precisam existir no catálogo.
store_idnão é aceito, pois os vínculos diretos entre produtos e categorias são globais.- Campos além dos quatro acima são rejeitados com HTTP 400.
Exemplo 1 — Adicionar e remover simultaneamente
{
"id": "SKU-123",
"type": "sku",
"add_category_ids": [60],
"remove_category_ids": [55]
}
A API adiciona a categoria 60 e remove a categoria 55, preservando todas as demais associações.
Resposta de sucesso — HTTP 200
{
"success": true,
"changed": true,
"product_id": 12345,
"added_category_ids": [60],
"removed_category_ids": [55]
}
Exemplo 2 — Somente adicionar categorias
{
"id": "SKU-123",
"type": "sku",
"add_category_ids": [60, 61]
}
A API adiciona as categorias informadas, desde que ainda não estejam vinculadas. Nenhuma categoria existente será removida.
Exemplo 3 — Somente remover categorias
{
"id": "SKU-123",
"type": "sku",
"remove_category_ids": [55, 56]
}
Somente as categorias informadas serão desvinculadas. As demais associações permanecerão intactas.
Idempotência e prevenção de alterações desnecessárias
- Adicionar uma categoria já vinculada não gera duplicidade.
- Remover uma categoria que não está vinculada não provoca erro.
- IDs repetidos são normalizados antes do processamento.
- Quando nenhuma associação precisa ser modificada, o produto não é salvo novamente.
added_category_ids e removed_category_ids listam apenas os vínculos efetivamente alterados. Resposta sem alterações — HTTP 200:
{
"success": true,
"changed": false,
"product_id": 12345,
"added_category_ids": [],
"removed_category_ids": []
}
Validação integral das requisições
Diferentemente da atualização genérica de produtos, essa operação não aceita sucesso parcial de validação. Antes de modificar o produto, a API verifica os campos recebidos, os IDs e a existência das categorias. A requisição é rejeitada integralmente quando houver valores inválidos ou conflitantes.
{
"id": "SKU-123",
"type": "sku",
"add_category_ids": [60],
"remove_category_ids": [60]
}
Resposta — HTTP 400
{
"error": "Uma categoria não pode ser adicionada e removida na mesma requisição."
}
Nesse cenário, nenhuma associação é alterada.
Respostas HTTP
| Código | Significado |
|---|---|
200 | Operação concluída, com ou sem mudança efetiva. |
400 | Payload inválido, categoria inexistente, IDs conflitantes ou campos não aceitos. |
401 | Autenticação ausente, inválida ou expirada. |
403 | Integração sem permissão para a operação. |
404 | Produto não encontrado. |
405 | Método HTTP diferente de PATCH. |
500 | Falha interna ou falha após tentativa de persistência. |
503 | Operação temporariamente bloqueada por concorrência ou indisponibilidade. |
Falha depois do salvamento
Caso ocorra falha depois do salvamento, as associações poderão já estar persistidas, mesmo com resposta de erro. Consulte o estado atual do produto antes de repetir a operação.
Indexação, cache e exibição na vitrine
A operação utiliza o salvamento nativo de produtos da Plataforma Yep, preservando os mecanismos existentes de indexação e atualização do catálogo. Quando há alteração efetiva, são processadas as associações do produto e acionados os mecanismos nativos de indexação, respeitando os modos configurados no ambiente.
A API também solicita invalidação direcionada de cache para as categorias afetadas e seus ancestrais pertinentes. Em ambientes com indexadores manuais ou bloqueados, a exibição das alterações na vitrine poderá depender do processamento posterior desses índices.
Considerações sobre categorias e lojas
- Os vínculos são aplicados diretamente ao produto e não são específicos por store view.
- Adicionar uma subcategoria não adiciona automaticamente seus ancestrais como vínculos diretos. Categorias âncora podem apresentar produtos por meio das regras normais de indexação.
- Em produtos configuráveis, a associação realizada no produto pai não é propagada automaticamente aos produtos simples relacionados.
- A exibição efetiva na loja também depende de website, árvore de categorias, status, visibilidade e configurações da vitrine.
Recomendações para integrações
- Para sincronizações em massa, execute uma requisição por produto e envie apenas os IDs de categorias que precisam ser adicionados ou removidos.
- Evite atualizações concorrentes de categorias do mesmo produto por diferentes sistemas.
- Para consultar as categorias vinculadas a um produto, utilize
GET /api2/productsinformando o ID ou SKU. A resposta contém os camposcategorieseproduct_categories.
Proteção limitada ao próprio endpoint
O endpoint preserva as associações não mencionadas, mas uma atualização tradicional que substitua a lista completa de categorias, feita pelo Admin ou por outra integração, ainda poderá sobrescrever vínculos existentes. O mecanismo de proteção contra concorrência coordena chamadas do próprio endpoint incremental; ele não bloqueia os demais processos de manutenção de produtos.
Vínculos, não a árvore
Esse endpoint modifica vínculos entre produtos e categorias. Ele não cria, exclui, renomeia ou movimenta categorias na árvore. Para essas operações, consulte Categorias.
Consulta individual de produto Atualizado
O GET /api2/products continua atendendo à listagem quando usado sem identificação individual. Para trazer um único produto, informe id e type. Nessa forma de uso a resposta passa a incluir referências legíveis (conjunto de atributos, categorias, websites, status e visibilidade), além de um resumo de preço e um resumo de estoque.
GET /api2/products?id=3291&type=sku
GET /api2/products?id=2074&type=id
GET /api2/products?id=3291&type=sku&store_id=1
Parâmetros
type. Obrigatório apenas na consulta individual.id é interpretado: id ou sku. Obrigatório apenas na consulta individual.Exemplo de resposta — produto simples
{
"success": true,
"product": {
"product_id": "2074",
"sku": "3291",
"name": "Cápsulas de Café União Ristretto 10 unidades",
"set": "4",
"product_set": {
"id": "4",
"name": "Default"
},
"type": "simple",
"categories": ["122", "124"],
"product_categories": [
{"id": "122", "name": "Cápsulas Compatíveis"},
{"id": "124", "name": "Cafés"}
],
"websites": ["1"],
"product_websites": [
{"id": "1", "code": "cafe", "name": "Website Principal"}
],
"status": "1",
"product_status": {
"value": "1",
"code": "enabled",
"label": "Habilitado"
},
"visibility": "4",
"product_visibility": {
"value": "4",
"code": "catalog_search",
"label": "Catálogo, Busca"
},
"created_at": "2025-12-01T12:02:21-03:00",
"updated_at": "2025-12-01 19:57:58",
"pricing": {
"price": "28.9000",
"special_price": "25.9000",
"final_price": "25.9000",
"currency": "BRL"
},
"inventory": {
"inventory_manage_stock": true,
"inventory_qty": "38.0000",
"inventory_stock_availability": "in_stock",
"inventory_stock_availability_label": "Em Estoque",
"inventory_is_salable": true
}
}
}
Retrocompatibilidade
Os campos históricos continuam presentes e com a mesma semântica: set, categories, websites, status e visibility. Os objetos product_set, product_categories, product_websites, product_status, product_visibility, pricing e inventory são aditivos.
- Integrações existentes podem continuar utilizando apenas os campos históricos, sem nenhuma alteração.
- Novas integrações devem preferir os objetos enriquecidos quando precisarem de nome, código ou label sem consultar o painel manualmente.
Referências enriquecidas
id e name.id e name no contexto da store consultada.id, code e name.value, code e label. Codes estáveis: enabled e disabled.value, code e label. Codes estáveis: not_visible_individually, catalog, search e catalog_search.label e name são destinados à apresentação e podem acompanhar o idioma e a configuração da Plataforma Yep. Para lógica de integração, prefira id, value e code.Resumo de preço
O bloco pricing entrega uma visão rápida do preço do produto no contexto consultado.
{
"price": "28.9000",
"special_price": "25.9000",
"final_price": "25.9000",
"currency": "BRL"
}
Resumo de estoque
O bloco inventory entrega uma visão rápida da disponibilidade.
{
"inventory_manage_stock": true,
"inventory_qty": "38.0000",
"inventory_stock_availability": "in_stock",
"inventory_stock_availability_label": "Em Estoque",
"inventory_is_salable": true
}
Quando usar os endpoints dedicados
Os resumos acima cobrem a maior parte das sincronizações. Para o detalhamento completo de preço (group prices, tier prices, classe fiscal, MSRP) use GET /api2/price. Para a configuração completa de estoque (backorders, incrementos, herança de configuração) use GET /api2/stock.
Respostas HTTP
| Situação | Status |
|---|---|
| Sucesso | 200 |
| Parâmetros inválidos | 400 |
| Sem autenticação ou token inválido | 401 |
| Sem permissão | 403 |
| Produto não encontrado | 404 |
| Falha interna | 500 |
200. Os 201 utilizados na criação de recursos permanecem inalterados.Novidades do GET /api2/products
Três evoluções principais foram incorporadas ao endpoint de listagem, tornando-o mais previsível em ambientes multi-store e mais eficiente para sincronizações em lote.
5) Suporte a store_id opcional Novo
Agora é possível informar store_id para tornar o resultado explícito e determinístico em cenários multi-store. Sem esse parâmetro, a seleção de store segue a regra default do ambiente; com ele, a integração assume o controle.
Exemplo
GET /api2/products?page=1&store_id=1
6) Metadados opcionais de paginação Novo
Foi adicionado suporte opcional a campos de paginação no corpo da resposta. Eles só são retornados quando for enviado include_pagination=1, evitando overhead em sincronizações que não precisam desses metadados.
1 habilita). Quando ativa, inclui na resposta os campos total, last_page e has_next.include_pagination=1).limit corrente.Exemplo
GET /api2/products?page=1&include_pagination=1
7) Suporte a limit opcional Novo
O endpoint aceita limit para definir a quantidade de produtos por página. Valores inválidos (não numéricos, arrays, negativos, zero ou acima do máximo) são normalizados para o padrão, garantindo que nenhuma requisição quebre por entrada inesperada.
| Regra | Valor | Comportamento |
|---|---|---|
| Padrão | 20 | Aplicado quando limit é omitido. |
| Máximo | 200 | Teto rígido para proteger a rota em cenários de alta carga. |
| Inválido | — | Valores inválidos são normalizados para 20. |
Exemplos
GET /api2/products?page=1&limit=50
GET /api2/products?page=1&limit=200
Formas de uso suportadas
Referência rápida das combinações testadas e homologadas para o GET /api2/products.
GET /api2/products
GET /api2/products?page=2
GET /api2/products?page=1&limit=100
GET /api2/products?id=24404
GET /api2/products?id=ABC-123&type=sku
GET /api2/products?id=2074&type=id
GET /api2/products?page=1&store_id=1
GET /api2/products?page=1&limit=100&include_pagination=1
Recomendações para integração
Boas práticas consolidadas após a evolução do endpoint. Seguir essas diretrizes reduz retrabalho, evita paginação infinita e garante determinismo em ambientes multi-store.
Recomendado
- Enviar sempre
pageexplicitamente em rotinas de paginação. - Usar
store_idsempre que a integração precisar de resultado determinístico em ambiente multi-store. - Preferir
limit=50oulimit=100para sincronizações usuais. - Usar
limit=200apenas quando houver necessidade real de reduzir o número de chamadas. - Usar
include_pagination=1para controlar avanço de paginação com mais segurança (loop baseado emhas_next).
Evitar
- Enviar parâmetros como array em campos escalares — por exemplo
id[]oulimit[]. - Considerar que o endpoint retorna apenas produtos ativos de vitrine. Esta rota é integracional/administrativa.
- Depender de ordenação implícita entre páginas em cenários multi-store sem
store_id.
Dica de sincronização
Para sincronizações periódicas, combine store_id + limit=100 + include_pagination=1. Você obtém determinismo, throughput equilibrado e um critério de parada confiável (has_next=false).
Imagens de produto
Para consultar, reconciliar, incluir, atualizar ou excluir imagens de produtos, consulte Catálogo › Imagens.
GET /api2/products/imagem — imagens de um SKU ou ID, com papéis e disabled.GET /api2/products/imagens — todas as imagens do catálogo, paginadas por cursor.POST, PUT e DELETE /api2/products/imagem — upload em base64, metadados e exclusão. DELETE /api2/products/imagens — exclusão total ou em lote.