Business Management APIs

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 querer 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
  • 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 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. La 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:

  1. 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).

  2. Implementa el nuevo token de acceso de usuario del sistema.

  3. 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.