API partenaire

ID de vendeur Marketplace

Qu'est-ce qu'une marketplace ?

Les marketplaces, ou places de marché, offrent aux détaillants une opportunité unique de développer leur présence en ligne et d'attirer facilement de nouveaux acheteurs ou des acheteurs occasionnels. Les marketplaces permettent ainsi à de petites entreprises de toucher un large éventail de clients. Les commandes sont généralement expédiées directement par le vendeur au client.

Les marketplaces permettent aux vendeurs de vendre leurs produits sur le site d'un détaillant, pour toucher ainsi un public plus large. Les détaillants, quant à eux, profitent d'offres de produits supplémentaires, qu'ils peuvent proposer à un plus large éventail de clients.

Outre la monétisation de leur site grâce aux fonctionnalités de marketplace, les détaillants peuvent également tirer parti de cet espace de vente en ligne attractif en donnant aux vendeurs la possibilité de faire des offres via CitrusAd pour profiter d'emplacements de premier choix. Découvrez comment ci-dessous.

Configurer des annonceurs Marketplace

Une fois les optimisations de l'intégration requises terminées (voir ci-dessous), vous pourrez définir un ID de vendeur pour chaque équipe. L'ID de vendeur peut uniquement être ajouté lors de la création d'une équipe à partir de l'équipe du détaillant, et non lors de sa modification ou par un fournisseur.

Lors de la création d'une nouvelle équipe, la section « Champs facultatifs » vous permettra de sélectionner l'ID de vendeur. Les ID de vendeur sont directement issus de votre catalogue de produits. Vous ne pouvez pas saisir une valeur qui n'est pas présente dans ce dernier.

Exigences d'intégration

Aperçu

En plus d'une intégration standard avec CitrusAd, votre intégration devra être optimisée en procédant aux modifications ci-dessous :

  • Déterminez un ID de vendeur pour chaque produit dans le fichier de catalogue de produits ou l'API
  • Analysez la réponse d'annonce et affichez l'offre du vendeur pertinente, le cas échéant
  • Comptabilisez un ID de vendeur pour chaque produit lorsque vous déclarez des commandes à CitrusAd

🚧

Actuellement, la fonctionnalité de CitrusAd ne répond pas entièrement au cas d'utilisation où le vendeur d'un produit n'a pas d'identifiant de vendeur et où il existe également des variantes d'identifiant de vendeur pour les produits. Une solution de contournement identifiée consiste à synchroniser l'identifiant vendeur d'un détaillant sur tout produit ne faisant pas partie du Marketplace, et chaque fournisseur qui n'est pas un vendeur du Marketplace doit avoir cet identifiant de vendeur ajouté. Veuillez contacter votre responsable de compte technique pour en savoir plus.

Optimisation du catalogue de produits

Dans votre catalogue de produits synchronisé avec Citrus, vous devrez fournir à CitrusAd un ID de vendeur par code produit unique.

Synchroniser le catalogue par fichier

Vous devrez ajouter une colonne/section supplémentaire à votre fichier catalogue de seller_id. Chaque combinaison seller_id et product_code doit être une ligne unique. Pour la vente de produits en dehors de Marketplace, le seller_id peut être vide.

🚧

Les produits qui ont à la fois un vendeur de marque (lorsque le produit n’a pas d'ID du vendeur) et des vendeurs Marketplace (lorsque le même produit a plusieurs variantes d'ID du vendeur) sont actuellement incompatibles. Si vous avez des produits qui entrent dans cette catégorie, nous vous recommandons de n'intégrer que des vendeurs Marketplace pour ces produits spécifiques pour le moment.

Si votre site de commerce électronique est configuré pour ce cas particulier d'utilisation des produits, nous vous demandons de le signaler à CitrusAd car nous envisageons de rendre compatible cette utilisation.

Pour consulter des exemples, rendez-vous sur Synchroniser le catalogue et les produits par fichier

Synchroniser le catalogue par l'API

Pour synchroniser des produits par l'API, vous devrez synchroniser un sellerId par combinaison sellerId et gtin unique. 

POST $BASE_URL/v1/catalog-products?teamId=<YOUR_TEAM_ID> HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "catalogProducts": [
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "sellerId": "327272-sade2-3ja",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg",
                 "name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty",
                 "category:Grocery",
                 "Brand:Covergirl",
                 "Special_Flag:0"
            ],
            "profit": "1.50"
        },
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965543",
            "sellerId": "09sa-d32s--faasw",
            "inventory": 50,
            "price": "19.99",
            "tags": [
                 "imageurl:https://your.image.host.com/image.jpg",
                 "name:Covergirl Clean 120 Creamy Natural Liquid Foundation30mL"
            ],
            "filters": [
                 "category:Health&Beauty",
                 "category:Grocery",
                 "Brand:Covergirl",
                 "Special_Flag:0"
            ],
            "profit": "1.50"
        },
        {
            "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
            "gtin": "23556578965738",
            "inventory": 26,
            "price": "8.50",
            "tags": [
                "imageurl:https://your.image.host.com/image.jpg",
                "name:Kelloggs Froot Loops Breakfast Cereal 500g"
            ],
            "filters": [
                "Brand:Kelloggs",
                "category:Pantry",
                "category:BreakfastFoods",
                "category:Cereals",
                "Special_Flag:0"
            ],
            "profit": "0.50"
        }
    ]
}

Optimisation de la réponse d'annonce

Lorsque CitrusAd diffuse des annonces, un sellerId est utilisé uniquement si un ID de vendeur est associé au gtin . Cela s'applique à tous les types d'annonces, mais est uniquement pertinent pour la diffusion d'annonces de produits. Vous trouverez ci-dessous un exemple de réponse d'annonce de produit :

