Consultar promoções de um SKU
GET/seller/v1/skus/:sku_id/promotions
Consulta, centrado no produto, as promoções relacionadas a um SKU: as que ele já participa e as disponíveis para adesão, em uma lista única paginada.
Escopo da Operação
Inverte o eixo da consulta de promoções: em vez de abrir promoção por promoção para descobrir a situação de um produto, o seller informa o sku_id e recebe todas as promoções que importam para a estratégia daquele SKU, ordenadas e paginadas pelo servidor.
A resposta é uma lista paginada, com os itens em results e os dados de paginação em meta. Cada item reusa o payload de detalhe de SKU da Open API (channel, name, sku, status, price, investment, inventory, created_at, updated_at) e acrescenta o objeto promotion, com a promoção do seller à qual o SKU pertence ou pode aderir:
promotion.id— identificador público da participação da promoção do seller, o mesmo aceito no path deGET /seller/v1/promotions/{promotion_id}e nas operações de adesão e edição.promotion.name— nome da promoção.promotion.validity— vigência da promoção (starts_at,ends_atesubscription_deadline, o prazo de adesão).promotion.status— estado da promoção do seller:available(disponível para adesão),pending,processing,active,suspended,erroroufinished.
O status do item (fora do objeto promotion) é o estado da vinculação do SKU com a promoção, não o estado da promoção. Ele vem null apenas quando o SKU ainda não tem vínculo, caso em que promotion.status continua identificando a promoção — por exemplo, available para promoções abertas para adesão.
Parâmetros
sku_id(path, obrigatório): identificador do SKU do seller no catálogo do canal._limit(query, opcional): quantidade de itens retornados na página (padrão50, máximo50)._offset(query, opcional): posição inicial da página._sort(query, opcional): campo de ordenação (created_atouupdated_at), com sufixo:asc/:desc. Padrãocreated_at:desc. O campostatusnão é ordenável.
Regras de Negócio Comerciais
- Catálogo cruzado: o
sku_iddeve pertencer ao seller autenticado no canal informado. Com canal informado, quando o SKU pertence a outro tenant, é inexistente ou está inativo nesse canal, a API responde404 Not Found, sem distinguir o motivo. Sem canal informado, o catálogo é validado por canal de cada item: um mesmosku_idpode existir em alguns canais do tenant e não em outros, e a ausência em um canal não gera erro — o item segue com os dados do vínculo. - Elegibilidade por seleção de SKUs: promoções
admin_choicesó aparecem quando o SKU já foi inserido nelas pelo comercial; promoçõesseller_choiceaparecem sempre (o seller pode aderir com qualquer SKU); promoçõesfull_catalogaparecem quando o seller já entrou. - Item
seller_choicesem vínculo: quando o SKU ainda não aderiu a uma promoçãoseller_choice, o item é retornado comstatusnulo eprice/investmentcalculados como preview da adesão — o benefício e o subsídio vigentes da promoção aplicados sobre o preço de catálogo do SKU, no mesmo formato dos endpoints de detalhe de SKU. Como não há limite de vendas contratado,inventoryvem zerado. - Vigência da adesão: promoções em que o SKU não participa e cujo prazo de adesão (
subscription_deadline) já venceu não são retornadas. Para quem já aderiu, o prazo não se aplica. - Tipos de benefício cobertos:
percentage_discount,fidelity_discount,absolute_discountecoupon_discount. Promoções de outros tipos não são retornadas. - Precificação normalizada: valores monetários e percentuais são inteiros acompanhados do fator
normalizer: 100e da moedaBRL.
Comportamentos de Resposta
200 OK: lista paginada de promoções relacionadas ao SKU (results+metacompageelinks).resultsvazio quando não há promoções relacionadas.400 Bad Request: parâmetro_sortmalformado ou com campo fora da allowlist (created_at/updated_at).404 Not Found:sku_idque não pertence ao seller autenticado no canal informado (ou inexistente/inativo nele); ou, sem canal informado, ausência de seller ativo para oX-Tenant-Idnos canais não-sandbox.500 Internal Server Error: falha ao consultar a integração de catálogo do canal.
status (estado da vinculação) só é preenchido quando o SKU tem vínculo com a promoção, em estado publicado ou aguardando publicação. Um SKU inserido pelo comercial mas com vínculo ainda pendente de aprovação aparece com status preenchido e promotion.status refletindo o estado da promoção; um SKU que não foi inserido não aparece em promoções admin_choice.
A paginação e a ordenação são resolvidas na origem dos dados, sobre o conjunto completo de promoções relacionadas ao SKU — não há teto implícito de itens. Percorra as páginas por meta.links.next.
Em itens sem vínculo (status: null), price.promotional (deve utilizar o desconto mínimo exigido pela campanha aplicado sobre o preço de catálogo) e investment mostram o efeito que a promoção teria sobre o SKU — útil para decidir a adesão. Não são garantia de preço: o valor só passa a valer quando o SKU é vinculado e o vínculo é aprovado, e um SKU com vínculo pendente já reflete o preço e o limite de vendas gravados no próprio vínculo.
Escopo requerido
| Valor | Descrição |
|---|---|
open:promotion-skus-seller:read | Leitura de SKUs promocionais do seller |
Request
Responses
- 200
- 403
- 404
- 422
- 500
Sucesso
Proibido
- O seller '%{id_tenant}', de contexto '%{id_channel}', não foi encontrado ou está inativo no sistema.
Não encontrado
- O SKU não está ativo no site ou sem estoque, ou é inválido para o canal 'magalu' e para o seller 'example-tenant'.
Entidade não processável
- Unprocessable entity
Erro interno do servidor
- Internal server error