API para socios

Solicitud de páginas de marca

Endpoint de la página de marca

La plataforma de páginas de marca utiliza URL independientes y rutas para los endpoints de generación de anuncios. El administrador técnico de su cuenta le proporcionará su URL básica para los entornos sandbox y de producción.

Autorización

La autorización para la herramienta de páginas de marca es la autenticación de portador. El administrador técnico de su cuenta le podrá proporcionar su token de portador para los entornos sandbox y de producción.

Tendrá que enviar el token en el encabezado como header 'Authorization: Bearer ${apiKey}

Solicitud

Para solicitar una página de marca, deberá enviar una solicitud GET al endpoint de CitrusAd brand-pagecon la URL que solicita

curl --location --request GET '${URL}/api/v1/brand-page:static?url=${url}&retailer=${retailer}' \
--header 'Authorization: Bearer ${apiKey}

🚧

Saneamiento de los parámetros de consulta de la URL

Al solicitar anuncios, deberá eliminar cualquier parámetro de consulta relevante para su sitio de los parámetros enviados a CitrusAd.

Dentro de la plataforma CitrusAd, usamos esta URL para obtener la URL exacta de la página que se solicita. Lo haremos coincidir, https\:www.retailer.com/brand/lollipops-brandpero no si se especifican parámetros de consulta adicionales.

Respuesta

Dependiendo de la configuración de su página de marca, las respuestas de segmento variarán debido a los segmentos integrados y a la plantilla de la página de marca.

Si desea revisar las capacidades de personalización, consulte la página Estructura de alto nivel.

Componentes de respuesta

Contenedor

El contenedor proporciona la información para toda la respuesta de la página de marca, además de contener una matriz de datos de objetos en la que se guardan las respuestas del segmento.

{
  "id": "string",
  "brandPageId": "string",
  "brandPageTemplateId": "string",
  "data": [
  ]
}

La data se rellenará con segmentos dependiendo de la configuración de la página de marca; el formato de los segmentos se detalla a continuación.

Segmentos

Debido a las posibilidades de personalización del producto de las páginas de marca, la respuesta exacta que reciba estará sujeta a su configuración. Cada segmento tendrá un id y un name, además de las propiedades específicas del segmento.

Segmentos de banner

Dentro de la matriz de data , cada segmento es un objeto, como en el ejemplo siguiente:

📘

Los atributos específicos del banner x en la respuesta son solo un ejemplo. Los valores de la respuesta se configuran por plantilla y se pueden personalizar como backgroundImage, brandLogoo según sea necesario.

 {
        "id": "26f6117c-147b-4447-86aa-992e9ddb0daa",
        "name": "primary-content",
    	  "headingText": "Banner For MasterFoods Beef Stroganoff with Shop Now button",
    	  "bannerText": "<strong>The Perfect Mid-Week Dinner</strong>",
    	  "bannerTextColour": "#fff",
   		  "heroImage": "https://storage.googleapis.com/assets-images/coke/2853856c8644",
  	    "heroImageAltText": "<i>Picture of the Dolmio Pasta Sauce</i>",
	      "secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
	      "secondaryHeroImageAltText": "Milo Logo",
	      "secondaryHeroMode": "landscape",
	      "backgroundColour": "895b5b",
	      "backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
	      "backgroundImagePosition": "FILL",
  	    "secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada"
}

Para obtener más información sobre las posibilidades de los segmentos de banner, consulte Estructura de alto nivel.

Segmentos de contenido

Dentro de la matriz de data , cada segmento es un objeto, como en el ejemplo siguiente:

📘

heroText,heroTextColoury del contexto. heroSubText son ejemplos de nuestro minorista de ejemplo. Cada campo puede denominarse según el tipo de campo que corresponda, por ejemplo paragraphText.

 {
        "id": "26f6117c-147b-4447-86aa-992e9ddb0daa",
        "name": "primary-content",
        "heroText": "<i>What a way to start your week</i>",
        "heroTextColour": "#000000",
        "heroSubText": "<i>What a way to start your week</i>",
}

Para obtener más información sobre las posibilidades de los segmentos de contenido, consulte Estructura de alto nivel.

Segmentos de productos

Dentro de la matriz de data , cada segmento es un objeto, como en el ejemplo siguiente:

📘

Este formato de respuesta es fijo y no se puede personalizar

 {
      "id":  "988dc393-a37a-421c-9b08-25f0f9e575f8",
      "name": "my-products",
      "productSelection": [
        {
          "catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
          "position": 3,
          "productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
          "sellerId": "123"
        },
        {
          "catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
          "position": 2,
          "productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
          "sellerId": "123"
        },
        {
          "catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
          "position": 1,
          "productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
          "sellerId": "123"
        }
      ]
    }

📘

Información del producto

Al igual que la integración de anuncios de productos estándar, CitrusAd no incluye atributos del producto como el nombre, el precio y la imagen. Estos deberán obtenerse de un servidor interno de información del producto (o similar) en la infraestructura del minorista.

Aunque esto supone un esfuerzo de integración adicional, garantiza que no haya dependencia de Citrus a la hora de actualizar y cambiar la información de precios, así como que cualquier gráfico automatizado como «en oferta», «al 20 % de descuento» o cualquier otro contenido similar no dependa de CitrusAd.

Para obtener más información sobre las posibilidades de los segmentos de productos, consulte Estructura de alto nivel.

Interpretación de la respuesta

En la respuesta, cada segmento contiene un id y un name. Estos serán únicos para cada segmento dentro de una plantilla. Puede utilizarlos para identificar distintos tipos de componentes, como el tipo de banner o el tipo de contenido, y alinearlos hacia donde los inserte.

Ejemplo de respuesta

He aquí un ejemplo de una respuesta de página de marca para una plantilla con un banner, un contenido y un segmento de producto.

📘

CUSTOM_ID_N es un ejemplo para un identificador definido por el minorista, como paragraphText.

Respuesta

{
  "id": "string",
  "brandPageId": "string",
  "brandPageTemplateId": "string",
  "data": [
    {
      "id":  "string",
      "name": "string",
      "CUSTOM_ID_1": "string",
      "CUSTOM_ID_2": "string",
      "CUSTOM_ID_3": "string"
    },
    {
      "id":  "string",
      "name": "string",
      "productSelection": [
        {
          "catalogId": "string",
          "position": integer,
          "productCode": "string",
          "sellerId": "string"
        },
        {
          "catalogId": "string",
          "position": integer,
          "productCode": "string",
          "sellerId": "string"
        },
        {
          "catalogId": "string",
          "position": integer,
          "productCode": "string",
          "sellerId": "string"
        }
      ]
    },
    {
      "id":  "string",
      "name": "string",
      "CUSTOM_TEXT_FIELD_ID_1": "VALUE",
      "CUSTOM_COLOUR_FIELD_ID_1": "VALUE",
      "CUSTOM_TEXT_FIELD_ID_2": "VALUE",
    }
  ]
}

¿Le interesa ver otras plantillas y ejemplos? Consulte Ejemplos de plantillas de páginas de marca.