Instalar apps, generar tokens, actualizarlos y anularlos

Dado que un usuario del sistema representa llamadas al servidor, no tiene inicio de sesión con Facebook y no puede instalar una app o pasar por el proceso estándar de OAuth de Facebook para generar un token. Esto se debe hacer a través de llamadas a la API.

Tipos de tokens de acceso al sistema

Tipos	Tokens de acceso sin vencimiento	Tokens de acceso con vencimiento sugeridos
Total	Nunca vence	Válido por 60 días
¿Necesitas una actualización?	No	Sí
Recomendaciones basadas en casos de uso	Puedes tolerar el riesgo de filtración de tokens de acceso y quieres que tus apps de terceros tengan acceso sin conexión a los datos.	Quieres limitar el riesgo de filtración de tokens de acceso.

Instalar apps

Un usuario del sistema o un usuario administrador del sistema debe instalar la aplicación que se utilizará para generar un token de acceso. Esto significa permitir que la aplicación llame a las API en nombre de este usuario del sistema o usuario administrador de sistema.

Tanto el usuario del sistema como la aplicación deben pertenecer a un mismo administrador comercial. Solo se pueden instalar aplicaciones con acceso estándar a la API de administración de anuncios y superior.

Para instalar una aplicación para un usuario del sistema, se necesita:

access_token: de un usuario administrador, de un usuario administrador del sistema, o de otro usuario del sistema
business_app: el identificador de la aplicación que se está instalando

Si quieres instalar una app para usuarios del sistema, haz una solicitud POST:

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

Si la instalación se realiza correctamente, esta llamada devuelve un resultado booleano. Si no se cumple alguna de las restricciones, aparecerá el mensaje de error correspondiente.

Generar el token de acceso

Después de que el usuario del sistema instala la app, puede generar un token de acceso persistente. Se aplican las siguientes restricciones:

El usuario del sistema debe haber instalado la app pasada en el parámetro, como se vio en el paso anterior.
Las apps solo pueden orientarse a negocios (o negocios secundarios de estos) que las hayan reclamado.
El usuario del sistema y el propietario del token de acceso que se utilice durante esta llamada a la API de generación de tokens deben pertenecer al mismo administrador comercial.
La aplicación puede ser o no ser propiedad del mismo administrador comercial. Si no lo es, se aplican algunas restricciones. Consulta la siguiente sección.

Estos son los parámetros para la llamada a la API:

business_app: la app que es propiedad del administrador comercial al que pertenece el usuario del sistema.
appsecret_proof: campo calculado para la app. Esto es obligatorio para garantizar que el servidor correcto está haciendo la llamada a la API. Para más detalles, revisa la seguridad de acceso.
scope: cadena separada por comas con permisos extendidos.
access_token: es un token que pertenece al administrador comercial, al usuario administrador del sistema o al usuario regular del sistema.
set_token_expires_in_60_days: configúralo en verdadero para generar un token de acceso de usuario del sistema con vencimiento. Opcional.

Ámbitos compatibles para 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 apps creadas antes del 24 de abril de 2018

publish_actions

Permisos limitados por capacidades

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 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 ejemplo de código anterior, app_secret_for_the_app_used_in_the_call se refiere a la clave secreta de la app que se utiliza para generar el token de acceso. La clave secreta de la app se encuentra en el panel de apps.

La appsecret_proof cifrada deberá ser una cadena similar a "1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3".

Para generar un token de acceso del usuario del sistema permanente, haz 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 token de acceso del usuario del sistema con vencimiento, haz 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"

El punto de conexión se llamaba originalmente /SYSTEM-USER-ID/ads_access_token. La llamada a ese nombre ya no funciona.

La respuesta devuelve la cadena del token de acceso. Si no se cumplen algunas de las restricciones, se producen los códigos de error correspondientes. Respuesta:

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

También puedes generar un token de acceso de usuario del sistema con la UI del administrador comercial.

Actualizar el token de acceso

Un token de usuario del sistema con vencimiento es válido por 60 días a partir de que se genera o actualiza. Para crear continuidad, el desarrollador debería actualizar el token de acceso en un plazo de 60 días. De lo contrario, el token de acceso podría perderse y el desarrollador deberá obtener uno nuevo para volver a tener acceso a la API.

Para actualizar un token de acceso de usuario del sistema, necesitas lo siguiente:

fb_exchange_token: un token de acceso de usuario del sistema válido
client_id: el identificador de la app
client_secret: la clave secreta de la app
set_token_expires_in_60_days: configurado en verdadero para actualizar un token de acceso de usuario del sistema con vencimiento.

Consulta el punto de conexión 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
}

Anular el token de acceso

Este punto de conexión tiene como objetivo realizar una rotación regular del token o anular los tokens de acceso de sistemas de usuario comprometidos como medio para proteger tu sistema.

Para anular un token de acceso de usuario del sistema, necesitas lo siguiente:

revoke_token: el token de acceso que se va a anular
client_id: el identificador de la app
client_secret: la clave secreta de la app
access_token: el token de acceso para identificar a la persona que llama

Los requisitos son los siguientes:

El client_id debe corresponder a la app real y debes asegurarte de que la app no esté limitada, inhabilitada o eliminada.
El client_id, junto con la app instalada de revoke_token, la app instalada de access_token y client_secret, deben ser iguales.

Consulta el punto de conexión 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 token de acceso

La rotación del token es una medida de seguridad que puede ayudar a mitigar riesgos. Por ejemplo, mediante la limitación del daño de tokens filtrados. Al cambiar tokens de seguridad de manera periódica, se puede limitar el daño potencial que causaría la filtración o el extravío de un token, algo similar a lo que ocurre con 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 token de acceso de usuario del sistema mediante la API de actualización de token de acceso de usuario del sistema. La API de actualización de token de acceso de usuario del sistema devolverá un nuevo token de acceso de usuario del sistema y el nuevo token será válido por 60 días a partir de la fecha en la que se actualizó. El token anterior podrá seguir funcionando hasta que caduque (60 días después de su fecha de creación).
Implementa el nuevo token de acceso de usuario del sistema.
Anula el token de acceso de usuario del sistema anterior con la API de anulación del token de acceso de usuario del sistema. La anulación se produce de inmediato. El token no podrá volver a usarse.