Concepts

Rapprocher ou proposer

Wamia est un catalogue unique : un produit, plusieurs offres. apiMatchListings prend vos SKU avec GTIN, marque, référence fabricant et titre et répond, par SKU, une correspondance avec son niveau de confiance (gtin, brand_mpn, …) ou unmatched. Attachez une offre à une correspondance avec apiUpsertOffers ; pour un SKU sans correspondance, apiSubmitListing propose un nouveau produit, qui entre dans le pipeline d’approbation comme brouillon avec les images que vous donnez par URL et devient un produit quand un modérateur — ou le score de confiance de la boutique — l’approuve. Les modifications de contenu d’un produit en ligne passent par apiProposeListingEdit.

Ne créez jamais de doublons volontairement : les produits rapprochés atteignent la Buy Box immédiatement, les propositions attendent la revue.

Pipeline d’approbation et confiance

Chaque proposition est vérifiée pour sa complétude (attributs obligatoires de la famille, au moins une image), puis relue. Les boutiques au score de confiance élevé sont approuvées automatiquement ; les notes de modération reviennent dans ApiListingView.moderationNotes et par webhook listing.state_changed. Corrigez et resoumettez ; le SKU garde son historique.

Médias

Les images sont copiées dans le stockage Wamia : donnez des URL https publiques à apiIngestMediaFromUrls (20 par appel au plus) et Wamia les récupère de façon asynchrone — apiMyMediaImports suit l’avancement — ou demandez un envoi signé de 15 minutes avec apiCreateMediaUpload et scellez-le avec apiFinalizeMediaUpload. Attachez les visuels à un produit avec apiAssignProductMedia. Réseaux privés, redirections vers ceux-ci, fichiers de plus de 10 Mo et types non image sont refusés avec MEDIA_FETCH_REFUSED.

Garde-fous

Des coupe-circuits protègent la boutique de ses propres bogues : un changement de prix en lot qui déplace plus que la part configurée d’annonces de plus que le pourcentage configuré, ou une mise à jour de stock qui met trop de SKU à zéro d’un coup (cinq annonces ou plus), est retenu au lieu d’être appliqué. L’appel répond BATCH_HELD avec extensions.pendingBatchId, la boutique reçoit un webhook connect.batch_held et une carte dans le tableau de bord, et le plugin peut lister les lots retenus avec apiPendingBatches et les trancher avec apiConfirmBatch ou apiDiscardBatch. Rien du lot n’est appliqué d’ici là ; un lot retenu expire après 7 jours.

Simulation (dry-run)

Envoyez Wamia-Dry-Run: true sur n’importe quelle mutation pour valider le contenu, exécuter les garde-fous et obtenir le résultat par élément sans rien écrire. Les connecteurs s’en servent pour l’aperçu de l’assistant d’import ; utilisez-le avant votre premier vrai appel en lot.

Curseurs et réconciliation

Les listes sont paginées par curseur et acceptent updatedSince ; interrogez apiMyListings(updatedSince) chaque nuit et comparez à vos propres données, ou appelez apiReconcileReport pour un résumé des écarts que Wamia a trouvés entre ce que vous avez envoyé et ce qu’il détient. Les webhooks sont « au moins une fois » ; la réconciliation vous garde exact.

Commandes

Une commande Wamia est découpée en tranches, une par boutique et par site. Votre plugin reflète la tranche en commande locale (apiMyOrdersPage, apiMyOrderSlice), en accuse réception avec apiAcknowledgeSlice, la marque préparée avec apiMarkSlicePrepared et suit le transporteur via apiShipments. Les retours arrivent comme RMA (apiMySliceReturnsPage) et la boutique répond avec apiDecideReturn.