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

Grupos de promoções

Lista, cria e remove os grupos de promoções do seller, usados como alvo de orçamentos.

Um grupo de promoções é apenas um nome que reúne promoções para que um orçamento possa limitá-las em conjunto ("Campanha de verão"). A ligação com o orçamento acontece pelo id: um orçamento de escopo group aponta para o grupo em scope_ref (veja Criar, alterar e excluir orçamento). O seller só enxerga e remove os grupos que criou.

Listar grupos

GET/api/v1/vendor/promotion-groupsSeller

Lista os grupos de promoções do seller

Sem parâmetros: devolve todos os grupos do seller.

Exemplo de requisição: listar

bash

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

Resposta: listar

200Grupos do seller

json

{
  "groups": [
    {
      "id": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
      "name": "Campanha de verão",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "created_at": "2026-10-11T14:40:00Z"
    }
  ]
}

Campos da resposta

groupsarray

Grupos do seller.

groups[].iduuid

Identificador do grupo.

groups[].namestring

Nome do grupo.

groups[].vendor_iduuid

Seller dono: sempre o seu.

groups[].created_atstring (RFC 3339)

Criação.

Criar um grupo

POST/api/v1/vendor/promotion-groupsSeller

Cria um grupo de promoções do seller

Corpo da requisição

namestringobrigatório

Nome do grupo.

Exemplo de requisição: criar

bash

curl -X POST "$BASE_URL/api/v1/vendor/promotion-groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Campanha de verão" }'

Resposta: criar

201Grupo criado

json

{
  "id": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
  "name": "Campanha de verão",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T14:40:00Z"
}

Remover um grupo

DELETE/api/v1/vendor/promotion-groups/{id}Seller

Remove um grupo de promoções do seller

Parâmetros de caminho

iduuidobrigatório

Id do grupo.

Resposta: remover

200Grupo removido

json

{ "deleted": true }

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"}`
400	Corpo que não é JSON, ou `name` vazio.	`{"error":"failed to create promotion group","detail":"promotion budget validation: name is required"}`
404	Ao remover: o grupo não existe ou é de outro seller.	`{"error":"promotion group not found"}`
500	Falha inesperada. Um `id` que não é UUID também chega como `500`.	`{"error":"failed to get promotion group","detail":"..."}`

Veja também

Grupos de promoções

Lista, cria e remove os grupos de promoções do seller, usados como alvo de orçamentos.

Listar grupos

GET/api/v1/vendor/promotion-groupsSeller

Lista os grupos de promoções do seller

Sem parâmetros: devolve todos os grupos do seller.

Exemplo de requisição: listar

bash

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

Resposta: listar

200Grupos do seller

json

{
  "groups": [
    {
      "id": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
      "name": "Campanha de verão",
      "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
      "created_at": "2026-10-11T14:40:00Z"
    }
  ]
}

Campos da resposta

groupsarray

Grupos do seller.

groups[].iduuid

Identificador do grupo.

groups[].namestring

Nome do grupo.

groups[].vendor_iduuid

Seller dono: sempre o seu.

groups[].created_atstring (RFC 3339)

Criação.

Criar um grupo

POST/api/v1/vendor/promotion-groupsSeller

Cria um grupo de promoções do seller

Corpo da requisição

namestringobrigatório

Nome do grupo.

Exemplo de requisição: criar

bash

curl -X POST "$BASE_URL/api/v1/vendor/promotion-groups" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Campanha de verão" }'

Resposta: criar

201Grupo criado

json

{
  "id": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
  "name": "Campanha de verão",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "created_at": "2026-10-11T14:40:00Z"
}

Remover um grupo

DELETE/api/v1/vendor/promotion-groups/{id}Seller

Remove um grupo de promoções do seller

Parâmetros de caminho

iduuidobrigatório

Id do grupo.

Resposta: remover

200Grupo removido

json

{ "deleted": true }

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"}`
400	Corpo que não é JSON, ou `name` vazio.	`{"error":"failed to create promotion group","detail":"promotion budget validation: name is required"}`
404	Ao remover: o grupo não existe ou é de outro seller.	`{"error":"promotion group not found"}`
500	Falha inesperada. Um `id` que não é UUID também chega como `500`.	`{"error":"failed to get promotion group","detail":"..."}`