Intégration logiciel de caisse (POS)

L'intégration POS permet aux éditeurs de logiciels de caisse d'enrichir leur module occasion avec les données de l'argus VoxSoft mais également de synchroniser son stock afin de retirer automatiquement les offres sur els marketplaces des articles vendus en magasin.
L'architecture est conçue pour que votre POS reste maître du stock : VoxSoft agit comme un fournisseur de données et un canal de vente supplémentaire, jamais comme un concurrent de votre solution.

Principe fondamental : Votre POS reste la source de vérité. VoxSoft enrichit vos données et ouvre un canal marketplace, mais ne pilote jamais votre stock ni votre caisse.

Intégration dans le flux VoxSoft

VoxSoft s'articule autour de 5 modules principaux : Reprise boutique, Reprise web, Gestion du stock, Marketplaces & repricing, Commandes & expéditions.

Reprise boutique Gestion du stock Marketplaces & Repricing Commandes & Expedition Reprise Web Argus Intégration POS

L’Argus VoxGaming enrichit vos données produits (valeur de reprise, prix de vente conseillé, métadonnées) pour les modules de reprise et vente sur le web. L’intégration POS permet de synchroniser automatiquement les mouvements de stock avec votre logiciel de caisse existant.

Sommaire

1. Architecture d'intégration

Schéma d'architecture : POS leader du stock, VoxSoft en satellite pour enrichissement et marketplaces.

L'intégration repose sur un principe simple : le POS notifie, VoxSoft exécute. Votre logiciel de caisse conserve le contrôle total sur le stock et les transactions. VoxSoft intervient en aval pour enrichir les données et gérer la diffusion marketplace.

  • POS = leader du stock. Toute entrée ou sortie de stock est initiée par le POS.
  • VoxSoft = enrichissement + canal de vente. Fournit l'argus, les métadonnées, et gère la mise en vente sur Amazon, Rakuten, VoxGaming.
  • Aucune interférence avec la caisse. VoxSoft ne génère pas de transactions comptables. Le POS gère ses propres écritures de rachat et de vente.
  • Communication bidirectionnelle. Le POS envoie les événements stock, VoxSoft notifie les ventes marketplace.

1.1. Ce que VoxSoft apporte à votre POS

  • Prix de reprise calculé selon les règles du magasin (taux par support, bonus CIB retrogaming).
  • Cotation loose et CIB pour les jeux cartouche.
  • Identifiants marketplace prêts à l'emploi (ASIN, Rakuten ID).
  • Historique des prix sur 12 mois.
  • Mise en vente automatique sur les marketplaces connectées.
  • Repricing automatique selon l'ancienneté en stock.
  • Retrait automatique des annonces lors d'une vente comptoir.

1.2. Ce que votre POS conserve

  • Gestion complète du stock physique (inventaires, écarts, transferts).
  • Transactions de caisse (ventes, rachats, remboursements).
  • Comptabilité et exports fiscaux.
  • Relation client et programme fidélité.
  • Votre système de numérotation (SKU). VoxSoft stocke votre référence et l'utilise pour toutes les notifications.

↑ Retour au sommaire

2. Les 4 endpoints essentiels

L'intégration complète ne nécessite que 4 endpoints. Deux sont appelés par le POS, deux permettent au POS de récupérer des informations depuis VoxSoft.

Endpoint Direction Déclencheur Action VoxSoft
GET /argus/{ean} POS → VoxSoft Scan au comptoir Renvoie argus, prix reprise, métadonnées
POST /stock/entry POS → VoxSoft Reprise validée en caisse Crée la fiche, enrichit, met en vente
POST /stock/sold POS → VoxSoft Vente comptoir Retire l'article des marketplaces
GET /stock/mp-sales VoxSoft → POS Polling ou webhook Liste des ventes MP à décrémenter

