Accedi

Benvenuto al nostro Centro Assistenza

Ottieni aiuto con integrazione e campagne live.

Benvenuto al nostro Centro Assistenza. Ottieni aiuto con integrazione e campagne live.

Guida all'API del programma Criteo Reseller V2.0

 

Registro delle modifiche alla guida

Versione

Data di rilascio

Cambia

V1.0 Novembre 2017 Rilascio della prima versione.
V1.1 Marzo 2018 Livello di impression nel report aggiunto alla guida.
V1.2 Settembre 2018 Nuove opzioni di filtraggio aggiunte alla guida.
V2.0 Settembre 2018

Anteprima della guida API V2 perché i nostri clienti possano organizzarsi di conseguenza. Sono inclusi in questa guida i dettagli sulla nuova funzione del budget quotidiano.

 

 

Informazioni su questo documento

Questo documento ti guiderà nell'integrazione del nostra API REST di Criteo. Grazie alla nostra nuova API V2, sarai in grado di eseguire le campagne del programma Criteo Reseller per conto dei tuoi rivenditori. Questa documentazione di aiuterà a comprendere le modifiche che devi attuare per l'API V2. 
 
Qui scoprirai le caratteristiche principali che ti permetteranno – per conto dei tuoi rivenditori - di:
  • Creare e aggiornare budget
  • Creare e aggiornare offerte (CPC)
  • Bloccare i tuoi rivenditori
  • Ottenere statistiche sui tuoi rivenditori

Inizia 

Per utilizzare l'API REST è necessario creare un nuovo utente API nel Management Center. Puoi accedere alla piattaforma mediante l'indirizzo: https://marketing.criteo.com/

Dopo aver effettuato l'accesso:

  • Fai clic su Impostazioni > Utenti

 

 

  • Fai clic su CREA UTENTE API

 

  • Dovrai quindi inserire un indirizzo email di contatto e selezionare uno dei seguenti ruoli: Solo visualizzazione, Business Manager, Financial Manager. Per utilizzare la nostra API, seleziona il ruolo Business Manager. I ruoli Solo visualizzazione e Financial Manager non presentano sufficienti privilegi per inserire e recuperare dati attraverso l'API.
  • Al termine, fai clic su Aggiungi utente. Riceverai un messaggio di conferma, il tuo Client ID e Client Secret. Conservali con cura, poiché ne avrai bisogno per pubblicare richieste sulla nostra API.

valuta

Tutti gli importi specificati nell'API REST di Criteo sono espressi nella tua valuta locale, e comprendono:

  • Numeri riferiti alle performance (ad es. COS, Spesa, …),
  • Budget e offerte

NOTA: puoi controllare la tua valuta locale nell'interfaccia del Management Center. Sotto "Imposta", seleziona "Utenti" e seleziona l'utente desiderato.

Fuso orario

Tutte le date presenti nell'API REST Criteo sono visualizzate nell'Orario Universale Coordinato (UTC).

AGGIORNAMENTO DEI DATI

Le statistiche e il budget rimanente non sono in tempo reale e possono presentare alcune ore di ritardo. Quindi un rivenditore può essere non attivo mentre il suo budget residuo continua a diminuire. Gli annunci del rivenditore non vengono più visualizzati, ma il budget residuo sta diminuendo perché i dati si stanno aggiornando.

Raccomandazioni per l'uso dell'API

Aggiornando budget o offerte in quantità rilevanti, è necessario implementare tali modifiche in chiamate a gruppi separate, relative all'API, e non ricorrere invece a molte singole chiamate, per evitare intasamenti.

Una delle chiamate deve essere contrassegnata come riservata alle offerte, mentre l'altra come riservata ai budget. Entrambe le chiamate conterranno le offerte corrette per le relative campagne e i budget per la data campagna o per più campagne.

ESEMPIO: devi impostare le offerte e i budget per 10 rivenditori diversi. Raccomandiamo di inviare una (1) chiamata API per gli endpoint relativi a rivenditore - campagna e una (1) chiamata per gli endpoint relativi ai budget: entrambe devono contenere le offerte e i budget desiderati dal rispettivo rivenditore.

Elementi tecnici

