Instalar aplicaciones y generar, actualizar y revocar identificadores

Como un usuario del sistema representa llamadas a un servidor, no tiene el inicio de sesión con Facebook y no puede instalar una aplicación ni someterse al proceso estándar de OAuth de Facebook para generar un identificador. Para ello, tienes que utilizar llamadas a la API.

Tipos de identificadores de acceso del sistema

Tipos	Identificadores de acceso sin caducidad	Sugerencias de identificadores de acceso con caducidad
Duración	Nunca caducan	Válidos durante 60 días
¿Es necesario actualizarlos?	No	Sí
Recomendación en función de los casos de uso	Puedes tolerar el riesgo de los identificadores de acceso filtrados y quieres que las aplicaciones de terceros tengan acceso fuera de internet a los datos.	Quieres limitar el riesgo de los identificadores de acceso filtrados.

Instalar aplicaciones

Un usuario del sistema o un usuario administrador del sistema debe instalar la aplicación con la que se generará un identificador de acceso. Esto significa permitir a la aplicación realizar llamadas a las API en nombre de dichos usuarios.

El usuario del sistema y la aplicación deben pertenecer a la misma cuenta de Business Manager. Solo pueden instalarse aplicaciones con acceso estándar (o uno superior) a la API de administración de anuncios.

A fin de instalar una aplicación para un usuario del sistema, necesitas lo siguiente:

access_token: valor de un usuario administrador, usuario administrador del sistema u otro usuario del sistema.
business_app: identificador de la aplicación que se va a instalar.

A fin de instalar una aplicación para un usuario del sistema, realiza una solicitud POST:

curl \
-F "business_app=APP-ID" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/applications"

Esta llamada devuelve un resultado booleano si la instalación se realiza correctamente. Si no se cumple alguna de las restricciones, verás el mensaje de error pertinente.

Generar un identificador de acceso

Una vez que el usuario del sistema haya instalado la aplicación, puede generar un identificador de acceso persistente. Sin embargo, se aplican algunas restricciones:

El usuario del sistema debe haber instalado la aplicación pasada en el parámetro, tal y como se muestra en el paso anterior.
Las aplicaciones solo pueden dirigirse a las empresas que las hayan reclamado (o a sus empresas secundarias).
El usuario del sistema y el propietario del identificador de acceso que se utiliza durante la llamada a la API de generación del identificador deben pertenecer a la misma cuenta de Business Manager.
La aplicación puede pertenecer a la misma cuenta de Business Manager o no. En caso negativo, se aplican ciertas restricciones. Consulta la sección siguiente.

A continuación, se enumeran los parámetros para la llamada a la API:

business_app: aplicación propiedad de Business Manager a la que pertenece el usuario del sistema.
appsecret_proof: campo calculado para la aplicación. Es obligatorio para garantizar que el servidor adecuado realice la llamada a la API. Para obtener más información, consulta Seguridad del inicio de sesión.
scope: cadena separada por comas que contiene permisos ampliados.
access_token: identificador que pertenece al administrador de Business Manager, al usuario administrador del sistema o al usuario del sistema regular.
set_token_expires_in_60_days: establece el valor como true para generar un identificador de acceso de usuario del sistema con caducidad. Recomendado. Los identificadores con caducidad son una práctica recomendada de seguridad. Algunas empresas deben usar identificadores con caducidad. Si este requisito se aplica a tu empresa, se producirá un error si omites este parámetro o lo estableces en un valor false. Todas las integraciones deben adoptar identificadores con caducidad para ajustarse a las normas de seguridad cambiantes de la plataforma.

Ámbitos compatibles con los usuarios del sistema:

ads_management
ads_read
attribution_read
business_management
catalog_management
commerce_account_manage_orders
commerce_account_read_orders
commerce_account_read_settings
instagram_basic
instagram_branded_content_ads_brand
instagram_branded_content_brand
instagram_content_publish
instagram_manage_comments
instagram_manage_insights
instagram_manage_messages
instagram_shopping_tag_products
leads_retrieval
page_events
pages_manage_ads
pages_manage_cta
pages_manage_engagement
pages_manage_instant_articles
pages_manage_metadata
pages_manage_posts
pages_messaging
pages_read_engagement
pages_read_user_content
pages_show_list
private_computation_access
publish_video
read_audience_network_insights
read_insights
read_page_mailboxes
whatsapp_business_management
whatsapp_business_messaging

Permiso obsoleto, solo visible para las aplicaciones creadas antes del 24 de abril de 2018

publish_actions

Permisos acotados por función

Función	Permiso
business_creative_asset_management	`business_creative_managementbusiness_creative_insights` `business_creative_insights_sharebusiness_data_management`
commerce_public_api_beta_testing	`commerce_manage_accountscommerce_account_read_reports`

