Criteo REST API para Resellers

Índice

A seguir, apresentamos os principais conceitos da REST API do Criteo Reseller Program para você gerenciar bids e budgets de campanhas no nível do cliente.

AUTENTICAÇÃO DA API

Usamos JWT para fornecer um sistema de autenticação baseado em tokens à nossa REST API. Para emitir chamadas à nossa API, você deve passar um token para cada uma dessas chamadas.

Para obter seu token, você deverá emitir uma chamada POST para o endpoint /oauth2/token, com client_id e client_secret como parâmetros (veja a seção "Como começar").

COMO RECUPERAR SEU AdvertiserID

Recupere seu AdvertiserID emitindo uma chamada GET para o endpoint /portfolio/.

COMO RECUPERAR SEU CampaignID

Recupere seu CampaignID emitindo uma chamada GET para o endpoint /sellers/.

COMO INTEGRAR UM CLIENTE AO CRITEO RESELLER PROGRAM

Para integrar um novo cliente, verifique se ele está corretamente sinalizado no catálogo de Feed de Produtos que você compartilhou com a Criteo.
Para ter certeza de que seu cliente está corretamente sinalizado, você precisará definir a coluna nome do cliente com o identificador exclusivo do cliente, que é o nome do cliente para cada produto do cliente fornecido no feed.

Após as etapas acima, você poderá nos enviar o budget e os bids dos seus clientes graças aos endpoints dos clientes anteriormente descritos, especialmente:

PUT /v1/sellers/bids para nos enviar o CPC dos clientes
POST /v1/sellers/budgets para nos enviar o budget do cliente

COMO REMOVER DADOS DE UM CLIENTE DO CRITEO RESELLER PROGRAM

Para remover um cliente do Criteo Reseller Program, basta parar esse cliente na campanha (veja a seção “Como parar um cliente”).

Ou você pode remover os produtos do cliente do seu feed de produtos. No entanto, isso só será possível depois que a Criteo concluir a ingestão de feed e categoria. Além disso, adicioná-lo de volta também demandará mais tempo, pois será necessária uma nova ingestão de feed e categoria. Por fim, depois que o cliente for removido do feed, as estatísticas para esse cliente não estarão mais disponíveis.

COMO COMEÇAR UMA CAMPANHA

Para começar uma campanha do Criteo Reseller Program, você deve nos fornecer um feed de produtos dedicado, que contenha produtos de todos os clientes integrados ao programa. Observe que cada um desses produtos deve ter o identificador exclusivo do cliente no campo do cliente.

Sua campanha será automaticamente criada assim que seu feed for ingerido.
Para ir ao ar, sua campanha precisa de, pelo menos, um cliente com budget e bid já definidos. É possível enviá-los através dos endpoints PUT /v1/sellers/bids e POST /v1/sellers /budgets.

COMO PARAR UMA CAMPANHA ATIVA

Para parar a campanha do Criteo Reseller Program (para todos os clientes), fale com seu Gerente de Contas.

COMO PAUSAR UM CLIENTE ESPECÍFICO

Para parar um ou mais clientes na sua campanha, você deve definir o budget de cada um como "Inativo". Depois que você fizer isso, o sistema não mostrará mais anúncios dos produtos desses clientes.

Para definir um budget como "Inativo", você deve emitir uma chamada PUT para o endpoint /sellers/budgets, conforme descrito abaixo:

PUT /sellers/budgets com o status = Inativo

COMO PARAR UM CLIENTE CUJO BUDGET JÁ FOI QUASE COMPLETAMENTE CONSUMIDO

Da sua parte, você não pode fazer nada. Antecipamos o esgotamento do budget de todos os clientes e interrompemos suas campanhas quando o budget estiver insuficiente.

COMO DEFINIR BUDGETS E CPCs

Para definir um budget e um CPC para determinado cliente, você precisa usar os seguintes endpoints:

Bids: para inicialização e atualização: emita uma chamada PUT para o endpoint /sellers/bids
Budgets:
- Para inicialização: emita uma chamada POST para o endpoint /v1/sellers/budgets
- Para a atualização de budgets: emita uma chamada PUT para o endpoint /v1/sellers/budgets

COMO AUMENTAR BUDGETS E CPCs