La documentation technique complète (authentification, codes d'erreur, exemples par langage) est disponible dans l'espace développeur VoxSoft.

↑ Retour au sommaire

3. Flux de reprise (entrée en stock)

Diagramme de séquence : scan EAN, appel argus, validation POS, notification VoxSoft.

Lorsqu'un client apporte des jeux à reprendre, le flux se déroule en 5 étapes. Le POS reste maître de la transaction de bout en bout.

3.1. Étape 1 : Scan et consultation argus

Le vendeur scanne le code-barres. Le POS appelle GET /argus/{ean} pour récupérer les informations de cotation.

Exemple de réponse JSON — GET /v1/ean/{ean}
{
  "success": true,
  "ean": "0045496460402",
  "title": "Super Mario Land - Nintendo Classics",
  "platform": {
    "code": "gameboy",
    "label": "Game Boy",
    "brand": "Nintendo",
    "support": "cartridge"
  },
  "identifiers": {
    "asin": "B00004TMG4",
    "rakutenId": "8599230366"
  },
  "buyback": {
    "currency": "EUR",
    "argus": 119,
    "source": "argus",
    "is_retrogaming": 1,
    "retrogaming": {
      "support": "cartridge",
      "loose": 31,
      "cib": 119
    }
  },
  "marketplaces": {
    "offers": [
      {
        "marketplace": "amazon",
        "link": "https://www.amazon.fr/dp/B00004TMG4",
        "price": 50.86,
        "shipping": 2.99,
        "total": 53.85
      },
      {
        "marketplace": "rakuten",
        "link": "https://www.fr.shopping.rakuten.com/offer/buy/8599230366",
        "price": 49.90,
        "shipping": 0,
        "total": 49.90
      },
      {
        "marketplace": "fnac",
        "link": "https://www.fnac.com/0045496460402/w-4"
      }
    ],
    "best": {
      "marketplace": "rakuten",
      "total": 49.90
    }
  },
  "images": {
    "cover": "https://cdn.voxsoft.fr/img/catalog/0045496460402.jpg",
    "platform": "https://cdn.voxsoft.fr/img/logo/game-boy.jpg"
  },
  "history": {
    "months": [
      { "period": "Octobre 24", "median_buyback": 28 },
      { "period": "Novembre 24", "median_buyback": 31 },
      { "period": "Décembre 24", "median_buyback": 44 }
    ]
  },
  "meta": {
    "version": "v1",
    "updated_at": "2023-12-01T12:39:24+00:00",
    "cache_ttl_seconds": 86400,
    "request_id": "req_xxx",
    "credits_used": 1
  }
}
  • argus : valeur de marché calculée par VoxSoft.
  • suggested_price : prix de reprise selon le taux configuré par le magasin.
  • rate_applied : taux de reprise appliqué (ici 40 % de l'argus).

3.2. Étape 2 : Négociation et validation POS

Le POS affiche le prix suggéré. Le vendeur peut l'ajuster selon l'état de l'article ou la négociation avec le client. Le POS valide la transaction de rachat selon ses propres règles comptables. VoxSoft n'intervient pas dans cette étape.

3.3. Étape 3 : Notification d'entrée en stock

Une fois la reprise validée en caisse, le POS notifie VoxSoft via POST /stock/entry.

Requête POST /stock/entry
{
  "ean": "3307216154891",
  "sku_pos": "POS-2024-00847",
  "purchase_price": 7.00,
  "condition": {
    "item": "very_good",
    "box": "good",
    "manual": "good"
  },
  "notes": "Légère rayure sur le disque"
}
  • sku_pos : référence interne du POS, conservée pour la synchronisation.
  • purchase_price : prix de rachat réellement payé.
  • condition : état de l'article (objet, boîte, notice).

3.4. Étape 4 : Traitement VoxSoft

VoxSoft reçoit la notification et exécute automatiquement :

  • Création de la fiche article avec SKU VoxSoft.
  • Enrichissement des métadonnées (jaquette, identifiants marketplace).
  • Calcul du prix de vente selon les règles configurées.
  • Mise en vente sur les marketplaces actives (si les critères sont remplis).

3.5. Étape 5 : Confirmation

Réponse POST /stock/entry
{
  "success": true,
  "sku_pos": "POS-2024-00847",
  "sale_price": 15.00,
  "marketplaces_queued": ["amazon", "rakuten"]
}

VoxSoft conserve le sku_pos comme clé de réconciliation. Le POS n'a pas besoin de stocker d'identifiant VoxSoft : toutes les notifications ultérieures (ventes marketplace) référenceront le SKU POS d'origine.

↑ Retour au sommaire

4. Flux de vente comptoir

Diagramme de séquence : vente POS, notification VoxSoft, retrait des marketplaces.

Lorsqu'un article géré par VoxSoft est vendu au comptoir, le POS doit notifier VoxSoft pour que l'article soit retiré des marketplaces. Sans cette notification, l'article resterait en vente en ligne alors qu'il n'est plus disponible.

4.1. Notification de vente

Après validation de la vente en caisse, le POS appelle POST /stock/sold.

Requête POST /stock/sold
{
  "sku_pos": "POS-2024-00847",
  "sale_price": 14.00,
  "sale_channel": "store"
}

4.2. Traitement VoxSoft

VoxSoft identifie l'article via le SKU POS et exécute :

  • Suspension immédiate des annonces sur toutes les marketplaces.
  • Mise à jour du statut de l'article (vendu).
  • Enregistrement de la vente pour statistiques.
Réponse POST /stock/sold
{
  "success": true,
  "sku_pos": "POS-2024-00847",
  "marketplaces_removed": ["amazon", "rakuten"]
}

↑ Retour au sommaire

5. Flux de vente marketplace

Diagramme de séquence : commande marketplace, traitement VoxSoft, notification POS.

Lorsqu'un article est vendu sur une marketplace (Amazon, Rakuten, VoxGaming), VoxSoft traite la commande et notifie le POS pour que celui-ci décrémente son stock.

5.1. Récupération des ventes marketplace

Le POS récupère les ventes marketplace par polling : un appel régulier à GET /stock/mp-sales (toutes les 5 minutes par exemple). Simple à implémenter, compatible avec tous les environnements serveur. L'éditeur POS garde le contrôle total sur le rythme de synchronisation.

Réponse GET /stock/mp-sales?since=2024-01-15T10:00:00Z
{
  "sales": [
    {
      "sku_pos": "POS-2024-00847",
      "ean": "3307216154891",
      "title": "Assassin's Creed Valhalla",
      "sale_price": 14.50,
      "marketplace": "rakuten",
      "order_id": "RK-240115-8847",
      "sold_at": "2024-01-15T14:32:18Z"
    }
  ],
  "count": 1
}

5.2. Traitement côté POS

Pour chaque vente remontée, le POS identifie l'article via son propre sku_pos (celui qu'il avait envoyé lors de l'entrée en stock) et décrémente le stock physique.

La préparation de la commande (picking, expédition, tracking) est gérée dans le module commandes VoxSoft. Le POS n'a pas besoin d'intervenir dans cette partie.

↑ Retour au sommaire

6. Mise en œuvre technique

6.1. Authentification

Toutes les requêtes utilisent une authentification par clé API (Bearer token). Chaque magasin dispose d'une clé unique, générée dans l'interface VoxSoft.

En-tête d'authentification
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxx

6.2. Environnement de test

Des clés de test peuvent être fournies sur demande pour valider l'intégration avant mise en production. Contacter l'équipe technique pour obtenir un accès.

6.3. Gestion des erreurs

L'API retourne des codes HTTP standards et des messages d'erreur explicites.

  • 200 : succès.
  • 400 : requête invalide (champ manquant, format incorrect).
  • 401 : clé API invalide ou expirée.
  • 404 : EAN ou SKU non trouvé.
  • 429 : quota de requêtes dépassé.

6.4. Quotas et limites

  • Endpoint argus : 60 requêtes/minute, 10 000 requêtes/jour.
  • Endpoints stock : 120 requêtes/minute, pas de limite journalière.
  • Réponses mises en cache 24h côté VoxSoft (argus).

6.5. Support technique

L'équipe VoxSoft accompagne les éditeurs POS pendant la phase d'intégration :

  • Documentation technique complète
  • Support technique dédié pendant le développement.
  • Revue de code sur demande.

↑ Retour au sommaire

Contacter l'équipe technique Documentation API