Tutti i componenti tecnici e gli endpoint sono nuovi per questa documentazione V2. A scopo di comparazione, il nostro swagger V1 è disponibile qui:

https://api.criteo.com/marketing/swagger 

In questo Swagger, troverai gli endpoint indicati qui di seguito:

  • Autenticazione: consente di ottenere un token. Per motivi di sicurezza, il token è valido per una durata di 5 (cinque) minuti.
  • Portafoglio: ti consente di recuperare informazioni di base, quali il tuo ID inserzionista e il Nome inserzionista
  • Rivenditori
    • GET /v2/crp/rivenditori: per ottenere informazioni di base sui rivenditori
    • POST /v2/crp/statistiche: per ottenere statistiche di base sulle campagne
  • Budget
    • GET /v2/crp/budgets: per ottenere lo stato e l'importo residuo i ogni budget
    • POST /v2/crp/budgets: per creare un budget per ogni rivenditore
    • PUT /v2/crp/budgets : aggiorna budget il relativo rivenditore
  • Rivenditori - campagna
    • GET/v2/crp/rivenditore - campagna: per ottenere informazioni del rivenditore sulla sua offerta per la campagna
    • PUT /v2/crp/rivenditore - campagne: per fornire un'offerta (CPC) per la campagna del rivenditore

Notare che sia Rivenditori sia Rivenditori - campagna vengono creati automaticamente in base all'importazione del catalogo, quindi per questi non offriamo chiamate POST.

ESEMPIO: questo swagger connette all'ambiente di produzione Criteo. Qualunque test applicato in tale sede avrà dunque un impatto sulle campagne reali.

Panoramica sull'API

Di seguito, troverai i concetti chiave dell'API REST del programma Criteo Reseller, che ti consente di gestire le offerte e i budget delle campagne al livello dei venditori.

Primi passi

Come posso autenticare l'API?

Criteo utilizza JWT per fornire un sistema di autenticazione basato su token per il nostro API REST. Allo scopo di effettuare chiamate alla nostra API, avrai bisogno di trasmettere un token in relazione a ciascuna di tali chiamate.

Per ottenere il token, dovrai richiamare l'endpoint POST /oauth2/token, con client_id e client_secret quali parametri (vedi la sezione Inizia).

NOTA: ogni token è valido per 5 minuti. Nel caso il token dovesse scadere, riceverai un codice stato risposta 401 HTTP.

Come posso recuperare il mio ID inserzionista?

Recupera l'ID inserzionista richiamando l'endpoint GET /portafoglio/.

Come posso recuperare il mio ID catalogo?

Recupera il tuo CatalogID effettuando una chiamata GET all'endpoint /v2/crp/rivenditori.  

Come posso recuperare il mio ID campagna?

Recupera il tuo CampaignID effettuando una chiamata GET all'endpoint /v2/crp/rivenditore - campagne.

Gestione dei rivenditori

Come posso coinvolgere un rivenditore nel programma Criteo Reseller?

Passo 1: per inserire un nuovo rivenditore, è necessario verificare che sia identificato correttamente nel catalogo Feed del prodotto che hai condiviso in precedenza con Criteo. 

Per verificare che il rivenditore sia identificato correttamente, sarà necessario impostare la colonna relativa al nome del rivenditore con l'identificativo unico del rivenditore, che è il nome del rivenditore per ciascuno dei prodotti del rivenditore forniti nel feed. 

SUGGERIMENTO: un rivenditore diventa attivo dopo che ci avrai inviato i prodotti disponibili attraverso il Feed.

Da quel momento i rivenditori saranno coinvolti per creare rivenditori - campagne per ognuna delle tue campagne CRP.

Passo 2: puoi ottenere l'ID rivenditore e l'ID rivenditore - campagna attraverso GET /v2/crp/rivenditore - campagne

Passo 3: sarai in grado di inviarci il budget e le offerte dei tuoi rivenditori grazie ai loro endpoint, descritti in precedenza, e in particolare:

  • POST /v2/crp/budgets   per inviarci il budget dei rivenditori – A questo punto il budget può essere condiviso con diverse campagne
  • PUT /v2/crp/rivenditore - campagne per fornire il CPC del venditore relativamente a rivenditore - campagna

