API del plano de control de la puerta de enlace de la API de conversiones para varias cuentas

Integración con socios

Información general

La API del plano de control de la puerta de enlace de la API de conversiones para varias cuentas es un conjunto de API de GraphQL que se exponen desde la instancia de la puerta de enlace. Permite a los desarrolladores administrar mediante programación las cuentas, los orígenes de datos y otras configuraciones de una instancia de la puerta de enlace. Los socios pueden integrar la API para crear en su IU orientada a los anunciantes y ofrecerles un proceso fluido de incorporación y administración.

Posibles casos de uso:

Los anunciantes se incorporan a la puerta de enlace mediante la IU del socio y realizan acciones de seguimiento mediante la configuración de administrador de la puerta de enlace. Esto requiere una integración parcial de la API del plano de control.
Los anunciantes realizan todas las acciones en la IU del socio, incluida la incorporación en la puerta de enlace y las acciones de seguimiento. Puede ser un buen caso de uso para los socios que no quieran exponer la IU de la puerta de enlace, pero quieran proporcionar la puerta de enlace como un servicio para los anunciantes. Esto requiere una integración completa de la API del plano de control.

Consulta la sección siguiente para obtener más información sobre los pasos de integración.

En este documento se usan indistintamente las siguientes denominaciones: API del plano de control de la puerta de enlace de la API de conversiones para varias cuentas o puerta de enlace.

Guía de integración

En función del caso de uso, puede haber dos rutas de integración (tal como se muestra en el diagrama siguiente):

Integración parcial de la API del plano de control. No requiere autenticación de los anunciantes.
Integración completa con la API del plano de control. Requiere autenticación de los anunciantes ya sea mediante la extensión de Meta para empresas (MBE) o la generación manual de identificadores.

Requisitos previos

En ambas rutas de integración, el socio primero debe completar los pasos siguientes:

Paso 1: Incorporarse como host de la instancia de la puerta de enlace

Paso 2: Generar el nombre de la cuenta y la clave secreta de la API

Ve a:

https://<Conversions API Gateway Endpoint>/hub/

Accede a la pestaña Configuración del host, selecciona la página Administrar cuentas de la API y haz clic en el botón Añadir cuenta de la API.

Vuelve a escribir la contraseña. Haz clic en Continuar.

Escribe el nombre de la cuenta de la API. Haz clic en Continuar.

El nombre de la cuenta solo puede incluir letras y números, no puede contener espacios. La longitud máxima es de 20 caracteres.

Copia y guarda la clave secreta generada. No podrás volver a verla.

Para eliminar una cuenta de la API, haz clic en Eliminar cuenta de la API. Ten en cuenta que la acción no es reversible y puede causar interrupciones en las aplicaciones o servicios del anunciante que utilicen la API.

Integración parcial

Caso de uso basado en la integración parcial:

El anunciante activa el servicio de la puerta de enlace mediante la IU del socio.
El socio genera un enlace de invitación que el anunciante puede usar para establecer una contraseña y completar la creación de la cuenta de la puerta de enlace.
El anunciante utiliza funcionalidades de la IU de la puerta de enlace para realizar acciones como la administración de los orígenes de datos o la administración de los usuarios de la cuenta, los dominios y el enrutamiento.
El socio recupera el uso y las facturas de la cuenta del anunciante en consecuencia.

Un proceso de usuario general podría tener un aspecto similar al siguiente:

Para lograr lo anterior, el socio puede integrar un subconjunto de la API del plano de control que incluya lo siguiente:

Obtener el identificador de acceso a la API
Crear cuenta para los anunciantes
Obtener el uso de la cuenta, por ejemplo, con fines de facturación

Integración completa

Caso de uso basado en la integración completa:

El anunciante activa el servicio de la puerta de enlace mediante la IU del socio.
El socio incorpora la cuenta de la puerta de enlace del anunciante y recibe permiso para administrar la cuenta; el anunciante autoriza al socio mediante la extensión de Meta para empresas (MBE) o la generación manual de identificadores.
El anunciante puede administrar los orígenes de datos, así como los usuarios de la cuenta, los dominios y el enrutamiento en la IU del socio.
El socio recupera el uso y las facturas de la cuenta del anunciante en consecuencia.

Un proceso de usuario general podría tener un aspecto similar al siguiente:

En el caso de esta ruta de integración, los socios deben solicitar autorización y obtener identificadores de acceso de usuario del sistema mediante autenticación para enviar eventos en nombre de los anunciantes.

Autenticación

Los socios disponen de las dos siguientes opciones para los píxeles de Meta de cuya administración no se encargan:

Opción 1: Extensión de Meta para empresas (MBE)

Antes de comenzar, debes:

Cumplir todos los requisitos para implementar MBE.
Ponerte en contacto con tu representante de Meta para añadir la aplicación a la lista de autorizados de un permiso privado: open_bridge_configuration_management.

MBE proporciona un extremo para recuperar los identificadores de acceso de usuario del sistema creados en la cuenta de Business Manager del anunciante. Los socios pueden seguir con el paso 4 de la guía de integración de MBE. Asegúrate de:

Establecer el valor del parámetro de canal en el objeto de configuración como CONVERSIONS_API_GATEWAY_ADVERTISER.
Poder recibir la respuesta del webhook al finalizar la incorporación.
Usar el identificador de acceso devuelto mediante MBE y convertirlo en un identificador de acceso de usuario del sistema mediante una llamada adicional a la API.
Guardar una copia de external_business_id, pixel_id, business_id y el identificador de acceso de usuario del sistema en el sistema.

Opción 2: Identificador de acceso de usuario del sistema del cliente

Con esta opción, los socios pueden conseguir que los anunciantes hagan lo siguiente:

Creen manualmente un identificador de acceso de usuario del sistema mediante la API de conversiones en Configuración, en el Administrador de eventos.
Compartan los valores de pixel_id y business_id y el identificador de acceso de usuario del sistema con el socio y guarden una copia.

Integración

Los socios pueden integrar el conjunto completo de la API del plano de control. Consulta más información en la referencia de la API.

Paridad de la API y la IU

Estamos aplicando la paridad de la API y la IU al exponer los mismos extremos de la API que se utilizan en la IU de la puerta de enlace. Sin embargo, los extremos de la API que no se tratan en la referencia de la API están sujetos a cambios en el desarrollo futuro. Para limitar el impacto inesperado al mínimo, dichos extremos de la API que no se tratan devuelven el código de error 418. Puedes seguir utilizando la API, pero bajo tu propio riesgo.