Descargar 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 descargar 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.

Descargar aplicaciones

Un usuario del sistema o un usuario administrador del sistema debe descargar 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 descargarse aplicaciones con acceso estándar (o uno superior) a la API de administración de anuncios.

A fin de descargar 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 descargar.

A fin de descargar 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 descarga 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 descargado 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 habitual.
set_token_expires_in_60_days: establece el valor como “true” para generar un identificador de acceso de usuario del sistema con caducidad. Opcional.

Ámbitos compatibles con los usuarios del sistema:

ads_management
ads_read
business_management
catalog_management
instagram_basic
instagram_content_publish
instagram_manage_comments
instagram_manage_insights
instagram_manage_messages
leads_retrieval
manage_notifications
pages_manage_cta
pages_read_engagement
pages_manage_ads
pages_manage_engagement
pages_manage_posts
pages_messaging
pages_show_list
pages_read_user_content
pages_manage_metadata
page_events
publish_video
read_audience_network_insights
read_insights
read_page_mailboxes
rsvp_event
whatsapp_business_management
whatsapp_business_messaging

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,manage_pages" \
-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,manage_pages" \
-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 mediante la API de actualización de SUAT. La API de actualización de SUAT 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 antiguo seguirá funcionando hasta que caduque (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 de SUAT. La invalidación se realiza de manera inmediata y el identificador no puede volver a usarse tras la revocación.