SUGGERIMENTO: puoi recuperare l'elenco completo dei rivenditori con il relativo stato (attivo/non attivo) richiamando l'endpoint GET del rivenditore, fornendo il tuo identificativo del catalogo (CatalogID) del programma Criteo Reseller quale parametro. 

Come posso rimuovere i dati di un rivenditore dal programma Criteo Reseller?

Se desideri rimuovere un rivenditore dal programma Criteo Reseller, è sufficiente bloccare il budget di questo rivenditore effettuando una chiamata PUT /v2/crp/budgets con stato = BLOCCATO.

In alternativa, puoi anche rimuovere i prodotti del venditore dal feed dei prodotti. Tuttavia, questo avrà effetto solo dopo che Criteo avrà completato l'ingesting di feed e rivenditori. Inoltre, per aggiungerlo nuovamente sarà necessario anche più tempo in quanto richiederà un nuovo ingesting di feed e di rivenditori Noi sconsigliamo questa alternativa.

La rimozione del rivenditore non ne influenzerà le statistiche.

Gestione delle Campagne

Come posso avviare una campagna?

Per avviare una campagna del programma Criteo Reseller, è necessario fornirci un feed prodotto contenente i prodotti di tutti i rivenditori coinvolti nel programma. Ricorda che ciascuno di questi prodotti deve presentare un identificatore unico relativo al rivenditore nel campo rivenditore. La tua campagna verrà automaticamente creata dal momento in cui avviene l'ingesting del feed.

Perché diventi attiva la campagna deve presentare almeno un rivenditore con budget e offerta già impostati. Tuttavia noi non consigliamo di iniziare a un livello così basso di rivenditori. Le campagne di CRP sono progettate per adattarsi a centinaia e migliaia di rivenditori.

SUGGERIMENTO: se lavori già con Criteo, hai le seguenti opzioni:

  • Consigliato: puoi aggiornare il tuo feed attuale aggiungendo informazioni dei rivenditori nel relativo campo (se attualmente non utilizzi 3 categorie).
  • In alternativa, puoi duplicare il feed che ci hai già fornito, assicurandoti che l'identificatore unico dei rivenditori sia disponibile nel relativo campo. 
    • In questo caso, discuti della fatturazione per la tua campagna. Idealmente, è meglio se possiamo integrare questa nuova campagna CRP alla tua attuale fatturazione.

La tua campagna verrà automaticamente creata dal momento in cui avviene l'ingesting del feed. Perché diventi attiva la campagna deve presentare almeno un rivenditore con budget e offerta già impostati. Tuttavia noi non consigliamo di iniziare a un livello così basso di rivenditori. Le campagne di CRP sono progettate per adattarsi a centinaia e migliaia di rivenditori.

Puoi inviarle mediante una chiamata POST /v2/crp/budgets e mettere /v2/crp/rivenditore - campagne.

Come posso bloccare una campagna?

Per interrompere l'intera campagna del programma Criteo Reseller (per tutti i rivenditori) contatta il tuo Account Manager.

Come posso bloccare un rivenditore?

Per bloccare uno o più rivenditori all'interno della tua campagna, è necessario impostare i loro budget come "BLOCCATO".

A quel punto, il sistema smetterà di mostrare annunci per i prodotti di quel rivenditore.

Per impostare un budget come "BLOCCATO", è necessario effettuate una chiamata PUT all'endpoint /rivenditori/budgets come PUT /v2/crp/budgets con stato = BLOCCATO.