Para generar un valor de appsecret_proof, puedes usar el código PHP:

$appsecret_proof = hash_hmac(
  'sha256',
  $access_token_used_in_the_call,
  $app_secret_for_the_app_used_in_the_call,
);

En el código de ejemplo anterior, app_secret_for_the_app_used_in_the_call hace referencia a la clave secreta de la aplicación que se usó para generar el identificador de acceso. Puedes consultar la clave secreta de la aplicación en el panel de aplicaciones.

El valor de appsecret_proof cifrado con hash debe ser una cadena como "1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3".

Para generar un identificador de acceso de usuario del sistema permanente, realiza una solicitud POST:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,pages_read_engagement,pages_show_list" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

Para generar un identificador de acceso de usuario del sistema con caducidad, realiza una solicitud POST:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,pages_read_engagement,pages_show_list" \
-F "set_token_expires_in_60_days=true" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

Anteriormente, el nombre del extremo era /SYSTEM-USER-ID/ads_access_token. Las llamadas a dicho nombre han dejado de funcionar.

La respuesta devuelve la cadena del identificador de acceso. Si no se cumple alguna de las restricciones, se devuelven los códigos de error pertinentes. La respuesta:

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

También puedes generar un identificador de acceso de usuario del sistema mediante la interfaz de usuario de Business Manager.

Actualizar un identificador de acceso

Un identificador de usuario del sistema con caducidad tiene una validez de 60 días desde que se generó o actualizó. Para crear continuidad, el desarrollador debe actualizar el identificador de acceso en un plazo de 60 días; en caso contrario, el identificador de acceso se perderá y el desarrollador tendrá que obtener uno nuevo para volver a obtener acceso a la API.

Para actualizar un identificador de acceso de usuario del sistema con caducidad, necesitas lo siguiente:

fb_exchange_token: identificador de acceso de usuario del sistema válido.
client_id: identificador de la aplicación.
client_secret: clave secreta de la aplicación.
set_token_expires_in_60_days: establece el valor como “true” para actualizar un identificador de acceso de usuario del sistema con caducidad.

Consulta el extremo GET oauth/access_token.

Ejemplo de solicitud

curl -i -X GET 
"https://graph.facebook.com/{graph-api-version}/oauth/access_token?  
    grant_type=fb_exchange_token&          
    client_id={app-id}&
    client_secret={app-secret}&
    set_token_expires_in_60_days=true&
    fb_exchange_token={your-access-token}"

Ejemplo de respuesta

{
  "access_token":"{expiring-system-user-access-token}",
  "token_type": "bearer",
  "expires_in": 5183944    // Time left in seconds until the token expires
}

Revocar un identificador de acceso

Este extremo está pensado para realizar una rotación regular de identificadores o revocar identificadores de acceso para usuarios del sistema comprometidos con el fin de proteger el sistema.

Para revocar un identificador de acceso de usuario del sistema, necesitas lo siguiente:

revoke_token: identificador de acceso que se va a revocar.
client_id: identificador de la aplicación.
client_secret: clave secreta de la aplicación.
access_token: identificador de acceso para identificar al participante.

Los requisitos son los siguientes:

Client_id debe corresponder a la aplicación real y garantizar que la aplicación no está limitada, desactivada ni eliminada.
Client_id, así como la aplicación instalada de revoke_token, la de access_token y el client_secret deben ser iguales.

Consulta el extremo GET oauth/revoke.

Ejemplo de solicitud

curl -i -X GET "https://graph.facebook.com/{graph-api-version}/oauth/revoke?   
    client_id={app-id}&
    client_secret={app-secret}&
    revoke_token={system-user-access-token-to-revoke}&
    access_token={your-access-token}"

Ejemplo de respuesta

{
  "success":"true",
}

Rotación del identificador de acceso

La rotación de identificadores es una medida de seguridad que puede ayudar a mitigar riesgos, por ejemplo, al limitar el daño de los identificadores filtrados. Al cambiar regularmente los identificadores de acceso, se puede limitar el daño potencial causado por un identificador filtrado o extraviado, como al cambiar las contraseñas. Actualmente, nuestro sistema admite la rotación de usuarios del sistema sin tiempo de inactividad. Para hacerlo, sigue estas instrucciones:

Actualiza el identificador de acceso de usuario del sistema con la API de actualización, que devolverá un nuevo identificador de acceso de usuario del sistema que será válido durante los 60 días posteriores a su actualización. El identificador de acceso antiguo seguirá funcionando hasta que caduque (es decir, fecha de creación + 60).
Implementa el nuevo identificador de acceso de usuario del sistema.
Revoca el identificador de acceso de usuario del sistema antiguo mediante la API de revocación. La invalidación se realiza de manera inmediata y el identificador no puede volver a usarse tras la revocación.