API atual/Referência completa/Orçamentos e grupos de promoções

Consultar grupos

Lista os grupos de promoções, detalha um grupo e conta quantos orçamentos o usam.

O grupo é apenas um nome. A ligação com as promoções e com os orçamentos acontece pelos ids: um orçamento de escopo group aponta para o grupo em scope_ref. Use /usage antes de excluir ou renomear um grupo para saber quantos orçamentos dependem dele.

Listar grupos

GET/api/v1/admin/promotion-groupsAdmin

Lista os grupos de promoções

Parâmetros de consulta

vendor_iduuid

Só grupos deste seller. Presente e vazio devolve só os da loja.

Exemplo de requisição: listar

bash

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

Resposta: listar

200Grupos

json

{
  "groups": [
    {
      "id": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
      "name": "Campanha de verão",
      "created_at": "2026-07-20T00:54:48.258916Z"
    }
  ]
}

Campos da resposta

groupsarray

Grupos, do mais novo para o mais antigo.

iduuid

Identificador do grupo.

namestring

Nome do grupo.

vendor_iduuid | omitted

Seller dono do grupo. Ausente = grupo da loja.

created_atstring (RFC 3339)

Criação.

Erros: listar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	Falta o privilégio: `view_promotions` para ler, `manage_promotions` para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`
500	Falha ao consultar o banco.	`{"error":"failed to list promotion groups","detail":"..."}`

Detalhar um grupo

GET/api/v1/admin/promotion-groups/{id}Admin

Detalha um grupo

Parâmetros de caminho

iduuidobrigatório

Id do grupo.

Exemplo de requisição: detalhar

bash

curl "$BASE_URL/api/v1/admin/promotion-groups/7af8cfda-fbbc-4a75-b266-fb90ad2d11fb" \
  -H "Authorization: Bearer $TOKEN"

Resposta: detalhar

200Grupo

json

{
  "id": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
  "name": "Campanha de verão",
  "created_at": "2026-07-20T00:54:48.258916Z"
}

Campos da resposta

iduuid

Identificador do grupo.

namestring

Nome do grupo.

vendor_iduuid | omitted

Seller dono do grupo. Ausente = grupo da loja.

created_atstring (RFC 3339)

Criação.

Erros: detalhar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	Falta o privilégio: `view_promotions` para ler, `manage_promotions` para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`
404	Não existe grupo com esse id.	`{"error":"failed to get promotion group","detail":"promotion budget not found"}`
500	O id não é um UUID válido.	`{"error":"failed to get promotion group","detail":"..."}`

Uso de um grupo

GET/api/v1/admin/promotion-groups/{id}/usageAdmin

Conta os orçamentos que apontam para o grupo

Parâmetros de caminho

iduuidobrigatório

Id do grupo.

Exemplo de requisição: uso

bash

curl "$BASE_URL/api/v1/admin/promotion-groups/7af8cfda-fbbc-4a75-b266-fb90ad2d11fb/usage" \
  -H "Authorization: Bearer $TOKEN"

Resposta: uso

200Contagem

json

{
  "budget_count": 1
}

Campos da resposta

budget_countinteger

Quantos orçamentos têm scope group e este id em scope_ref.

Erros: uso

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	Falta o privilégio: `view_promotions` para ler, `manage_promotions` para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`
500	O id não é um UUID válido, ou falha de banco.	`{"error":"failed to count group usage","detail":"..."}`

Veja também

API atual/Referência completa/Orçamentos e grupos de promoções

Consultar grupos

Lista os grupos de promoções, detalha um grupo e conta quantos orçamentos o usam.

Listar grupos

GET/api/v1/admin/promotion-groupsAdmin

Lista os grupos de promoções

Parâmetros de consulta

vendor_iduuid

Só grupos deste seller. Presente e vazio devolve só os da loja.

Exemplo de requisição: listar

bash

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

Resposta: listar

200Grupos

json

{
  "groups": [
    {
      "id": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
      "name": "Campanha de verão",
      "created_at": "2026-07-20T00:54:48.258916Z"
    }
  ]
}

Campos da resposta

groupsarray

Grupos, do mais novo para o mais antigo.

iduuid

Identificador do grupo.

namestring

Nome do grupo.

vendor_iduuid | omitted

Seller dono do grupo. Ausente = grupo da loja.

created_atstring (RFC 3339)

Criação.

Erros: listar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	Falta o privilégio: `view_promotions` para ler, `manage_promotions` para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`
500	Falha ao consultar o banco.	`{"error":"failed to list promotion groups","detail":"..."}`

Detalhar um grupo

GET/api/v1/admin/promotion-groups/{id}Admin

Detalha um grupo

Parâmetros de caminho

iduuidobrigatório

Id do grupo.

Exemplo de requisição: detalhar

bash

curl "$BASE_URL/api/v1/admin/promotion-groups/7af8cfda-fbbc-4a75-b266-fb90ad2d11fb" \
  -H "Authorization: Bearer $TOKEN"

Resposta: detalhar

200Grupo

json

{
  "id": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
  "name": "Campanha de verão",
  "created_at": "2026-07-20T00:54:48.258916Z"
}

Campos da resposta

iduuid

Identificador do grupo.

namestring

Nome do grupo.

vendor_iduuid | omitted

Seller dono do grupo. Ausente = grupo da loja.

created_atstring (RFC 3339)

Criação.

Erros: detalhar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	Falta o privilégio: `view_promotions` para ler, `manage_promotions` para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`
404	Não existe grupo com esse id.	`{"error":"failed to get promotion group","detail":"promotion budget not found"}`
500	O id não é um UUID válido.	`{"error":"failed to get promotion group","detail":"..."}`

Uso de um grupo

GET/api/v1/admin/promotion-groups/{id}/usageAdmin

Conta os orçamentos que apontam para o grupo

Parâmetros de caminho

iduuidobrigatório

Id do grupo.

Exemplo de requisição: uso

bash

curl "$BASE_URL/api/v1/admin/promotion-groups/7af8cfda-fbbc-4a75-b266-fb90ad2d11fb/usage" \
  -H "Authorization: Bearer $TOKEN"

Resposta: uso

200Contagem

json

{
  "budget_count": 1
}

Campos da resposta

budget_countinteger

Quantos orçamentos têm scope group e este id em scope_ref.

Erros: uso

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	Falta o privilégio: `view_promotions` para ler, `manage_promotions` para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`
500	O id não é um UUID válido, ou falha de banco.	`{"error":"failed to count group usage","detail":"..."}`