Logo Plataforma Yep
API REST · Plataforma Yep Documentação técnica para integrações homologadas

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.

REST JSON Bearer Token Novo em 2026

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.

200
Limit máximoPor página, quando especificado via limit.
20
Limit padrãoQuando limit é omitido ou inválido.
1+
Store explícitaDeterminístico em ambientes multi-store.
opt
Metadadostotal, last_page, has_next sob include_pagination=1.
POST/api2/products/

Criar produto configurável.

JSONCatálogo
{
  "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]
}
POST/api2/products/

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}
}
PATCH/api2/products/

Atualizar produto.

{
  "type": "sku",
  "id": "novo_produto",
  "name": "Novo nome do produto"
}
O update aceita sucesso parcial quando parte do payload for ignorada por campos, atributos ou valores inválidos. A resposta detalha invalid_fields, invalid_attributes e invalid_attribute_values.
Novo: a atualização de produtos também permite criar redirecionamentos permanentes (HTTP 301) ao modificar o 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.
PATCH/api2/products/categoriesNovo

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]
}
GET/api2/products/Atualizado

Consultar produto (individual) ou listar com paginação determinística.

?page=1&type=sku&id=novo_produto
A consulta individual passou a retornar referências legíveis, resumo de preço e resumo de estoque. Detalhes em Consulta individual de produto.
POST/api2/products/vincular

Vincular simples a configurável.

{
  "type": "sku",
  "configurable_id": "novo_produto",
  "simples": "novo_configuravel"
}
DELETE/api2/products/

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.

PATCH/api2/products/Novo parâmetro

Atualizar o url_key preservando a URL anterior.

JSONproducts/write
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 Obrigatório
ID ou SKU do produto a atualizar.
type Opcional
Tipo de identificação: id (padrão) ou sku.
store_id Opcional
ID da loja utilizada como contexto da atualização.
url_key Para alterar a URL
Nova chave de URL do produto, sem domínio ou barra inicial.
create_url_redirect Opcional
Booleano JSON (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.
  • false ou 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, 0 ou null são rejeitados com HTTP 400. Utilize exclusivamente os booleanos JSON true e false.
  • 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ódigoSituação
200Produto atualizado com sucesso.
400Parâmetro create_url_redirect inválido, JSON inválido ou id ausente.
404Produto não encontrado.
409Conflito de cadastro, como uma URL já utilizada por outro produto.
500Falha interna durante a operação.
503Indisponibilidade 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: true somente quando desejar preservar a URL anterior.
  • Evite requisições simultâneas de atualização de URL para o mesmo produto e trate erros 500 e 503 antes 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

Tradicional — 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.
Incremental — 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.

PATCH/api2/products/categoriesNovo

Adicionar e/ou remover vínculos entre um produto e categorias.

JSONGlobalproducts/write
PATCH /api2/products/categories
Authorization: Bearer {access_token}
Content-Type: application/json

Parâmetros aceitos

id Obrigatório
Identificador do produto. Pode representar o ID interno ou o SKU, conforme type.
type Opcional
id (padrão) ou sku.
add_category_ids Condicional
Array de IDs de categorias a adicionar.
remove_category_ids Condicional
Array de IDs de categorias a remover.
  • 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_id nã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.

Os IDs apresentados nos exemplos são ilustrativos e devem corresponder a produtos e categorias existentes na loja.

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ódigoSignificado
200Operação concluída, com ou sem mudança efetiva.
400Payload inválido, categoria inexistente, IDs conflitantes ou campos não aceitos.
401Autenticação ausente, inválida ou expirada.
403Integração sem permissão para a operação.
404Produto não encontrado.
405Método HTTP diferente de PATCH.
500Falha interna ou falha após tentativa de persistência.
503Operaçã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.

A operação não executa reindexação completa do catálogo nem altera os modos dos indexadores.

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/products informando o ID ou SKU. A resposta contém os campos categories e product_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.

Por SKU GET /api2/products?id=3291&type=sku
Por ID GET /api2/products?id=2074&type=id
Com store explícita GET /api2/products?id=3291&type=sku&store_id=1

Parâmetros

id Obrigatório
ID ou SKU do produto, conforme o type. Obrigatório apenas na consulta individual.
type Obrigatório
Define como o id é interpretado: id ou sku. Obrigatório apenas na consulta individual.
store_id Opcional
Store utilizada como contexto da leitura. Recomendado em qualquer integração multi-store.

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

product_set Novo
Conjunto de atributos do produto, com id e name.
product_categories Novo
Categorias vinculadas ao produto, com id e name no contexto da store consultada.
product_websites Novo
Websites vinculados ao produto, com id, code e name.
product_status Novo
Status do produto com value, code e label. Codes estáveis: enabled e disabled.
product_visibility Novo
Visibilidade com value, code e label. Codes estáveis: not_visible_individually, catalog, search e catalog_search.
Os campos 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çãoStatus
Sucesso200
Parâmetros inválidos400
Sem autenticação ou token inválido401
Sem permissão403
Produto não encontrado404
Falha interna500
A consulta individual de produto responde 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.

store_id Opcional Novo
Inteiro. ID da store a ser usada como contexto da listagem. Recomendado em qualquer integração multi-store.

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.

include_pagination Opcional Novo
Flag boolean (1 habilita). Quando ativa, inclui na resposta os campos total, last_page e has_next.
total
Total de produtos elegíveis para o filtro atual (apenas com include_pagination=1).
last_page
Número da última página considerando o limit corrente.
has_next
Boolean indicando se existe próxima página. Útil para terminar loops de sincronização com segurança.

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.

RegraValorComportamento
Padrão20Aplicado quando limit é omitido.
Máximo200Teto 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.

Listagem padrão GET /api2/products
Paginada GET /api2/products?page=2
Limite customizado GET /api2/products?page=1&limit=100
Busca por ID GET /api2/products?id=24404
Busca por SKU GET /api2/products?id=ABC-123&type=sku
Busca por ID explícita GET /api2/products?id=2074&type=id
Store explícita GET /api2/products?page=1&store_id=1
Com metadados 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 page explicitamente em rotinas de paginação.
  • Usar store_id sempre que a integração precisar de resultado determinístico em ambiente multi-store.
  • Preferir limit=50 ou limit=100 para sincronizações usuais.
  • Usar limit=200 apenas quando houver necessidade real de reduzir o número de chamadas.
  • Usar include_pagination=1 para controlar avanço de paginação com mais segurança (loop baseado em has_next).

Evitar

  • Enviar parâmetros como array em campos escalares — por exemplo id[] ou limit[].
  • 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.

Consulta por produtoGET /api2/products/imagem — imagens de um SKU ou ID, com papéis e disabled.
Inventário globalGET /api2/products/imagens — todas as imagens do catálogo, paginadas por cursor.
EscritaPOST, PUT e DELETE /api2/products/imagem — upload em base64, metadados e exclusão. DELETE /api2/products/imagens — exclusão total ou em lote.