API atual/Referência completa/Venddor Ads

Consultar campanhas

Lista as campanhas do seller ou devolve uma delas, com gasto do dia e acumulado.

Use para a tela de desempenho. Campanhas apagadas não aparecem. As duas rotas devolvem o mesmo formato de campanha.

Listar campanhas

GET/api/v1/vendor/ads/campaignsSeller

Lista as campanhas do seller

Da mais nova para a mais antiga. Não há paginação nem filtros: devolve todas.

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/ads/campaigns" \
  -H "Authorization: Bearer $TOKEN"

200Campanhas

json

{
  "items": [
    {
      "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

itemsarray

Campanhas do seller. Lista vazia se não houver.

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).

Consultar uma campanha

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

Devolve 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.

Exemplo de requisição

bash

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

200Campanha

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

...object

Os mesmos campos de cada item da lista.

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"}`
404	A campanha não existe, é de outro seller ou o id é inválido.	`{"error":"campaign not found","detail":"sql: no rows in result set"}`
500	Falha ao listar.	`{"error":"failed to list campaigns","detail":"..."}`

Veja também

Consultar campanhas

Lista as campanhas do seller ou devolve uma delas, com gasto do dia e acumulado.

Use para a tela de desempenho. Campanhas apagadas não aparecem. As duas rotas devolvem o mesmo formato de campanha.

Listar campanhas

GET/api/v1/vendor/ads/campaignsSeller

Lista as campanhas do seller

Da mais nova para a mais antiga. Não há paginação nem filtros: devolve todas.

Cabeçalhos

Authorizationstringobrigatório

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

Exemplo de requisição

bash

curl -X GET "$BASE_URL/api/v1/vendor/ads/campaigns" \
  -H "Authorization: Bearer $TOKEN"

200Campanhas

json

{
  "items": [
    {
      "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

itemsarray

Campanhas do seller. Lista vazia se não houver.

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).

Consultar uma campanha

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

Devolve 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.

Exemplo de requisição

bash

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

200Campanha

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

...object

Os mesmos campos de cada item da lista.

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"}`
404	A campanha não existe, é de outro seller ou o id é inválido.	`{"error":"campaign not found","detail":"sql: no rows in result set"}`
500	Falha ao listar.	`{"error":"failed to list campaigns","detail":"..."}`