API atual/Referência completa/Venddor Ads

Criar e alterar campanhas

Cria uma campanha em rascunho, altera lance, orçamento e produtos, ou a apaga.

A campanha nasce em draft e não veicula até ser ativada em Mudar status. Apagar é lógico: a campanha vira ended e some das listas, mas o gasto passado continua nos movimentos da carteira.

Criar campanha

POST/api/v1/vendor/ads/campaignsSeller

Cria uma campanha

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Corpo da requisição

namestringobrigatório

Nome interno. Obrigatório, sem ser só espaços.

bid_centsintegerobrigatório

Lance máximo por clique em centavos. Maior que 0.

daily_budget_centsintegerobrigatório

Orçamento diário em centavos. Maior que 0.

total_budget_centsinteger

Orçamento total em centavos. Omita (ou null) para não ter limite total.

product_idsarray

Ids (UUID) dos produtos a anunciar. Ids que não sejam de produtos (não apagados) do seu seller são descartados sem erro.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/ads/campaigns" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Chinelos de verão",
  "bid_cents": 80,
  "daily_budget_cents": 5000,
  "total_budget_cents": 50000,
  "product_ids": [
    "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44"
  ]
}'

201Campanha criada

json

{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Chinelos de verão",
  "status": "draft",
  "bid_cents": 80,
  "daily_budget_cents": 5000,
  "total_budget_cents": 50000,
  "spent_today_cents": 0,
  "spent_total_cents": 0,
  "product_ids": [
    "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44"
  ],
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

iduuid

Id da campanha.

vendor_iduuid

Seller dono da campanha.

namestring

Nome interno.

statusstring

draftactivepausedended

draft, active, paused ou ended.

bid_centsinteger

Lance máximo por clique, em centavos.

daily_budget_centsinteger

Orçamento diário em centavos.

total_budget_centsinteger

Orçamento total em centavos. Ausente = sem limite total.

starts_atstring

Início da veiculação. Ausente: a API de seller não permite definir esta data.

ends_atstring

Fim da veiculação. Ausente: a API de seller não permite definir esta data.

spent_today_centsinteger

Gasto no dia atual (fuso de São Paulo), em centavos. Zera na virada do dia.

spent_total_centsinteger

Gasto acumulado em centavos.

product_idsarray

Ids dos produtos anunciados. Só entram produtos do próprio seller.

created_atstring

Criação (RFC 3339, UTC).

updated_atstring

Última alteração (RFC 3339, UTC).

Alterar campanha

PUT/api/v1/vendor/ads/campaigns/{id}Seller

Altera uma campanha

Atenção às regras de cada campo: name, bid_cents e daily_budget_cents só mudam se vierem preenchidos (vazio ou 0 mantém o valor atual); product_ids só muda se o campo vier no corpo (a lista enviada substitui a atual, [] esvazia); total_budget_cents é sempre regravado.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da campanha.

Corpo da requisição

namestring

Novo nome. Vazio mantém.

bid_centsinteger

Novo lance em centavos. 0 ou ausente mantém.

daily_budget_centsinteger

Novo orçamento diário. 0 ou ausente mantém.

total_budget_centsinteger

Novo orçamento total. Ausente ou null remove o limite total.

product_idsarray

Lista completa de produtos. Ausente mantém a atual.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/ads/campaigns/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "bid_cents": 90,
  "total_budget_cents": 50000
}'

200Campanha atualizada

json

{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Chinelos de verão",
  "status": "draft",
  "bid_cents": 90,
  "daily_budget_cents": 5000,
  "total_budget_cents": 50000,
  "spent_today_cents": 0,
  "spent_total_cents": 0,
  "product_ids": [
    "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44"
  ],
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Apagar campanha

DELETE/api/v1/vendor/ads/campaigns/{id}Seller

Apaga (encerra) uma campanha

Marca como apagada e muda o status para ended. A resposta é 200 mesmo se o id não existir ou for de outro seller: nada é alterado nesse caso.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da campanha.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/ads/campaigns/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN"

200Campanha apagada

json

{
  "deleted": true
}

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O usuário autenticado não está vinculado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	Criação: `name` vazio, ou `bid_cents`/`daily_budget_cents` menores ou iguais a 0.	`{"error":"failed to create campaign","detail":"bid_cents and daily_budget_cents must be positive (in centavos)"}`
400	Alteração: campanha inexistente ou de outro seller.	`{"error":"failed to update campaign","detail":"campaign not found"}`
500	Falha ao apagar.	`{"error":"failed to delete campaign","detail":"..."}`

Veja também

API atual/Referência completa/Venddor Ads

Criar e alterar campanhas

Cria uma campanha em rascunho, altera lance, orçamento e produtos, ou a apaga.

A campanha nasce em draft e não veicula até ser ativada em Mudar status. Apagar é lógico: a campanha vira ended e some das listas, mas o gasto passado continua nos movimentos da carteira.

Criar campanha

POST/api/v1/vendor/ads/campaignsSeller

Cria uma campanha

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Corpo da requisição

namestringobrigatório

Nome interno. Obrigatório, sem ser só espaços.

bid_centsintegerobrigatório

Lance máximo por clique em centavos. Maior que 0.

daily_budget_centsintegerobrigatório

Orçamento diário em centavos. Maior que 0.

total_budget_centsinteger

Orçamento total em centavos. Omita (ou null) para não ter limite total.

product_idsarray

Ids (UUID) dos produtos a anunciar. Ids que não sejam de produtos (não apagados) do seu seller são descartados sem erro.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/ads/campaigns" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Chinelos de verão",
  "bid_cents": 80,
  "daily_budget_cents": 5000,
  "total_budget_cents": 50000,
  "product_ids": [
    "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44"
  ]
}'

