API para socios

ID de vendedor del mercado web

¿Qué es un mercado?

Los mercados son una oportunidad única para que los minoristas amplíen su presencia en línea y atraigan a compradores nuevos u ocasionales con facilidad. Los mercados permiten a las pequeñas empresas llegar a una amplia variedad de clientes, normalmente enviados directamente por el vendedor del mercado al cliente.

Los mercados permiten a los vendedores poner sus productos a la venta en el sitio de un minorista, lo que aumenta la visibilidad de sus productos ante un público más amplio. De esta forma, los minoristas también amplían su oferta de productos para venderlos a una gama más amplia de clientes.

Además de sacar más rendimiento a su sitio con las capacidades del mercado, los minoristas también pueden aprovechar este espacio de primera clase en las estanterías en línea y ofrecer a los vendedores del mercado la oportunidad de pujar por los primeros puestos mediante CitruSad, con la documentación que se indica a continuación.

Configuración de anunciantes del mercado

Una vez que se completen las mejoras de integración (que se detallan a continuación), podrá establecer un ID de vendedor por equipo. Esto solo se puede hacer al crear un equipo a partir del de minoristas, no se puede hacer al editar un equipo ni a través de un proveedor.

Hay una sección llamada «Campos opcionales» al crear un nuevo equipo donde se puede seleccionar el ID de vendedor. Los ID de vendedor que se pueden seleccionar se obtienen directamente de su catálogo de productos. No puede definir un valor que no esté en el catálogo de productos.

Requisitos de integración

Descripción general

Además de una integración estándar con CitrusAd, deberá mejorar su integración con los siguientes cambios:

  • Aplique un sellerId por producto en el archivo de catálogo de productos o en la API
  • Analice la respuesta del anuncio y presente la oferta correcta del vendedor cuando sea pertinente
  • Informe de un sellerId por producto único al informar de pedidos a CitrusAd

🚧

Actualmente, la función de CitrusAd no contempla completamente el caso de uso en el que un vendedor de un producto no tiene ID de vendedor y también hay variantes de variantes de ID de vendedor de productos. Una solución alternativa para ello es sincronizar un ID de vendedor minorista en cualquier producto que no sea del mercado, y cada proveedor que no sea vendedor de dicho mercado deberá tener este ID de vendedor agregado. Póngase en contacto con el administrador técnico de su cuenta para obtener más información al respecto.

Mejoras en el catálogo de productos.

En su catálogo de productos sincronizado con Citrus, deberá indicar un sellerId por código de producto único a CitrusAd.

Sincronización de catálogo a través de archivo

Deberá añadir una columna/sección adicional a su archivo de catálogo de seller_id. Cada combinación de seller_id y product_code debe estar en una única fila. Para los productos que no son del mercado, el seller_id puede estar vacío.

🚧

Actualmente, los productos que tienen un vendedor de marca (sin ID de vendedor) y los que tienen vendedores del mercado web (con variantes de ID de vendedor) son incompatibles. Si tiene productos que entren en esta categoría, le recomendamos que, por el momento, solo incorpore vendedores del mercado web para estos productos específicos.

Si su sitio de comercio electrónico está configurado con este caso de uso concreto de productos, le rogamos que se lo plantee a su contacto de CitrusAd, ya que estamos estudiando la posibilidad de hacerlo compatible.

Para ver ejemplos, visite Sincronizar el catálogo y los productos a través de archivo

Sincronización del catálogo a través de API

Al sincronizar productos a través de la API, tendrá que sincronizar una sellerId por combinación de sellerId y gtin únicos. 

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"
        }
    ]
}

Mejoras en la respuesta de anuncios

Cuando CitruSad publica anuncios, se mostrará un sellerId si el gtin tiene uno asociado. Esto se aplica a todos los tipos de anuncios, pero solo es relevante para la renderización de anuncios de productos. A continuación se muestra un ejemplo de respuesta de un anuncio de producto:

{
    "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="
}

Para asegurarse de que se muestre la oferta del vendedor correcto, debe leer el sellerId proporcionado por CitrusAd y mostrar la oferta del vendedor correcto al cliente.

Mejoras en los informes de pedidos

Al informar de pedidos a CitrusAd, también tendrá que especificar el sellerId por combinación de gtin al informar de pedidos a CitrusAd.

🚧

Este paso es obligatorio y no puede omitirse o los anuncios no se atribuirán a los pedidos.

Sincronización de pedidos a través de archivo

Deberá añadir una columna/sección adicional a su archivo de pedido de seller_id. Cada combinación de seller_id y product_code debe estar en una única fila. Para los productos comprados fuera del mercado, el seller_id puede estar vacío.

Para ver ejemplos, visite Sincronizar datos de pedidos a través de archivo

Sincronización de pedidos a través de API

Al sincronizar los pedidos a través de API, tendrá que sincronizar el sellerId cuando corresponda al informar de pedidos. En caso de que el producto comprado no tenga un sellerId, se puede omitir.

A continuación se muestra un ejemplo de un pedido en el que un producto proviene de un vendedor del mercado y otro no es un producto del mercado:

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"            
                }
              ]
            }
    ]
}

Migración de equipos existentes

Si está mejorando su integración para apoyar a los vendedores del mercado web, existen una serie de pasos que usted o sus anunciantes deben seguir. Es importante saber cómo funcionan los productos dentro del sistema de CitrusAd.

Un producto sin ID de vendedor y un producto con ID de vendedor son dos entidades únicas en el sistema de CitrusAd. Por lo tanto, es necesario migrar las campañas para seleccionar la nueva variante de producto correcta para todas las campañas existentes que deban actualizarse.

  1. Informe al gestor técnico de su cuenta de CitrusAd sobre su intención de activar la función de ID de vendedor del mercado web
  2. El gestor técnico de su cuenta debería poder asegurarse de que nuestra atribución interna esté configurada para gestionar la migración de los equipos
  3. Mejore el catálogo de productos con productos de ID de vendedor
  4. Mejore los informes de pedidos para informar sobre el ID de vendedor
  5. Si va a migrar equipos existentes, edítelos para que especifiquen el ID de vendedor
  6. Una vez editado un equipo, las campañas de todos los equipos deben editarse también para volver a seleccionar los productos. Esto se debe a que necesitamos que el nuevo producto disponga de un ID de vendedor seleccionado en la campaña, mientras que las campañas creadas antes de que el equipo tuviera un ID de vendedor no contarán con la variante correcta del producto seleccionado.