Pular para o conteúdo principal

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 de GET /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_at e subscription_deadline, o prazo de adesão).
  • promotion.status — estado da promoção do seller: available (disponível para adesão), pending, processing, active, suspended, error ou finished.

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ão 50, máximo 50).
  • _offset (query, opcional): posição inicial da página.
  • _sort (query, opcional): campo de ordenação (created_at ou updated_at), com sufixo :asc/:desc. Padrão created_at:desc. O campo status não é ordenável.

Regras de Negócio Comerciais​

  • Catálogo cruzado: o sku_id deve 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 responde 404 Not Found, sem distinguir o motivo. Sem canal informado, o catálogo é validado por canal de cada item: um mesmo sku_id pode 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_choice só aparecem quando o SKU já foi inserido nelas pelo comercial; promoções seller_choice aparecem sempre (o seller pode aderir com qualquer SKU); promoções full_catalog aparecem quando o seller já entrou.
  • Item seller_choice sem vínculo: quando o SKU ainda não aderiu a uma promoção seller_choice, o item é retornado com status nulo e price/investment calculados 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, inventory vem 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_discount e coupon_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: 100 e da moeda BRL.

Comportamentos de Resposta​

  • 200 OK: lista paginada de promoções relacionadas ao SKU (results + meta com page e links). results vazio quando não há promoções relacionadas.
  • 400 Bad Request: parâmetro _sort malformado ou com campo fora da allowlist (created_at/updated_at).
  • 404 Not Found: sku_id que não pertence ao seller autenticado no canal informado (ou inexistente/inativo nele); ou, sem canal informado, ausência de seller ativo para o X-Tenant-Id nos canais não-sandbox.
  • 500 Internal Server Error: falha ao consultar a integração de catálogo do canal.
ATENÇÃO

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.

Dica

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.

Preview de adesão

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​

ValorDescrição
open:promotion-skus-seller:readLeitura de SKUs promocionais do seller

Request​

Responses​

Sucesso