201Campanha criada

json

{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Chinelos de verão",
  "status": "draft",
  "bid_cents": 80,
  "daily_budget_cents": 5000,
  "total_budget_cents": 50000,
  "spent_today_cents": 0,
  "spent_total_cents": 0,
  "product_ids": [
    "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44"
  ],
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

iduuid

Id da campanha.

vendor_iduuid

Seller dono da campanha.

namestring

Nome interno.

statusstring

draftactivepausedended

draft, active, paused ou ended.

bid_centsinteger

Lance máximo por clique, em centavos.

daily_budget_centsinteger

Orçamento diário em centavos.

total_budget_centsinteger

Orçamento total em centavos. Ausente = sem limite total.

starts_atstring

Início da veiculação. Ausente: a API de seller não permite definir esta data.

ends_atstring

Fim da veiculação. Ausente: a API de seller não permite definir esta data.

spent_today_centsinteger

Gasto no dia atual (fuso de São Paulo), em centavos. Zera na virada do dia.

spent_total_centsinteger

Gasto acumulado em centavos.

product_idsarray

Ids dos produtos anunciados. Só entram produtos do próprio seller.

created_atstring

Criação (RFC 3339, UTC).

updated_atstring

Última alteração (RFC 3339, UTC).

Alterar campanha

PUT/api/v1/vendor/ads/campaigns/{id}Seller

Altera uma campanha

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da campanha.

Corpo da requisição

namestring

Novo nome. Vazio mantém.

bid_centsinteger

Novo lance em centavos. 0 ou ausente mantém.

daily_budget_centsinteger

Novo orçamento diário. 0 ou ausente mantém.

total_budget_centsinteger

Novo orçamento total. Ausente ou null remove o limite total.

product_idsarray

Lista completa de produtos. Ausente mantém a atual.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/vendor/ads/campaigns/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "bid_cents": 90,
  "total_budget_cents": 50000
}'

200Campanha atualizada

json

{
  "id": "7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "name": "Chinelos de verão",
  "status": "draft",
  "bid_cents": 90,
  "daily_budget_cents": 5000,
  "total_budget_cents": 50000,
  "spent_today_cents": 0,
  "spent_total_cents": 0,
  "product_ids": [
    "1c5e8a30-92b4-4d6f-8e21-5a7b9c0d3e44"
  ],
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Apagar campanha

DELETE/api/v1/vendor/ads/campaigns/{id}Seller

Apaga (encerra) uma campanha

Marca como apagada e muda o status para ended. A resposta é 200 mesmo se o id não existir ou for de outro seller: nada é alterado nesse caso.

Cabeçalhos

Authorizationstringobrigatório

Bearer $TOKEN. Token de acesso do usuário seller. Veja Tokens.

Parâmetros de caminho

iduuidobrigatório

Id da campanha.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/ads/campaigns/7f0c2b1e-5a43-4d8e-9a67-3c1d2e4f5a60" \
  -H "Authorization: Bearer $TOKEN"

200Campanha apagada

json

{
  "deleted": true
}

Erros

Status	Quando	Corpo de exemplo
401	Token ausente, inválido ou expirado.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller (por exemplo, é de administrador).	`{"error":"insufficient permissions"}`
403	O usuário autenticado não está vinculado a nenhum seller.	`{"error":"no vendor account associated with this user"}`
400	JSON inválido.	`{"error":"invalid request body","detail":"..."}`
400	Criação: `name` vazio, ou `bid_cents`/`daily_budget_cents` menores ou iguais a 0.	`{"error":"failed to create campaign","detail":"bid_cents and daily_budget_cents must be positive (in centavos)"}`
400	Alteração: campanha inexistente ou de outro seller.	`{"error":"failed to update campaign","detail":"campaign not found"}`
500	Falha ao apagar.	`{"error":"failed to delete campaign","detail":"..."}`