NOTA: qualunque budget di rivenditore che presenti uno stato di BLOCCATO non può essere riattivato. Se desideri rilanciare un rivenditore il cui stato è stato impostato su BLOCCATO, sarà necessario creare un nuovo budget (vedi la sezione “Creazione di un nuovo budget").

Bloccando il budget, è possibile che si veda un calo del budget poiché per l'aggiornamento delle statistiche possono essere necessarie alcune ore. Ad esempio, se blocchi il tuo budget a €10.00, i tuoi annunci si bloccheranno, ma potrebbe esserci qualche spesa residua, per cui il budget potrebbe scendere a €9,50.

Che cosa devo fare per un rivenditore il cui budget è quasi esaurito?

Tu non puoi fare nulla. Anticipiamo l'esaurimento del budget di tutti i rivenditori e interrompiamo le relative campagne in qualunque momento si stia esaurendo il budget.

Come posso impostare i budget e i CPC?

Per impostare il budget e i CPC per un rivenditore specifico, è necessario utilizzare i seguenti endpoint:

  • Budget:
    • Per l'inizializzazione: effettua una chiamata POST all'endpoint /v2/crp/budget   
    • Per l'aggiornamento: effettua una chiamata PUT all'endpoint /v2/crp/budget endpoint
  • CPC: per l'inizializzazione e l'aggiornamento: effettua una chiamata PUT all'endpoint /v2/crp/rivenditore - campagna

Come posso aumentare un budget/CPC?

Per aumentare un budget e il CPC per uno specifico rivenditore, è necessario effettuare una chiamata PUT all'endpoint /v2/crp/budget e v2/crp/rivenditore - campagna.

Come posso ridurre un budget/CPC?

Nel caso il rivenditore desideri ridurre il suo CPC, è necessario effettuare una chiamata POST all'endpoint v2/crp/rivenditore - campagna.

Come posso ridurre un budget?

Nel caso il rivenditore desideri ridurre il suo budget, sarà necessario impostare lo stato corrente su BLOCCATO - ciò interromperà le visualizzazioni sul budget corrente il giorno stesso (G) in cui si esegue l'azione. Dopodiché, è possibile creare un nuovo budget con il valore ridotto (vedi la sezione “Come creare un nuovo budget”). Questo inizierà (G+1), ora UTC.

Esempio:

Giorno 0, il rivenditore A ha inizialmente impostato un valore del budget pari a €1000.

Giorno 2, il rivenditore A ha un budget pari a €800, ma decide di ridurre il suo budget disponibile a €500.

Quindi è necessario procedere come segue:

  • Chiamata PUT all'endpoint /v2/crp/budgets
    • Imposta lo stato su BLOCCATO
    • (Non è necessario precisare nessun valore del budget qui, budgetStatus (Stato budget) ha la priorità)
  • Chiamata POST all'endpoint /v2/crp/budgets
    • Imposta importo su 500
    • (Non è necessario precisare nessuno stato qui; se viene lasciato vuoto, si presume che sia Attivo)

NOTA IMPORTANTE Qualunque diminuzione di budget sarà presa immediatamente in considerazione con il seguente impatto:

  • Il rivenditore avrà immediatamente bloccata per il resto della giornata qualsiasi campagna abbia attiva.
  • Il rivenditore verrà riavviato il giorno successivo alle ore 00:00 UTC con il nuovo budget impostato per le campagne che ha in esecuzione.

Come posso creare un nuovo budget?

Puoi creare un nuovo budget se è vero uno dei due casi seguenti:

  • Non hai nessun budget in esecuzione per il giorno corrente per questo rivenditore. I nostri budget non possono sovrapporsi.
  • Hai ESAURITO il budget per questo rivenditore.

Per creare un nuovo budget per un rivenditore, sarà necessario richiamare:

  • Chiamata POST all'endpoint /v2/crp/budgets

Il nuovo budget avrà effetto in uno dei due casi:

  • Oggi, se il budget non è ancora stato stabilito per i rivenditori.
  • Domani, se esiste già un budget.

Uno dei miei rivenditori ha commesso un errore nell'impostazione del budget. Come posso rimediare?

Primo, sarà necessario che il tuo rivenditore ti fornisca il budget aggiornato. Quindi, esistono tre scenari principali che portano ad azioni diverse:

  • Hai già il nuovo budget ed è minore del budget iniziale impostato:
    • Applica le azioni descritte nella sezione "Come posso ridurre un budget/CPC?".
  • Hai già il nuovo budget ed è maggiore del budget iniziale impostato:
    • Applica le azioni descritte nella sezione "Come posso aumentare un budget/CPC?".
  • Non hai il budget nuovo/corretto:
    • Applica le azioni spiegate nella sezione "Come posso rimuovere un rivenditore?".

Uno dei miei rivenditori ha impostato un'offerta errata. Come posso rimediare?

Primo, sarà necessario che il tuo rivenditore ti fornisca il CPC aggiornato. Dovrai inoltre effettuare una chiamata PUT all'endpoint /v2/crp/rivenditore - campagne per impostare l'offerta aggiornata.

E se uno dei miei rivenditori ha modificato il nome sulla mia piattaforma?

Poiché la nostra API si basa essenzialmente su sellerName (Nome venditore) per la gestione di offerte e budget, qualunque cambiamento relativo al nome del rivenditore creerà automaticamente una nuova voce nel nostro sistema, non correlata al precedente nome del rivenditore.<br>In poche parole, se un rivenditore modifica il suo nome sulla tua piattaforma, sarà necessario:

  • Aggiornare il tuo feed del prodotto con il nuovo sellerName (Nome venditore)
  • Inizializza l'offerta del tuo rivenditore e il budget inviandoci una chiamata PUT /v2/crp/rivenditore - campagne e POST /v2/crp/budgets

NOTA: sarai in grado di recuperare le statistiche del precedente sellerName (Nome venditore) dall'endpoint delle statistiche.

Come posso vedere il budget speso dal mio rivenditore?

Per visualizzare il budget speso relativo a un rivenditore dedicato per una campagna del programma Criteo Reseller, effettua una chiamata GET all'endpoint /v2/crp/budgets. Le informazioni saranno disponibili come spentAmount (Budget speso).

Come posso visualizzare il budget residuo relativo ai miei rivenditori?

Per visualizzare il budget speso relativo a un rivenditore dedicato per una campagna del programma Criteo Reseller, effettua una chiamata GET all'endpoint /v2/crp/budgets.

Le informazioni saranno disponibili come remainingAmount (Importo residuo).

Quali sono i diversi stati del mio budget?

  • In esecuzione 
  • Esaurito: hai esaurito il budget e abbiamo dovuto bloccare il rivenditore che visualizzava gli annunci
  • Bloccato: hai manualmente bloccato questo rivenditore
  • Terminato: hai fornito una data di fine per questo budget – La data di fine è trascorsa
  • Programmato: hai fornito una data di inizio nel futuro

Posso pianificare l'avvio posticipato di un budget?

Sì, puoi creare un budget che abbia avvio in futuro, fornendone la data di inizio. Il budget inizierà dalla mezzanotte, ora di Greenwich (GMT).

Posso stabilire una data di fine per il mio budget?

Sì, puoi stabilirla. Finirà alle 23:59 ora di Greenwich (GMT). Lo stato del budget verrà automaticamente impostato come ESAURITO il giorno seguente.

Posso impostare un budget giornaliero?

Non ancora. Puoi, tuttavia, impostare un tipo di budget = GIORNALIERO e fornire un importo in futuro. Prevediamo di attivare questa funzione nel primo trimestre del 2019. L'ETA non è contrattuale e deve essere confermata.

Posso filtrare le mie chiamate relative ai budget del rivenditore?

Sì. Di seguito sono i filtri disponibili:

  • /v2/crp/rivenditori
    • Per i rivenditori endpoint: è possibile filtrare per stato (Disponibile/Non disponibile), ID rivenditore
  • /v2/crp/rivenditore - campagne
    • Per venditore - campagne endpoint: è possibile filtrare per ID campagne e ID rivenditore
  • /v2/crp/budgets
    • Endpoint budget: per stato

Resoconti

Puoi effettuare una chiamata POST all'endpoint /v2/crp/statistiche È possibile unicamente accedere a impression, clic e costo a livello di rivenditore, disponibili fino a un livello di granularità giornaliero.

Oltre alla dimensione ID rivenditore e ID campagna è possibile utilizzare una sola dimensione extra.

Dimensioni:

  • ID inserzionista
  • ID campagna: obbligatoria
  • ID rivenditore: obbligatorio
  • Settimana
  • Giorno

Metriche disponibili:

  • Display
  • Clic
  • Costo inserzionista

Visualizzazione: dal momento che puoi avere diversi rivenditori in un banner, usiamo il rivenditore che ha avuto l'ultimo prodotto visualizzato nel nostro sistema.

Questo articolo ti è stato utile?
Utenti che ritengono sia utile: 0 su 0
Powered by Zendesk