Guida per sviluppatori
Evidenziare nel menu e inviare eventi
Il tuo server invia il contesto del menu e Reach ti dice quale voce evidenziare. Poi manda un VIEW quando viene vista e un CLICK quando viene scelta. Base URL: https://adv.api.waithero.com/api/v1. La chiave va nell’header x-api-key, mai nel browser.
Il campo chiave qui sotto è una simulazione visiva per le prove in pagina. In produzione tutto viene gestito tramite API, dal tuo server.
Serve solo alle prove visive qui sotto. In produzione la chiave non sta nel browser.
Panoramica
Trova cosa evidenziare
Chiedi le campagne adatte a città, ristorante e piatto.
Invia un VIEW
Quando una campagna diventa visibile.
Invia un CLICK
Quando l’utente la tocca.
Categorie di ristoranti
GET /restaurant-categories. Tieni l’id di ogni categoria: ti serve in restaurantCategoryIds.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| search | string | No | Cerca dentro il nome. |
| language | string | No | Codice lingua, per esempio it o en. |
| page | integer | No | Da 1. Predefinito 1. |
| limit | integer | No | Da 1 a 50. Predefinito 20. |
curl "https://adv.api.waithero.com/api/v1/restaurant-categories?search=pizza&language=it"
Prova GET /restaurant-categories
Recupera campagne
POST /client/campaigns/search. Serve solo la posizione: un address, oppure areaLat e areaLon. Senza prodotti ricevi solo campagne HOMEPAGE.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| restaurantCategoryIds | integer[] | No | ID delle categorie, oppure manda i nomi. |
| restaurantCategoryNames | string[] | No | Nomi delle categorie, per esempio Pizza. |
| address | string | No | Indirizzo scritto a mano. |
| areaLat / areaLon | number | No | Coordinate: vanno insieme. |
| products | Product[] | No | productName e categoryName obbligatori nel prodotto. referenceId facoltativo. |
Ogni campagna ti dà id, type (HOMEPAGE, SUGGESTION, HIGHLIGHT), advisor, promotedProduct, homepage e matchedProductReferenceIds.
curl -X POST "https://adv.api.waithero.com/api/v1/client/campaigns/search" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{"address":"Milano","restaurantCategoryNames":["Pizza"],"products":[{"referenceId":"sku-123","productName":"Margherita","categoryName":"Pizza"}]}'Prova POST /client/campaigns/search
Inserisci la tua chiave API in cima alla pagina per provare questa richiesta.
Eventi VIEW e CLICK
POST /events con idAdCampaign e un eventType VIEW o CLICK. Se ne hai mostrate più di una, mandale insieme con POST /events/batch.
| Campo | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| idAdCampaign | integer | Sì | L’id che ti ha dato la ricerca. |
| eventType | VIEW | CLICK | Sì | L’evento che stai registrando. |
| idUser | integer | No | Id dell’utente, se vuoi l’attribuzione. |
La risposta dice quanto è stato addebitato (amount) e quanto resta (remainingBudget). Il batch torna un results[] con ok o error per ogni campagna.
curl -X POST "https://adv.api.waithero.com/api/v1/events" \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{ "idAdCampaign": 42, "eventType": "VIEW" }'Esempio completo
const BASE = "https://adv.api.waithero.com/api/v1";
const headers = { "Content-Type": "application/json", "x-api-key": process.env.CAMPAIGNS_API_KEY };
const categories = await fetch(`${BASE}/restaurant-categories?search=pizza`, { headers }).then((r) => r.json());
const { campaigns } = await fetch(`${BASE}/client/campaigns/search`, {
method: "POST", headers,
body: JSON.stringify({
restaurantCategoryIds: categories.data.map((c) => c.id),
areaLat: 45.4642, areaLon: 9.19,
products: [{ referenceId: "sku-123", productName: "Margherita", categoryName: "Pizza" }]
})
}).then((r) => r.json());
for (const campaign of campaigns) {
await fetch(`${BASE}/events`, { method: "POST", headers, body: JSON.stringify({ idAdCampaign: campaign.id, eventType: "VIEW" }) });
}Errori e budget
Ogni evento scala costPerView o costPerClick dal budget. Quando il budget finisce, la campagna si chiude e sparisce dalle ricerche.
| Stato | Significato |
|---|---|
| 400 | Campagna non attiva, fuori periodo, o evento non valido. |
| 401 | Chiave API mancante o non valida. |
| 402 | Budget finito. |
| 404 | Campagna non trovata. |