Produits & write-backs

Un produit est un article du catalogue de la marque : ce que les assistants IA recommandent — ou non — et ce contre quoi Skoup compare leurs affirmations (prix, stock, caractéristiques). Les produits viennent d’une source : shopify (synchronisé depuis la boutique, à jour en temps réel), feed (un feed CSV ou Google Shopping), manual (créé dans Skoup ou par l’API, pour une stack sans connecteur) ou site (une offre que Skoup a lue sur le site de la marque — un plan, une prestation — modifiable comme une manuelle). Pour une marque qui vend un logiciel ou tient un établissement (son profil d’activité), les produits sont ses offres : plans, prestations, soins, avec les mêmes champs.

Un write-back est une modification que Skoup a écrite dans la boutique pour un produit : sa description, son titre et sa description SEO, ou le code-barres de ses variantes. Il est journalisé champ par champ, avec la valeur remplacée, et peut être annulé depuis l’app pendant 30 jours.

Statuts

draftactivearchived

Statut du produit, comme dans la boutique.

failedappliedrolled_back

Statut d'un write-back : il naît failed et passe applied une fois accepté par la boutique ; rolled_back une fois les valeurs précédentes restaurées.

Je veux…

Je veux…	Appel
Chercher dans le catalogue	`GET /v1/brands/{brand}/products?q=grizl`
Lister les produits manuels	`GET /v1/brands/{brand}/products?source=manual`
Lire un produit et ses variantes	`GET /v1/brands/{brand}/products/{product}`
Ajouter un produit (sans connecteur)	`POST /v1/brands/{brand}/products`
Modifier un produit manuel	`PATCH /v1/brands/{brand}/products/{product}`
Voir ce que Skoup a écrit dans la boutique	`GET /v1/brands/{brand}/products/{product}/write_backs`
Voir comment les IA perçoivent un produit	`GET /v1/brands/{brand}/products/{product}/perception` (`metrics:read`)

Scopes : products:read, products:write. Events : product.created, product.updated, product.deleted, catalog.sync.completed, catalog.sync.failed, write_back.applied, write_back.rolled_back, sheet.validated.

Scénario : alimenter Skoup depuis un catalogue Magento

Sans connecteur, poussez vos produits en produits manuels et tenez-les à jour avec PATCH :


curl -X POST https://api.skoup.ai/v1/brands/br_034PJIMnN3EOTCU3TMUdLS/products \
  -H "Authorization: Bearer skoup_test_4eC39HqLyjWDarjtT1zdp7dc" \
  -H "Idempotency-Key: magento-sku-GRZ-CF-SL7" \
  -H "Content-Type: application/json" \
  -d '{"title":"Grizl CF SL 7","sku":"GRZ-CF-SL7","price":2499,"currency":"EUR","url":"https://nordvelo.fr/grizl-cf-sl-7","category":"Gravel"}'

Tarif d’une offre

Une offre vendue par abonnement dit ce que son prix achète :

Champ	Sens
`price`	Le prix d’une période `price_period`.
`price_period`	`month`, `year` ou `once` ; `null` = un prix unique (un produit de boutique).
`price_annual`	Le montant d’une année, quelle que soit la façon dont le site l’écrit.
`price_unit`	`flat` (forfait) ou `per_user` (par utilisateur, praticien, poste).
`addons`	Les options vendues en plus : `name`, `price` (`null` = sur devis), `period`, `unit`. 12 au plus.

Skoup lit ces champs sur la page tarifs du site à l’analyse de la marque (source site) ; vous les corrigez dans l’app ou par PATCH. Ils servent de vérité quand une IA cite un prix : voir le guide Alertes.

Pièges

Les produits synchronisés sont en lecture seule. Un PATCH sur un produit shopify ou feed répond 422 resource_read_only : la boutique fait foi, corrigez-la — Skoup reprend la modification.
Les write-backs ne s’appliquent pas par l’API. Une personne valide le diff dans l’app avant que quoi que ce soit n’atteigne une vitrine ; l’API ne fait que lire le journal.
Un produit retiré à la source émet product.deleted ; il revient avec product.created s’il réapparaît.
price_annual est toujours un montant annuel. Un site qui affiche « 32 €/mois facturé à l’année » vaut price_annual: 384. Skoup accepte ensuite « 32 €/mois » comme « 384 €/an » dans une réponse d’IA.
Les options élargissent la borne haute, jamais le prix. Une option sur devis (price: null) laisse le tarif ouvert : seule une réponse sous le prix de l’offre est fausse.
Mode test : les créations sont annulées ; lisez plutôt le catalogue Nordvelo du bac à sable.