Correctifs

L’inbox est l’écran « Correctifs » de l’app en API : une seule file de tout ce que la marque peut corriger sur un marché, d’où que ça vienne, déjà dans l’ordre où s’en occuper. Alertes ouvertes, tâches, checks readiness et SEO en échec, écarts de perception, territoires vacants, sites à conquérir, constats de l’écran Pages, fiches d’un établissement : chaque ligne est l’un d’eux.

Une ligne n’est pas un enregistrement à part. Elle EST un objet existant, donc elle n’a pas d’id préfixé : son id est composé (alert:{uuid}, task:{uuid}, readiness:{check}, seo:{check}, perception:{produit}:{écart}, opportunity:{attribut}, source_gap:{hôte}, insight:{kind}:{hash}, listing:{id}:{kind}) et stable tant que l’objet tient. Les objets qui ont un id public le portent (alert, task.id, product.id, location.id). L’inbox n’écrit rien : on agit sur l’objet derrière la ligne, par ses propres endpoints.

Une ligne par objet. Une tâche absorbe ce dont elle est née : une alerte, un check ou un écart qui a déjà une tâche ouverte apparaît comme cette tâche, jamais deux fois. Un prix ou un stock faux qui a une alerte ouverte apparaît comme l’alerte.

Je veux…

Je veux…	Appel
La file d’un marché, dans l’ordre	`GET /v1/brands/{brand}/inbox?market=FR`
Seulement ce qui coûte des ventes cette semaine	`GET /v1/brands/{brand}/inbox?group=now`
Seulement les alertes critiques	`GET /v1/brands/{brand}/inbox?q=kind:alert severity:critical`
Tout, correctifs vérifiés compris	`GET /v1/brands/{brand}/inbox?q=is:all`
Traiter l’alerte derrière une ligne	`POST /v1/brands/{brand}/alerts/{alert}/treat` avec le `alert` de la ligne
Faire avancer la tâche derrière une ligne	`PATCH /v1/brands/{brand}/tasks/{task}` avec le `task.id` de la ligne
Suivre une ligne dans une tâche à vous	`POST /v1/brands/{brand}/tasks` (une tâche manuelle : la ligne reste jusqu’à ce que son objet soit corrigé — les tâches liées à un check ou un écart s’ouvrent depuis l’app)

Scopes : alerts:read et tasks:read (la file liste les deux). Un assistant lit la même file avec l’outil MCP list_inbox.

Les groupes

Les lignes arrivent groupées, dans cet ordre, et triées dans chaque groupe. Lisez-les comme elles viennent : l’ordre est le service rendu.

`group`	Ce qui y tombe
`now`	Coûte des ventes cette semaine : une alerte `critical` ; un prix, un stock ou un fait d’établissement faux vu au moins deux fois ou encore là après une vérification ; une chute de visibilité ; une régression SEO ; un prix ou un stock faux dans la perception d’un produit ; une page qui perd ses clics ou reçoit du trafic en erreur ; une tâche dont la date de vérification est passée ; une petite tâche (`effort: s`) qui dit ce qu’elle rapporte.
`week`	Fait monter la visibilité : une alerte `medium` ; un check readiness ou SEO en erreur ; un écart de perception déformé ou absent qui vaut au moins 2 points ; un territoire vacant ; une fiche qui contredit son établissement ; les autres tâches ouvertes.
`later`	Quand vous pouvez : une alerte `low` ; un check en avertissement ; un petit écart de perception ; un site à conquérir ; les constats de trafic mineurs ; une fiche incomplète ou manquante.
`verified`	Les tâches vérifiées depuis 90 jours — ce que les correctifs ont changé. Listées seulement avec `q=is:all`, `q=is:verified` ou `group=verified`.

Dans un groupe : la gravité d’abord, puis impact.points, puis le nombre de fois où le problème a été vu, puis l’effort (petit d’abord), puis le plus récent. score est cet ordre en un nombre : ne le comparez qu’à l’intérieur d’un groupe.

Recherche

q prend la grammaire de recherche de l’app. Sans is:, seuls les groupes ouverts (now, week, later) sont listés.

Qualificatif	Valeurs
`is:`	`open` (défaut), `verified`, `all`
`kind:`	`alert`, `task`, `audit` (readiness), `seo`, `perception`, `traffic`, `competitors`, `listing`
`severity:`	`critical`, `medium`, `low`
`product:` / `offer:` / `location:`	une partie du titre du produit ou du nom de l’établissement, p. ex. `product:"Strade 7"`
`model:`	`chatgpt`, `claude`, `gemini`, `perplexity`…
`effort:`	`s`, `m`, `l`
`after:` / `before:`	`AAAA-MM-JJ`, sur la dernière fois que la ligne a été vue

- inverse un qualificatif (-kind:task) ; le reste est du texte libre sur le titre.

Scénario : la liste du lundi pour l’équipe


curl -G "https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/inbox" \
  --data-urlencode "market=FR" \
  --data-urlencode "group=now" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Lancez-le après le sampling.completed de la semaine : les lignes sont déjà dans l’ordre, publiez-les telles quelles.

Pièges

Pas d’event. L’inbox est calculée à l’appel ; rien « n’arrive » à une ligne. Suivez plutôt les objets : alert.created, alert.resolved, task.verified.
impact.points peut valoir null. C’est un nombre mesuré quand la source en compte un (points readiness ou perception, answers, clicks, points de visibility), jamais 0 pour « inconnu ». Des points d’unités différentes ne se comparent pas.
Une tâche est à la marque. Une ligne de tâche a market: null quand sa source ne nomme pas de marché, et apparaît sur tous les marchés.
La pagination est un curseur dans l’ordre de la file : limit (1 à 100, 20 par défaut) et starting_after = l’id de la dernière ligne de la page précédente. La file peut bouger entre deux appels (un sampling, un correctif) : repartez du début plutôt que de reprendre un vieux curseur.
Un plan sans la fonctionnalité Opportunités garde une ligne opportunity:locked avec plan_feature: "opportunities" : le module est montré verrouillé, jamais caché.
Les titres sont en anglais, composés par Skoup depuis les faits mesurés.