Table of contents
API REST de Criteo para resellers
A continuación, te explicamos los conceptos clave de la API REST del Programa de resellers de Criteo, que te permite gestionar pujas y presupuestos de campañas a nivel de vendedores.
AUTETICACIÓN EN APIUsamos JWT para proporcionar un sistema de autenticación basado en tokens a la API de REST. Para emitir llamadas a la API, deberás pasar un token a cualquiera de estas llamadas.
Para conseguir tu token, necesitarás emitir una llamada POST al endpoint /oauth2/token, con client_id y client secret como parámetros (consulta la sección «Primeros pasos»).
Recupera tu AdvertiserID emitiendo una llamada GET al endpoint /portfolio/.
Recupera tu CampaignID emitiendo una llamada GET al endpoint /sellers/.
Para incorporar un nuevo vendedor, tendrás que asegurarte que está bien identificado en el catálogo de productos que has compartido previamente con Criteo.
Para asegurarte de que el vendedor está bien identificado, deberás establecer la columna seller name (nombre del vendedor) en el identificador exclusivo del vendedor, que es el nombre del vendedor para cada uno de los productos de tu vendedor proporcionados en el catálogo de productos.
Después de llevar a cabo estos pasos, podrás enviarnos el presupuesto y las pujas de tus vendedores gracias a los endpoints de vendedores descritos anteriormente, especialmente:
- PUT /v1/sellers/bids para enviarnos el CPC del vendedor
- POST /v1/sellers/budgets para enviarnos el presupuesto del vendedor
ELIMINAR UN VENDEDOR DEL PROGRAMA DE RESELLERS DE CRITEO
Si deseas eliminar a un vendedor del Programa de resellers de Criteo, solo tienes que detener la actividad de este vendedor en la campaña (consulta la sección «Cómo detener a un vendedor»).
Si lo prefieres, puedes eliminar los productos del vendedor del catálogo de productos. No obstante, esto solo tendrá efecto una vez que Criteo complete la incorporación del catálogo de productos y categoría. Por otra parte, volver a añadirlo llevaría más tiempo ya que también requeriría una nueva incorporación del catálogo de productos y categoría. Por último, en cuanto el vendedor se elimina del catálogo de productos, las estadísticas para este vendedor dejarán de estar disponibles.
Para empezar una campaña del Programa de resellers de Criteo, debes suministrarnos un catálogo de productos exclusivo que contenga productos de todos los vendedores incorporados en el programa. Ten en cuenta que cada uno de estos productos debe tener el identificador único en el campo del vendedor.
Tu campaña se creará automáticamente a partir del momento que se incorpore tu catálogo de productos.
Para que esté online, tu campaña debe tener al menos un vendedor con un presupuesto y una puja ya definidos. Puedes enviarlos a través de los endpoints PUT /v1/sellers/bids y POST /v1/sellers /budgets.
DETENER UNA CAMPAÑA ACTIVA
Para detener toda la campaña del Programa de resellers de Criteo (para todos los vendedores), ponte en contacto con tu account manager.
Para detener a un vendedor o varios vendedores concretos en tu campaña, debes definir sus presupuestos como «Inactive» (inactivos). Una vez hecho, el sistema dejará de mostrar publicidad para los productos de estos vendedores.
Para definir un presupuesto como “Inactivo” debes emitir una llamada PUT al endpoint /sellers/budgets tal como se describe a continuación:
- PUT /sellers/budgets con estatus = Inactive (inactivo)
No hace falta que hagas nada. Prevemos que se agota el presupuesto de todos los vendedores y detenemos sus campañas en cuanto vemos que se están quedando sin presupuesto.
Para definir el presupuesto y el CPC de un vendedor específico, debes utilizar los siguientes endpoints:
- Pujas: para inicialización y actualización: emitir una llamada PUT al endpoint /sellers/bids
- Inicialización de presupuestos:
- Para inicialización: emitir una llamada POST al endpoint /v1/sellers/budgets
- Para actualización del presupuesto: emitir una llamada PUT al endpoint /v1/sellers/budgets
Para aumentar un presupuesto y un CPC para un vendedor específico, debes emitir una llamada PUT a los endpoints /v1/sellers/budgets y /v1/sellers/bids.
REDUCIR CPC
En el caso de que tu vendedor quiera reducir su CPC, debes emitir una llamada POST al endpoint /v1/sellers/bids.
Si tu vendedor quiere reducir su presupuesto, deberás definir el estado actual en «Inactive», de esta manera se detendrá la emisión de anuncios con el presupuesto actual en el día (D) que realizas la acción. Después de ello, podrás crear un nuevo presupuesto con el menor valor (consulta la sección “Cómo crear un presupuesto nuevo”) Este empezará el (D+1), hora UTC
EJEMPLO:
Día 0, vendedor A ha establecido un presupuesto de 1.000 € en su campaña del Programa de resellers de Criteo.
Día 2, vendedor A sigue teniendo 800 € de presupuesto PERO decide reducir su presupuesto disponible a 500 €.
Luego debes emitir las siguientes llamadas:
- Llamada PUT al endpoint /sellers/budgets/
- Establece el status en Inactive
- (no necesitas precisar ningún presupuesto aquí, status tiene prioridad)
- Llamada POST al endpoint /sellers/budgets/
- Establece la cantidad en 500
- (no necesitas proporcionar ningún status aquí; si se deja vacío, presupodremos que será Active)
CREAR PRESUPUESTOS
Puedes crear un presupuesto nuevo si se da uno de estos dos casos:
- No tienes ningún presupuesto para el día actual
- Has tenido un presupuesto inactivo para el día actual
Para crear un nuevo presupuesto para un vendedor, deberás emitir
- Llamada POST al endpoint /sellers/budgets/
El nuevo presupuesto tendrá validez:
- Ahora mismo si no tienes ningún presupuesto para el día actual
- Mañana si has tenido un presupuesto inactivo para el día actual
En primer lugar, necesitarás que tu vendedor te indique el presupuesto actualizado.
A continuación, hay tres escenarios principales que traen consigo diferentes acciones:
- Ya tienes el nuevo presupuesto y es menor que el presupuesto inicial establecido:
- Realiza las acciones descritas en la sección Cómo puedo disminuir un presupuesto/CPC.
- Ya tienes el nuevo presupuesto y es mayor que el presupuesto inicial establecido:
- Aplicar las acciones descritas en la sección «Aumentar un presupuesto/CPC»
- No tiene el presupuesto nuevo/correcto:
- Aplicar las acciones explicadas en la sección «Cómo eliminar a un vendedor»
- Aplicar las acciones explicadas en la sección «Cómo eliminar a un vendedor»
En primer lugar, deberás pedirle al vendedor que te indique el CPC actualizado. A continuación, deberás emitir una llamada PUT al endpoint sellers/bids/ para fijar la puja actualizada.
Dado que nuestra API se basa principalmente en el sellerName para gestionar las pujas y los presupuestos, cualquier cambio en el nombre del vendedor creará automáticamente una nueva entrada en nuestro sistema, no vinculada al nombre del vendedor anterior.
En resumen, si un vendedor cambia su nombre en tu plataforma, deberás:
- Actualiza el catálogo de productos con el nuevo sellerName.
- Inicializar la puja y el presupuesto del vendedor enviándonos una instrucción PUT /v1/sellers/bids y POST /v1/sellers/budgets.
Para obtener una vista del presupuesto gastado para un vendedor concreto en una campaña del Programa de resellers de Criteo, emite una llamada GET al endpoint /v1/sellers. La información estará disponible como spentAmount.
Para obtener una vista del presupuesto gastado para un vendedor concreto en una campaña del Programa de resellers de Criteo, emite una llamada GET al endpoint /v1/sellers. La información estará disponible como remainingAmount.
Generación de informesPuedes emitir una llamada POST al endpoint /v1/sellers/stats. Solo es posible acceder a las impresiones, clics y coste en el nivel de vendedor, disponible hasta una granularidad diaria.
Se puede utilizar un máximo de 3 dimensiones y deben contener la dimensión del vendedor.
Dimensiones disponibles:
- AdvertiserID
- campaignID
- Vendedor – Obligatorio
- Año
- Semana
- Día
Métricas disponibles:
- Displays
- clics
- AdvertiserCost