API atual/Referência completa/Promoções do seller

Consultar promoções

Lista as promoções do seller e detalha uma delas.

Use estas duas rotas para ver o que o seller já cadastrou: a lista traz todas as promoções dele (da mais nova para a mais antiga) e o detalhe devolve uma só. Promoções da loja ou de outros sellers nunca aparecem: uma consulta por id de outro seller responde 404 como se não existisse.

Listar promoções

GET/api/v1/vendor/promotionsSeller

Lista as promoções do seller

A lista não tem paginação nem filtros: devolve todas as promoções não excluídas do seller, da criação mais recente para a mais antiga.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/vendor/promotions" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Promoções do seller

json

{
  "promotions": [
    {
      "id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Inverno 10% nas camisas",
      "description": "",
      "type": "percentage",
      "code": "INVERNO10",
      "discount": 1000,
      "conditions": { "min_cart_total": 20000 },
      "usage_limit": 500,
      "usage_count": 12,
      "valid_from": "2026-11-27T03:00:00Z",
      "valid_until": "2026-11-30T02:59:59Z",
      "status": "A",
      "priority": 0,
      "stop_other_rules": false,
      "stackable": false,
      "zone": "cart",
      "bonuses": [],
      "per_user_limit": 1,
      "created_at": "2026-10-11T14:02:10.482113Z",
      "updated_at": "2026-10-11T14:02:10.482113Z"
    }
  ],
  "total": 1
}

Campos da resposta

promotionsarray

Promoções do seller. Lista vazia ([]) quando não há nenhuma.

totalinteger

Quantidade de itens em promotions.

Detalhar uma promoção

GET/api/v1/vendor/promotions/{id}Seller

Detalha uma promoção do seller

Parâmetros de caminho

iduuidobrigatório

Id da promoção, UUID completo.

Resposta: detalhar

200Promoção encontrada

json

{
  "id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Inverno 10% nas camisas",
  "type": "percentage",
  "code": "INVERNO10",
  "discount": 1000,
  "conditions": { "min_cart_total": 20000 },
  "usage_limit": 500,
  "usage_count": 12,
  "valid_from": "2026-11-27T03:00:00Z",
  "valid_until": "2026-11-30T02:59:59Z",
  "status": "A",
  "priority": 0,
  "stop_other_rules": false,
  "stackable": false,
  "zone": "cart",
  "per_user_limit": 1,
  "created_at": "2026-10-11T14:02:10.482113Z",
  "updated_at": "2026-10-11T14:02:10.482113Z"
}

Campos da resposta

iduuid

Identificador da promoção.

vendor_iduuid

Seller dono da promoção. Sempre o seu.

namestring

Nome interno.

descriptionstring

Descrição livre. Pode ser vazia.

typestring

Tipo: percentage, fixed, free_shipping, buy_x_get_y e os demais aceitos na criação.

codestring | null

Código do cupom, sempre em maiúsculas. Sem código a promoção do seller não é aplicada.

discountinteger

Pontos-base em percentage (1000 = 10%); centavos em fixed.

max_discountinteger | omitted

Teto do desconto em centavos. Ausente quando não há teto.

conditionsobject

Condições simples (por exemplo min_cart_total em centavos, medido sobre os itens do seller). {} quando não há.

condition_groupsobject | null

Condições aninhadas E/OU.

usage_limitinteger

Máximo de usos no total. 0 = sem limite.

per_user_limitinteger | omitted

Máximo de usos por cliente.

usage_countinteger

Quantas vezes já foi usada em pedidos.

valid_fromstring (RFC 3339)

Início da vigência, em UTC.

valid_untilstring (RFC 3339) | null

Fim da vigência, em UTC. null = sem fim.

statusstring

Letra: A ativa, D inativa ou excluída, E expirada.

priorityinteger

Ordem de avaliação; menor primeiro.

stop_other_rulesboolean

Quando true, as promoções seguintes deixam de ser avaliadas.

stackableboolean

Quando true, pode se combinar com outras acumuláveis.

zonestring

cart (carrinho) ou catalog (preço na vitrine).

bonus_typestring | null

Tipo de bônus único (formato antigo).

bonus_configobject | null

Configuração do bônus único (formato antigo).

bonusesarray

Lista de bônus; cada item tem bonus_type e config.

free_shipping_method_iduuid | null

Forma de envio que ganha frete grátis, no tipo free_shipping.

created_atstring (RFC 3339)

Criação.

updated_atstring (RFC 3339)

Última alteração.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller.	`{"error":"insufficient permissions"}`
403	O usuário seller não tem privilégio de configurações.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings", "..."]}`
403	O usuário não está ligado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
404	No detalhe: a promoção não existe ou é de outro seller.	`{"error":"promotion not found"}`
500	Falha ao ler. Um `id` que não é UUID também cai aqui, não em `400`.	`{"error":"failed to get promotion","detail":"..."}`

