La extensión Facebook Business (FBE) permite que tus usuarios suban recursos de contenido fácilmente a la familia de apps de Meta mediante la conexión con un administrador comercial nuevo o preexistente. Con el administrador comercial que se devuelve después de completar este proceso, los socios pueden subir recursos de contenido en Facebook en representación de sus clientes:
En este documento se describen los principales requisitos previos para el flujo de contenido de la FBE, junto con los pasos necesarios para completar el proceso. Consulta la guía de la extensión Facebook Business para obtener información específica sobre integraciones generales.
Ejemplo: El proceso de incorporación desde la superficie del socio (Inicio de sesión de empresas)
Regístrate como desarrollador de Facebook si quieres acceder a nuestras herramientas para desarrolladores y crear apps de Facebook.
Si todavía no lo hiciste, crea una app de Facebook.
Tu app de Facebook debe pertenecer a un administrador comercial que sea un negocio verificado. Obtén más Información sobre cómo verificar tu negocio.
Crea una app de prueba y úsala para realizar todos los nuevos desarrollos y pruebas. Asegúrate de asignar a un administrador comercial diferente para probar la app.
Permisos y funciones privadas:
manage_business_extension
: acceso a la extensión Facebook Business. Una vez que esta funcionalidad se incorpore a tu app, encontrarás el panel de desarrolladores de FBE en la sección Productos.
Business_creative_asset_management
: acceso a las API de administración de recursos relacionados con el contenido. Una vez que te hayan otorgado esta función, podrás acceder a los siguientes permisos:
business_creative_insights
: permite acceder a estadísticas de recursos de contenido del negocio.
business_creative_management
: permite que tu app cree, edite y comparta nuevas carpetas, y suba recursos en ellas en el contexto de tu propia entidad empresarial.
business_creative_insights_share
(en desarrollo): permiso opcional que se usa en el flujo de uso compartido de carpetas. Si el usuario lo permite, tu app podrá compartir la carpeta de contenido con otros negocios y permitirles ver estadísticas de recursos de contenido.
Genera un token de acceso de socio:
Sigue estas instrucciones para generar un token de acceso del usuario del sistema administrativo en el administrador comercial.
Asegúrate de que este token tenga permisos business_creative_insights
, business_creative_management
y business_management
seleccionados en el paso de "alcances disponibles".
Este botón se usa para enviar un recurso a la biblioteca multimedia de Facebook del usuario desde tu app. Durante este proceso, tu app deberá permitir que el usuario seleccione o cree una carpeta para enviar a ella el recurso.
Recomendamos dos enfoques para hacer esto:
1. (Mínimo) El usuario solo tiene la opción de elegir o crear una carpeta de nivel superior. En el contexto comercial seleccionado, haz una consulta a todas las carpetas de nivel superior a las que tenga acceso el usuario. Pide al usuario que elija una carpeta de nivel superior existente o crea una. Los usuarios pueden especificar el nombre de carpeta o usar el nombre predeterminado de la carpeta <YourBusinessName>_<UserBusinessName>_<UserName>
. Carga los recursos en nueva carpeta de nivel superior o en la seleccionada. Este enfoque requiere un mínimo trabajo en la UI y se puede hallar información sobre la API en el paso 3 a continuación.
2. (Opcional) El usuario tiene control total de la navegación de carpetas y subcarpetas. En el contexto comercial seleccionado, consulta todas las carpetas de nivel superior a las que el usuario tenga acceso y pídele que elija una carpeta de nivel superior existente o cree una nueva. Si crea una nueva carpeta, pide al usuario que dé nombre a la carpeta o use el nombre predeterminado <YourBusinessName>_<UserBusinessName>_<UserName>
. En la carpeta de nivel superior seleccionada, el usuario tiene la opción de navegar hasta una subcarpeta existente, crear una nueva o subir recursos. Con esta opción, deberás implementar la navegación de carpetas en tu UI. Se pueden hallar instrucciones de integración en el paso 3 y el paso 4, a continuación.
Los pasos específicos requeridos para implementar este flujo son los siguientes:
Cuando el usuario envía un recurso de contenido a Facebook por primera vez, debes indicar a la extensión de Facebook para empresas que solicite al usuario que autentique tu app y le otorgue los permisos y el acceso necesarios a los recursos, bajo la forma de tokens de acceso, a fin de acceder a sus datos en Facebook. Consulta Extensión de Facebook para empresas: primeros pasos para implementar la extensión de Facebook para empresas en tu app. Sigue la guía sobre Apps de negocios para que tu app aparezca en Apps de negocios.
Para solicitar el flujo de contenido:
business_creative_management
y business_creative_insights
.
business_creative_insights_share
.
VIEW_INSIGHTS
.Usando el token de acceso de usuario devuelto de esta solicitud, puedes hacer llamadas a la API en representación del usuario.
Campo | Tipo | Descripción |
---|---|---|
| configuración | Obligatorio La configuración del vendedor en Facebook, como su identificador único ( |
| business_config | Obligatorio Objeto de configuración que usa la extensión de Facebook para empresas para configurar el proceso de trabajo de la extensión de Facebook para empresas. Consulta |
| booleano | Obligatorio Configura esta valor como |
Usa este objeto para definir los parámetros de la presencia en Facebook del usuario final
Campo | Descripción |
---|---|
| Obligatorio. |
| Obligatorio. |
| Obligatorio. |
| Obligatorio. |
| Obligatorio.
|
| Opcional. |
Usa este objeto a fin de configurar los parámetros del negocio para un usuario final. Esto incluye CTA (llamada a la acción), tarjetas de servicios y otros. Cada campo incluye un "tipo" vinculado a las tablas correspondientes que aparecen a continuación.
Campo | Descripción |
---|---|
| Obligatorio. |
Usa este objeto para configurar el nombre de las empresas.
Campo | Descripción |
---|---|
| Obligatorio. |
Una vez que el usuario complete el flujo de incorporación de la FBE anterior, recibirás el identificador de administrador comercial y el token de acceso de usuario de la API de instalación de la FBE o la notificación de Webhooks.
Los usuarios pueden subir recursos a la carpeta de nivel superior o crear subcarpetas en la carpeta de nivel superior.
Primero, verifica las carpetas de nivel superior a las que el usuario tiene permiso para la tarea CREATE_CONTENT
. Para esto, haz una solicitud al punto de conexión <business_id>/creative_folders
(en desarrollo).
Solicitud
curl -X GET \ -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<user_business_id>/creative_folders?filtering=[{field:"permitted_tasks", operator: "EQUAL", value:"create_content"}]
Respuesta
{ "id": "<folder_id>" }
Solicita al usuario que elija una carpeta de nivel superior preexistente o cree una nueva dentro del contexto del administrador comercial del usuario. Si se crea una nueva carpeta de nivel superior, puedes pedir al usuario que asigne un nombre a la carpeta o usar el nombre predeterminado <YourBusinessName>_<UserBusinessName>_<UserName>
. Si el usuario comparte la carpeta contigo, será visible para tu empresa y la del usuario en la biblioteca de recursos de Facebook.
Nota: el nombre del negocio del usuario se puede obtener haciendo una solicitud GET
al punto de conexión {business-id}
donde {business-id}
es el identificador del negocio del usuario.
Solicitud
curl -X GET \ -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>
Respuesta
{ "id": {business-id} "name": {user-business-name} }
Solicitud
curl -X POST \ -F "name={folder_name}" -F "description={description}" -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders
Respuesta
{ "id": {top-level-folder-id} }
Si deseas admitir el flujo completo de navegación de carpetas, pide al usuario que elija una subcarpeta existente o cree una nueva en la carpeta de nivel superior con las siguientes solicitudes:
business_creative_management
Solicitud
curl -X GET \ -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<parent_folder_id>/subfolders?fields=name
Respuesta
{ "data": [ { "name": "<subfolder_name>", "id": "<subfolder_id>" } ] }
business_creative_management
Solicitud
curl -X POST \ -F "name={folder_name}" -F "description={description}" -F "parent_folder_id={parent-folder-id}" -F 'access_token={user-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders
Respuesta
{ "id": {sub-folder-id} }
La carpeta y la subcarpeta se pueden eliminar mediante el envío de una solicitud DELETE
al punto de conexión <folder_id>
o <subfolder_id>
.
Sube los recursos de contenido del usuario a la subcarpeta.
business_creative_management
Solicitud
curl -X POST \ -F 'bytes={image-content-in-bytes-format}' \ -F 'name={image-name}' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={subfolder-id}' \ https://graph.facebook.com/{version}/{business-id}/images
Respuesta
{ "images":{ "{image-name}":{ "id":"{business-creative-image-id}", "hash":"{hash}", "url":"{image-url}" } } }
Sube un video en una sola solicitud si su tamaño es de unos pocos megabytes o cárgalo en partes (consulta la siguiente sección). Haz la llamada a la API para subir video en graph-video.facebook.com
en lugar de graph.facebook.com
.
Ejemplo: envía un POST
a {business-id}/video
e incluye el nombre de tu video, el origen y el identificador de subcarpeta.
Solicitud
curl -X POST \ -F 'name={video-name}' \ -F 'source='@{video-path}'' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={subfolder-id}' \ https://graph-video.facebook.com/{version}/{business-id}/videos
Respuesta
{ "success": true, "business_video_id": "<business_video_id>" }
Para videos más grandes, envía una solicitud de inicio, una o varias solicitudes de transferencia y una solicitud de finalización.
Para realizar una solicitud de inicio y crear una sesión de subida de video, envía una solicitud POST
a /{business-id}/videos
, fija el campo upload_phase
en “start” y especifica file_size
, en bytes.
Solicitud
curl -X POST \ -F 'title={video-name}' \ -F 'creative_folder_id={subfolder-id}' \ -F 'access_token={user-access-token}' \ -F 'upload_phase=start' \ -F 'file_size={video_file_size_in_bytes}' \ https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos
Respuesta
{ "upload_session_id": "{session-id}", "video_id": "{video-id}", "start_offset": "0", "end_offset": "52428800" }
Para subir [0,52428800] de tu video, segmenta el archivo según los desplazamientos de inicio y finalización, y, luego, envía esos segmentos con solicitudes de transferencia. Te enviaremos nuevos desplazamientos para cada segmento; úsalos para subir cada segmento.
Ejemplo: envía tu primer segmento
Solicitud
curl -X POST \ -F 'title={video-name}' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={subfolder-id}' \ -F 'upload_phase=transfer' \ -F 'upload_session_id={session-id}' \ -F 'start_offset=0' \ -F 'video_file_chunk=@{binary-chunk-filename}' \ https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos
Respuesta
Si la operación se realiza correctamente, responderemos con los desplazamientos de tu próximo segmento:
{ "start_offset": "52428800", //Start byte position of the next file chunk "end_offset": "104857601" //End byte position of the next file chunk }
Corta y sube el segundo segmento con el intervalo [52428800, 104857601] de tu archivo y envíalo:
Solicitud
curl -X POST \ -F 'title={video-name}' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={subfolder-id}' \ -F 'upload_phase=transfer' \ -F 'start_offset=52428801' \ -F 'upload_session_id={your-upload-sesson-id}' \ -F 'video_file_chunk={binary-chunk-filename}' \ https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos
Respuesta
Envía todos los segmentos adicionales hasta que start_offset
sea equivalente a end_offset
:
{ "start_offset": "152043520", "end_offset": "152043520" }
La respuesta anterior implica que subiste todo el archivo. Ahora debes publicar este video y cerrar la sesión de subida.
Solicitud
curl -X POST \ -F 'title={video-name}' \ -F 'access_token={user-access-token}' \ -F 'creative_folder_id={business-creative-folder-id}' \ -F 'upload_phase=finish' \ -F 'upload_session_id={session-id}' \ https://graph-video.facebook.com/<API_VERSION>/<BUSINESS_ID>/videos
Si recibes errores durante una subida, puedes intentar subirlo de nuevo. Normalmente, los errores se deben a problemas en respuestas. Intenta nuevamente subir el segmento que falló. Para obtener más información sobre errores, consulta:
Tu app debe notificar al usuario que la subida se completó con éxito y presentar un enlace profundo a este contenido detrás de una llamada a la acción “Ver contenido en mi biblioteca de recursos de Facebook”. Enlace profundo de la carpeta o del recurso:
https://business.facebook.com/asset_library/business_creatives/?object_id={asset_id or folder id}
(en desarrollo)
Este enlace dirige al usuario a la página de selección de la empresa si este tiene varios administradores comerciales. Para eliminar la ambigüedad en la empresa, puedes proporcionar contexto de empresa en la URL de la siguiente manera:
https://business.facebook.com/asset_library/business_creatives/?object_id={asset_id or folder id}&business_id={client_business_id}
La URL del enlace profundo también se puede obtener realizando una solicitud GET
en el punto de conexión:
curl -X GET \ /<folder_id or asset_id> ?fields=['media_library_url'] &access_token=<user_access_token>
El enlace permite al usuario ir a la carpeta o al recurso directamente en la biblioteca de recursos de Facebook.
Puedes solicitar que se comparta la carpeta de nivel superior contigo si deseas administrarla o ver estadísticas de los recursos. Envía una solicitud POST
a {business-creative-folder-id}/agencies
y asigna permitted_tasks
a CREATE_CONTENT
.
Nota: También puedes asignar la tarea permitida VIEW_INSIGHTS
si el usuario otorga business_creative_insights_share
a tu app (en desarrollo).
business_creative_management
Solicitud
curl -X POST \ -F 'permitted_tasks=['CREATE_CONTENT','VIEW_INSIGHTS']' \ -F 'business={partner-business-id} ' \ -F 'access_token={user-access-token}' https://graph.facebook.com/<API_VERSION>/<BUSINESS_CREATIVE_FOLDER_ID>/agencies
La respuesta se da en uno o dos tipos, según el rol del usuario en su organización comercial:
La API establecerá un acuerdo de colaboración entre las empresas del usuario y la del cliente.
Respuesta
Si hay un acuerdo de colaboración establecido entre el negocio del usuario y el tuyo (la empresa del usuario compartió una carpeta contigo y tú aceptaste con anterioridad una solicitud para compartir):
{ "success": true }
Si aún no aceptaste solicitudes para compartir del negocio del usuario:
{ "success": true, "share_status": "In Progress" }
En ese caso, tu negocio deberá aceptar la solicitud para compartir y así poder acceder a todas las funciones que están habilitadas en el proceso de uso compartido (ver, crear, etc.).
Para enumerar todos los acuerdos de colaboración con aprobación pendiente, envía una solicitud a {business-id}/received_sharing_agreements
usando tu token de acceso de socio y fija request_status
en IN_PROGRESS
. Necesitas los permisos business_creative_management
y business_management
para esta acción.
Listar todos los acuerdos de colaboración
Solicitud
curl -i -X GET https://graph.facebook.com/<API_VERSION>/<PARTNER_BUSINESS_ID>/received_sharing_agreements ?request_status=IN_PROGRESS &access_token={partner-access-token}"
Para aceptar una solicitud de compartir, envía un POST
a business_sharing_agreement_request_id
y configura request_status
en APPROVE
. Solo necesitas hacer esto la primera vez que alguien comparta una carpeta con tu empresa. Necesitas el permiso business_management
para esta acción.
Aceptar todos los acuerdos de colaboración
Solicitud
curl -X POST \ -F 'request_status=APPROVE' \ -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_SHARING_AGREEMENT_REQUEST_ID>
Respuesta
{ "success": true }
Como alternativa, puedes aprobar solicitudes para compartir pendientes en la UI del administrador comercial. Para ver solicitudes pendientes en el administrador comercial, dirígete a Configuración > Solicitudes > Solicitudes recibidas, donde verás más información sobre estas.
La API activa un flujo de trabajo de notificación para enviar una notificación por correo electrónico a administradores de negocios para aprobar la solicitud.
Respuesta
{ "success": true, "share_status": "Pending" }
En respuesta a este estado, tu app debe notificar al usuario lo siguiente:
Para listar todos los acuerdos pendientes que se hayan iniciado en el negocio del usuario, envía una solicitud a {business-id}/attempted_sharing_agreements
y fija request_status
en IN_PROGRESS
y requesting_business_id
en el identificador del administrador comercial del usuario. Necesitas los permisos business_creative_management
y business_management
para esta acción.
Listar todos los acuerdos para compartir de carpetas pendientes
Solicitud
curl -i -X GET \ https://graph.facebook.com/<API_VERSION>/<PARTNER_BUSINESS_ID>/attempted_sharing_agreements ?request_status=IN_PROGRESS &requesting_business_id=<user_business_id> &access_token={partner-access-token}
Listar todos los acuerdos para compartir de carpetas pendientes con el identificador de solicitud
De forma alternativa, si dispones del identificador de solicitud, puedes obtener el estado directamente enviando una solicitud a {request_id}
.
business_creative_management
Solicitud
curl -i -X GET \ https://graph.facebook.com/<API_VERSION>/<REQUEST_ID>?fields=status
Cuando el administrador de un negocio aprueba la solicitud, el estado cambia a APPROVE
, y la carpeta se comparte con tu administrador comercial si se estableció una relación de acuerdo de uso compartido entre el negocio del usuario y el tuyo (el negocio del usuario compartió una carpeta contigo, y tú aceptaste con anterioridad una solicitud para compartir). De lo contrario, el share_status
se actualiza a IN_PROGRESS
. Puedes listar todos los acuerdos de colaboración con estado IN_PROGRESS
y aceptarlos a través de la API o en la UI del administrador comercial.
Cuando el usuario comparte una carpeta contigo con permiso para la tarea VIEW_INSIGHTS
, puedes leer estadísticas de imágenes y videos de negocios en la carpeta compartida realizando una solicitud GET
en el punto de conexión <business_asset_id>/insights
.
business_creative_management
y business_creative_insights
.Solicitud
curl -i -X GET \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ASSET_ID>/insights ?breakdowns=["age","gender"] &fields=impressions,inline_link_clicks,age,gender,date_start, &time_range={"since":"2019-08-01","until":"2019-08-22"} &access_token={partner-access-token}"
Respuesta
{ "data": [ { "impressions": 99, "inline_link_clicks": 1, "age": "18-24", "gender": "female", "date_start": "2019-08-01", "date_end": "2019-08-22" }, { "impressions": 198, "inline_link_clicks": 2, "age": "18-24", "gender": "male", "date_start": "2019-08-01", "date_end": "2019-08-22" }, { "impressions": 464, "inline_link_clicks": 2, "age": "25-34", "gender": "female", "date_start": "2019-08-01", "date_end": "2019-08-22" }, ] }
El desglose se puede realizar con las siguientes categorías:
gender
age
country
publisher_platform
platform_position
device_platform
ad_id
objective
optimization_goal
time_range
(requiere una fecha en el formato “AAAA-MM-DD”, que significa a partir de la medianoche en la que se inicia ese día).Para socios de servicios administrados, puedes administrar la carpeta de nivel superior con un token de acceso de socio si la carpeta se compartió contigo con las tareas permitidas adecuadas que te otorguen lo siguiente:
CREATE_CONTENT
en la carpeta, con el que tu app pueda crear subcarpetas, y subir imágenes y videos a la carpeta.VIEW_INSIGHTS
, que tu app puede usar para ver estadísticas de rendimiento de cualquier recurso de contenido almacenado en esta carpeta.Llama al punto de conexión <business_id>/creative_folders
para obtener todas las carpetas superiores que se compartan contigo en el negocio del usuario.
business_creative_management
Obtener carpetas del negocio del usuario
Solicitud
curl -X GET \ -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<partner_business_id>/creative_folders?filtering=[{field:"owner_business_id", operator:"EQUAL", value:"user_business_id"}]
Respuesta
{ "data": [ { "id": "<shared_folder_id>" } ] }
Acceder a tareas permitidas que tengas en la carpeta
Solicitud
curl -X GET \ -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<folder_id>/agencies
Respuesta
{ "data": [ { "id": "<partner_business_id>", "name": "<partner business name>", "permitted_tasks": [ "VIEW_INSIGHTS", "VIEW_CONTENT", "CREATE_CONTENT", "MANAGE_CONTENT", "MANAGE_PERMISSIONS"] } ], }
CREATE_CONTENT
para subir imágenes y videos a una carpeta compartida.VIEW_INSIGHTS
para consultar estadísticas de contenido de imágenes o videos en una carpeta compartida.Con el permiso de tarea CREATE_CONTENT
en la carpeta principal, puedes crear una subcarpeta en una carpeta compartida.
business_creative_management
Crear una subcarpeta
Solicitud
curl -X POST \ -F "name={folder_name}" -F "description={description}" -F "parent_folder_id={parent-folder-id}" -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<BUSINESS_ID>/creative_folders
Respuesta
{ "id": {subfolder-id} }
Sigue los mismos pasos indicados en el paso 5. Subir imágenes y videos a la subcarpeta con el token de socio.
Cuando tu app suba una imagen o un video a la biblioteca de recursos de Facebook, la API de Facebook devolverá un identificador para ese recurso.
Para facilitar la continuidad, tu app deberá hacer un seguimiento del identificador del recurso respecto del proyecto o espacio de trabajo del que surgió la imagen o el video en tu app.
Esto hará que sean posibles casos de uso de “edición” y “actualización” optimizados, que se admitirán en el futuro. Un ejemplo:
media_library_url
del recurso de imagen o video subidoSolicitud
curl -X GET \ -F 'access_token={partner-access-token}' \ https://graph.facebook.com/<API_VERSION>/<asset_id>?fields=media_library_url
&action=CREATE_AD
o &action=CREATE_POST
al final del enlace profundo del paso anterior.Ejemplo:
https://business.facebook.com/asset_library/business_creatives/?object_id=2838437832929622&action=CREATE_AD