Para aumentar um budget e o CPC de determinado cliente, você deve emitir uma chamada PUT para os endpoints /v1/sellers/budgets e /v1/sellers/bids.

COMO REDUZIR CPCs

Caso seu cliente deseje reduzir o CPC dele, você deverá emitir uma chamada POST para o endpoint /v1/sellers/bids.

COMO REDUZIR BUDGETS

Se seu cliente quiser reduzir o budget dele, você deverá definir o status atual como Inativo — isso interromperá a campanha com o budget atual no dia (D) em que você realizar a ação. Em seguida, você poderá criar um novo budget com o valor reduzido (veja a seção “Como criar um novo budget”). Essa ação será iniciada(D+1), horário UTC

EXEMPLO:

Dia 0: o cliente A definiu, inicialmente, um budget de US$ 1.000,00 para a campanha do Criteo Reseller Program.

Dia 2: o cliente A ainda tem US$ 800 de budget, MAS decide reduzir o budget disponível para US$ 500.

Você deverá então emitir as seguintes chamadas:

Chamada PUT para o endpoint /sellers/budgets/
- Defina o status como Inativo
- (Não é necessário definir nenhum valor de budget aqui. O status tem prioridade)
Chamada POST para o endpoint /sellers/budgets
- Defina o valor como 500
- (Não é necessário fornecer o status aqui; se for deixado vazio, entenderemos como Ativo)

COMO CRIAR BUDGETS

Você pode criar um novo budget em um dos dois casos:

Você não tem um budget para o dia atual
Você tem um budget inativo para o dia atual

Para criar um novo Budget para o cliente, você precisará emitir

Chamada POST para o endpoint /sellers/budgets

O novo Budget terá efeito:

Imediatamente, caso você não tenha nenhum budget para o dia atual
Amanhã, caso você tenha um budget inativo para o dia atual

COMO CORRIGIR BUDGETS INSERIDOS INCORRETAMENTE

Primeiro, será necessário que seu cliente forneça a você o budget atualizado.
Em seguida, há três cenários principais que levam a diferentes ações:

Você já tem o novo budget e ele é inferior ao budget inicial definido:
- Aplique as ações descritas na seção Como faço para reduzir um budget/CPC?
Você já tem o novo budget e ele é superior ao budget inicial definido:
- Aplique as ações descritas na seção "Como aumentar um budget/CPC"
Você não tem o budget novo/correto:
- Aplique as ações explicadas na seção "Como posso remover um cliente"

COMO CORRIGIR CPCs INSERIDOS INCORRETAMENTE

Primeiro, será necessário que seu cliente forneça a você o CPC atualizado. Em seguida, você deverá emitir uma chamada PUT para o endpoint sellers/bids/ para definir o bid atualizado.

E SE MEU CLIENTE TIVER MUDADO O NOME DELE NA MINHA PLATAFORMA?

Como nossa API depende do sellerName para gerenciar bids e budgets, qualquer mudança no nome do cliente criará automaticamente uma nova entrada no nosso sistema, não vinculada ao nome anterior do cliente.
Resumindo, se o cliente mudar o nome dele na sua plataforma, você precisará:

Atualizar seu feed de produtos com o novo sellerName.
Inicializar o bid e o budget do seu cliente enviando para nós uma instrução PUT /v1/sellers/bids e POST /v1/sellers/budgets.

COMO ANALISAR O BUDGET CONSUMIDO DE CLIENTES

Para ver o budget consumido de determinado cliente em uma campanha do Criteo Reseller Program, emita uma chamada GET para o endpoint /v1/sellers. As informações estarão disponíveis como spentAmount.

COMO ANALISAR O BUDGET RESTANTE DE CLIENTES

Para ver o budget consumido determinado cliente em uma campanha do Criteo Reseller Program, emita uma chamada GET para o endpoint /v1/sellers. As informações estarão disponíveis como remainingAmount.

Relatórios

Você pode emitir uma chamada POST para o endpoint /v1/sellers/stats. Só é possível acessar impressões, cliques e custos no nível do cliente. Esses dados estão disponíveis com granularidade diária.

No máximo, 3 dimensões podem ser usadas e devem conter a dimensão do cliente.

Dimensões disponíveis:

AdvertiserID
campaignID
Cliente – Obrigatório
Ano
Semana
Dia

Métricas disponíveis:

Displays
cliques
AdvertiserCost