Alertes

Une alerte vous signale que les assistants IA se trompent sur la marque, ou que quelque chose a bougé : une hallucination de prix (un modèle cite un prix qui n’est pas celui du catalogue), une disponibilité erronée (un modèle dit en stock / en rupture à l’inverse de la boutique), une chute de visibilité (la part a baissé entre deux samplings hebdo) un nouveau concurrent cité sur plusieurs requêtes, une spec inventée (un modèle prête au produit une caractéristique que sa fiche d’identité ne donne pas — claimed.specs les liste), ou, pour un établissement physique, des informations d’établissement erronées (wrong_local_fact : un modèle donne une adresse ou un téléphone qui n’est pas celui déclaré sur le marché — claimed.address / claimed.phone, claimed.wrong dit lesquels), ou une régression SEO (seo_regression : entre deux crawls SEO du marché, une page clé est passée en erreur, a reçu un noindex, perdu son schema Product, sa balise title, sa meta description ou sa canonical, ou robots.txt bloque un bot de recherche — claimed.signal, claimed.pages[{url, before, after}], claimed.count, claimed.bots ; une alerte par signal et par marché, sans modèle ni requête, résolue d’elle-même par le crawl qui retrouve les pages saines). Les deux premières, wrong_local_fact et les régressions SEO bloquantes (erreur, noindex, schema, robots) sont critical : un acheteur peut acheter — ou non — sur une fausse promesse.

Skoup ouvre une alerte par incident : si le même prix faux revient la semaine suivante, l’alerte ouverte agrège les nouvelles occurrences au lieu d’en ouvrir une autre. Chaque alerte porte sa preuve — le claim (claimed) face au catalogue (truth), par modèle.

Statuts d’une alerte

La boucle : vous corrigez la cause (le prix dans la boutique, le stock, la fiche produit), vous traitez l’alerte, puis vous la vérifiez. Vérifier repose la requête de l’alerte à chaque modèle : si le claim a disparu, l’alerte passe resolved ; s’il est toujours là, elle reste treated avec persisted: true.

Je veux…

status=open regroupe new, seen et treated. Scopes : alerts:read, alerts:write. Events : alert.created, alert.updated (changement de statut, avec previous_attributes), alert.resolved.

Scénario : prévenir un client quand une hallucination de prix apparaît

Abonnez un endpoint à alert.created, ne gardez que les hallucinations de prix, et envoyez la preuve à votre client.

if (event.type === 'alert.created' && event.data.object.kind === 'price_hallucination') {
  const alert = event.data.object
  await notifyClient(alert.brand, {
    // `product` est null quand l'IA a donné un prix pour la marque, sans nommer d'offre.
    subject: alert.product?.title ?? 'la marque',
    // Une fourchette : de `price` à `price_max` ; `period` dit ce que le prix achète.
    claimed: [alert.claimed?.price, alert.claimed?.price_max].filter(Boolean),
    truth: [alert.truth?.min, alert.truth?.max],
    period: alert.truth?.period,
    currency: alert.truth?.currency,
  })
}

Une fois le prix corrigé dans la boutique, refermez la boucle :

curl -X POST https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/alerts/alrt_031CQlTxUKUOFYaHSd3kBY/treat \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
 
curl -X POST https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/alerts/alrt_031CQlTxUKUOFYaHSd3kBY/verify \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

verify répond 202 quand un re-sampling démarre (200 s’il en tourne déjà un) ; le verdict arrive ensuite en alert.resolved, ou en alert.updated avec persisted: true.

Pièges

• Une régression SEO n’a ni modèle ni requête. first_seen_at est la fin du crawl qui l’a vue, query et model sont null, occurrences vaut 0 : la preuve est dans claimed.pages. POST …/verify ne s’applique pas ; elle se résout au crawl suivant (alert.resolved).
• Un prix cité n’est pas toujours un nombre. claimed.price_kind vaut exact, range (de price à price_max), from (« à partir de ») ou approximate ; claimed.period (month, year, once) et claimed.unit (flat, per_user) disent ce qu’il achète. Une fourchette qui recoupe le tarif réel n’ouvre aucune alerte ; un prix annuel n’est comparé que si l’offre déclare son price_annual.
• Une alerte de prix peut ne viser aucun produit. Quand l’IA donne un prix pour la marque sans nommer d’offre, claimed.scope vaut brand, product est null et truth est l’enveloppe de toutes les offres actives (truth.min – truth.max, truth.offers). Il y en a une par marché, jamais une par plan.
• Seul un prix exact faux sur une offre nommée est critical. Une fourchette, une approximation ou un prix de marque qui manque le tarif est medium ; la sévérité d’une alerte ouverte peut monter, jamais descendre.
• truth.open_ended : une option sur devis laisse le tarif ouvert vers le haut ; seul un prix sous truth.min est alors faux.
• On ne vérifie qu’une alerte traitée, sinon l’appel répond 422.
• Les vérifications sont rationnées : 10 par marque sur 24 heures glissantes, et une par requête et par heure. Quand le quota est épuisé, verify répond 422 quota_exceeded ; lisez Skoup-Quota-Verifications (limit, remaining, reset) avant de réessayer.
• Les transitions sont à sens unique : une alerte résolue ou ignorée ne se rouvre pas — si l’incident revient, une nouvelle alerte s’ouvre.
• Une spec inventée arrive après les autres : elle est lue dans le jugement Perception, qui finit après le sampling. Elle n’existe qu’avec une fiche d’identité sur le produit, et sa vérification attend aussi ce jugement.
• Les informations d’établissement n’existent que pour une marque local dont un établissement suivi déclare une adresse ou un téléphone ; une alerte par établissement (location : id, name, city) ; les horaires sont rapportés (claimed.hours), jamais jugés.
• close_reason: rejudged : Skoup a fermé l’alerte lui-même parce que l’affirmation ne compte plus comme fausse (une fourchette qui contient le tarif, par exemple). Elle est ignored, arrive par alert.updated — jamais alert.resolved — et ne se rétablit pas.
• Mode test : treat et verify répondent comme en live sur le bac à sable, mais rien n’est conservé et aucun re-sampling ne tourne.