Veja também

Consultar promoções

Lista as promoções do seller e detalha uma delas.

Listar promoções

GET/api/v1/vendor/promotionsSeller

Lista as promoções do seller

A lista não tem paginação nem filtros: devolve todas as promoções não excluídas do seller, da criação mais recente para a mais antiga.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/vendor/promotions" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Promoções do seller

json

{
  "promotions": [
    {
      "id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "name": "Inverno 10% nas camisas",
      "description": "",
      "type": "percentage",
      "code": "INVERNO10",
      "discount": 1000,
      "conditions": { "min_cart_total": 20000 },
      "usage_limit": 500,
      "usage_count": 12,
      "valid_from": "2026-11-27T03:00:00Z",
      "valid_until": "2026-11-30T02:59:59Z",
      "status": "A",
      "priority": 0,
      "stop_other_rules": false,
      "stackable": false,
      "zone": "cart",
      "bonuses": [],
      "per_user_limit": 1,
      "created_at": "2026-10-11T14:02:10.482113Z",
      "updated_at": "2026-10-11T14:02:10.482113Z"
    }
  ],
  "total": 1
}

Campos da resposta

promotionsarray

Promoções do seller. Lista vazia ([]) quando não há nenhuma.

totalinteger

Quantidade de itens em promotions.

Detalhar uma promoção

GET/api/v1/vendor/promotions/{id}Seller

Detalha uma promoção do seller

Parâmetros de caminho

iduuidobrigatório

Id da promoção, UUID completo.

Resposta: detalhar

200Promoção encontrada

json

{
  "id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Inverno 10% nas camisas",
  "type": "percentage",
  "code": "INVERNO10",
  "discount": 1000,
  "conditions": { "min_cart_total": 20000 },
  "usage_limit": 500,
  "usage_count": 12,
  "valid_from": "2026-11-27T03:00:00Z",
  "valid_until": "2026-11-30T02:59:59Z",
  "status": "A",
  "priority": 0,
  "stop_other_rules": false,
  "stackable": false,
  "zone": "cart",
  "per_user_limit": 1,
  "created_at": "2026-10-11T14:02:10.482113Z",
  "updated_at": "2026-10-11T14:02:10.482113Z"
}

Campos da resposta

iduuid

Identificador da promoção.

vendor_iduuid

Seller dono da promoção. Sempre o seu.

namestring

Nome interno.

descriptionstring

Descrição livre. Pode ser vazia.

typestring

Tipo: percentage, fixed, free_shipping, buy_x_get_y e os demais aceitos na criação.

codestring | null

Código do cupom, sempre em maiúsculas. Sem código a promoção do seller não é aplicada.

discountinteger

Pontos-base em percentage (1000 = 10%); centavos em fixed.

max_discountinteger | omitted

Teto do desconto em centavos. Ausente quando não há teto.

conditionsobject

Condições simples (por exemplo min_cart_total em centavos, medido sobre os itens do seller). {} quando não há.

condition_groupsobject | null

Condições aninhadas E/OU.

usage_limitinteger

Máximo de usos no total. 0 = sem limite.

per_user_limitinteger | omitted

Máximo de usos por cliente.

usage_countinteger

Quantas vezes já foi usada em pedidos.

valid_fromstring (RFC 3339)

Início da vigência, em UTC.

valid_untilstring (RFC 3339) | null

Fim da vigência, em UTC. null = sem fim.

statusstring

Letra: A ativa, D inativa ou excluída, E expirada.

priorityinteger

Ordem de avaliação; menor primeiro.

stop_other_rulesboolean

Quando true, as promoções seguintes deixam de ser avaliadas.

stackableboolean

Quando true, pode se combinar com outras acumuláveis.

zonestring

cart (carrinho) ou catalog (preço na vitrine).

bonus_typestring | null

Tipo de bônus único (formato antigo).

bonus_configobject | null

Configuração do bônus único (formato antigo).

bonusesarray

Lista de bônus; cada item tem bonus_type e config.

free_shipping_method_iduuid | null

Forma de envio que ganha frete grátis, no tipo free_shipping.

created_atstring (RFC 3339)

Criação.

updated_atstring (RFC 3339)

Última alteração.

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller.	`{"error":"insufficient permissions"}`
403	O usuário seller não tem privilégio de configurações.	`{"error":"insufficient vendor privileges","privilege_required_any":["vendor_settings", "..."]}`
403	O usuário não está ligado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
404	No detalhe: a promoção não existe ou é de outro seller.	`{"error":"promotion not found"}`
500	Falha ao ler. Um `id` que não é UUID também cai aqui, não em `400`.	`{"error":"failed to get promotion","detail":"..."}`