{
    "ads": [
        {
            "id": "display_QqHaKRrKlFm1Wxr9c_DXJN4HSE3NzMzNjM2",
            "gtin": "7733636",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400902957Z",
            "position": 1
        },
        {
            "id": "display_NzsHqP0_iQedlo9VnrO2vqkwi_k3NzMzNjI4",
            "gtin": "7733628",
            "sellerId": "2834-ascre-2wcr4",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2021-05-12T04:17:50.400908257Z",
            "position": 2
        }
    ],
    "banners": [],
    "products": [],
    "memoryToken":"85ykKVv-luDHMWLZx2d6xcPq6sF7CgkJCSJDb3VudGVyIjogIjIiLAoJCQkiQWRzIjogWwoJCQkJImRpc3BsYXlfV05VV0NwQkRKMUpKNm5wdVZSVExvOU40TUxzNE1UWTBOemt5TWc9PSIsCgkJCQkiZGlzcGxheV9MME5NUHRxNmdCcVFvREJOd3J0dE9UTGJoWk0xTVRFeU9UYzRPUT09IiwKCQkJCSJkaXNwbGF5XzlCcEpmdUpaWk9VXzgyaWpFM3VCczgxd3VVczRNekkwTnpVeE5nPT0iLAoJCQkJImRpc3BsYXlfcW1VU1p4TkpMQ0lqeWQwdTFJRDk0RmxVZ0pnNE16STBOelV4Tnc9PSIsCgkJCQkiZGlzcGxheV9oeHlFZktCUnRrNWlxMThMQzE1SDJHcEN3QjgxTVRFeU9UYzVNQT09IiwKCQkJCSJkaXNwbGF5X1NkcjFEcU5aUEFtcGh0Q1FIUndoYUxFT1B0RXhNamsxT1RJNE5BPT0iLAoJCQkJImRpc3BsYXlfeVlSai1qV2Ntc2ozNzhrel9PMm0yOVlwTjhJeE5EazNPRE00TXc9PSIsCgkJCQkiZGlzcGxheV9Xbm9NZGZuLTRTVmhxcF9xQzVvLWxoT0paNm8xTkRJeE1UUTROdz09IgoJCQldLAoJCQkiVFRMIjogMTYyODk4NTYwMAoJCX0="
}

Pour vous assurer que l'offre du vendeur pertinent s'affiche, vous devez lire le sellerId fourni par CitrusAd et afficher l'offre du vendeur pertinent au client.

Optimisation de la comptabilisation des commandes

Vous devez également spécifier le sellerId par combinaison gtin lorsque vous déclarez des commandes à CitrusAd.

🚧

Cette étape est obligatoire et ne doit pas être oubliée, sinon les annonces ne seront pas attribuées aux commandes.

Synchroniser les commandes par fichier

Vous devrez ajouter une colonne/section supplémentaire à votre fichier de commande de seller_id. Chaque combinaison seller_id et product_code doit être une ligne unique. Pour les produits achetés en dehors de Marketplace, le seller_id peut être vide.

Pour consulter des exemples, rendez-vous sur Synchroniser les données de commande par fichier

Synchroniser les commandes par l'API

Pour synchroniser des commandes par l'API, vous devrez synchroniser le sellerId le cas échéant lors de la comptabilisation des commandes. Si le produit acheté n'est pas associé à un sellerId, il peut être omis.

Vous trouverez ci-dessous un exemple de commande contenant un produit qui provient d'un vendeur Marketplace et un autre non :

POST $BASE_URL/v1/orders HTTP/1.1 
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "orders": [
       {
       "customerId": "npc-s243-ir",
        "sessionId": "5cat7-9964-4f",
        "orderDate": "2021-12-02T15:00:00Z",
        "id": "abcti84ew-c158-4d78-a0af-b48bbwfrcss4",
        "orderItems": [
            {
                  "gtin": "9891998566P",
                  "quantity": 3,
                  "regularUnitPrice": "1.00",
                  "totalOrderItemPriceAfterDiscounts": "3.00",
                  "sellerId": "10sa-3s33-j8e3"
                }
              ]
            },
          {
                  "gtin": "351998532P",
                  "quantity": 1,
                  "regularUnitPrice": "2.50",
                  "totalOrderItemPriceAfterDiscounts": "2.50"            
                }
              ]
            }
    ]
}

Migration des équipes existantes

Si vous améliorez votre intégration pour aider les vendeurs Marketplace, vous ou vos annonceurs devez suivre un certain nombre d'étapes. Il est important de savoir comment fonctionnent les produits au sein du système CitrusAd.

Un produit sans ID de vendeur et un produit avec un ID de vendeur sont deux entités distinctes dans le système CitrusAd. Il est donc nécessaire de faire migrer les campagnes afin de sélectionner la nouvelle variante de produit appropriée pour toutes les campagnes existantes qui doivent être mises à jour.

  1. Informez votre responsable de compte technique CitrusAd de votre intention d'activer la fonctionnalité relative à l'ID de vendeur Marketplace
  2. Votre responsable de compte technique pourra s'assurer que notre système d'attribution interne est configuré pour gérer la migration des équipes
  3. Améliorez le catalogue en intégrant des produits avec un ID de vendeur
  4. Améliorez la comptabilisation des commandes pour indiquer l'ID de vendeur
  5. Si vous migrez des équipes existantes, modifiez-les pour spécifier l'ID de vendeur
  6. Une fois qu'une équipe est modifiée, il faut aussi apporter des changements aux campagnes de chaque équipe avant de sélectionner à nouveau les produits. En effet, les nouveaux produits avec un ID de vendeur doivent être sélectionnées dans la campagne. Les campagnes créées avant qu'un ID de vendeur n'ait été attribué à l'équipe ne disposent pas des bonnes variantes pour les produits sélectionnés.