Marques & marchés

Une marque est ce que Skoup mesure : ses offres et sa présence dans les réponses IA. Un espace solo a une marque ; un espace agence a une marque par client, chacune totalement isolée. Presque tous les appels de l’API sont scopés à une marque : son id (br_…) est dans l’URL, /v1/brands/{brand}/….

Une marque est mesurée sur un ou plusieurs marchés — un pays, avec sa langue et sa devise. Les assistants IA ne répondent pas pareil en France et aux États-Unis : chaque mesure (visibilité, readiness, revenue…) est donc par marché. L’un d’eux est le marché principal de la marque : c’est la valeur par défaut dès qu’un appel accepte un paramètre market et que vous l’omettez.

Profils d’activité

Une marque a un profil d’activité (vertical) — ce qu’elle vend — qui décide des modules qui s’appliquent à elle :

`vertical`	La marque	Modules qui n’existent pas pour elle
`ecommerce`	Une boutique en ligne : une boutique ou un feed synchronisés dans un catalogue	—
`saas`	Un logiciel ou un service en ligne : des plans et des offres, déclarés à la main ou lus sur son site	Synchronisation du catalogue, variantes, commandes et CA attribués, corrélation, write-backs, blocs feed et checkout de la readiness, alerte de disponibilité
`local`	Un commerce ou un cabinet de proximité (cabinet, agence, magasin) : ses prestations sur place	Les mêmes que `saas`

Un endpoint d’un module que le profil n’a pas répond 403 capability_unavailable : rien à corriger sur la clé ni sur le plan, le module n’existe pas pour cette marque. Lisez vertical sur la marque avant d’appeler les endpoints d’une boutique.

Établissements

Une marque local a un ou plusieurs établissements (loc_…) — une chaîne de cabinets, de magasins ou d’agences est une marque avec autant d’établissements, le marché restant un pays. Chaque établissement porte son nom, sa ville, son adresse, son téléphone, ses horaires et la page qui le décrit sur le site. Skoup les lit sur le site de la marque (pages d’établissements et leur balisage LocalBusiness) ou les reçoit dans l’app ; tracked dit si le panel écrit des requêtes pour lui.

Chaque requête d’une marque local est posée depuis la ville d’un établissement (location sur la requête), et l’alerte wrong_local_fact juge une adresse ou un téléphone contre l’établissement que la réponse visait (location sur l’alerte) — une alerte par établissement.

Je veux…	Appel
Lister les établissements d’une marque	`GET /v1/brands/{brand}/locations`
Ceux d’un marché, suivis seulement	`GET /v1/brands/{brand}/locations?market=FR&tracked=true`

Le champ locality d’un marché reste servi pour compatibilité (le premier établissement suivi du marché, null sans établissement) : préférez /locations. Les établissements se gèrent dans l’app (étape Marchés, page Établissements), pas par l’API.

Statuts d’un marché

offactive

active = mesuré chaque semaine. off = non mesuré ; un marché qui a un historique est conservé, jamais supprimé. backfill est une valeur transitoire du même champ.

Je veux…

Je veux…	Appel
Lister les marques accessibles à ma clé	`GET /v1/brands`
Lire une marque	`GET /v1/brands/{brand}`
Lister les marchés d’une marque	`GET /v1/brands/{brand}/markets`
Lister seulement les marchés mesurés	`GET /v1/brands/{brand}/markets?status=active`

Scope : brands:read. Events : aucun — marques et marchés se gèrent dans l’app Skoup.

Scénario : retrouver la marque et ses marchés

Toute intégration commence ici : résolvez l’id de la marque une fois, stockez-le, puis lisez ses marchés actifs.


curl https://api.skoup.ai/v1/brands \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"
 
curl "https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/markets?status=active" \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc"

Pièges

Les ids sont opaques. Stockez br_… comme une chaîne ; ne le construisez jamais à partir du nom ou du slug.
Une clé peut être limitée à certaines marques. Une marque hors de sa sélection répond 404 resource_missing, exactement comme une marque inexistante.
Les clés de test voient les marques du bac à sable, pas les vôtres : les ids diffèrent entre test et live.