API de marketing

Control de versiones

La versión actual de la API de marketing es v20.0.

La plataforma de Facebook posee un modelo de control de versiones central y extendido. Con el control de versiones de la API de marketing, todos los cambios radicales se incluirán en una nueva versión. Simultáneamente, puede haber varias versiones de las API o los SDK de marketing, con funciones diferentes en cada versión.

Los desarrolladores deben saber de antemano si una API o un SDK de marketing van a cambiar. Aunque cuentas con un intervalo de 90 días para adoptar los cambios, tú eliges cómo y cuándo cambiar a la nueva versión.

Calendarios de las versiones

Cuando se lanza una nueva versión de la API de marketing, la versión anterior se admite durante al menos 90 días más. De esta forma, tienes un mínimo de 90 días de gracia para cambiar a la nueva versión. Durante el período de gracia de 90 días, puedes llamar a la versión actual o a la versión obsoleta de la API, y dispones de ese tiempo para pasar a la nueva versión. Una vez transcurrido el período de gracia de 90 días, la versión obsoleta dejará de funcionar. Cuando una versión deja de estar disponible, cualquier llamada realizada a ese número de versión puede generar error, o bien se actualiza a la siguiente versión disponible.

Por ejemplo, la versión 17.0 de la API de marketing se lanzó el 23 de mayo de 2023 y la versión 16.0 caducó el 6 de febrero de 2024, lo que proporcionó al menos 90 días para migrar a la nueva versión.

Este es un ejemplo de línea de tiempo. Ten en cuenta que no siempre lanzamos una nueva versión cuando finaliza el período de gracia de 90 días de la versión anterior. En el ejemplo, la versión 16.0 quedó obsoleta poco tiempo antes de que se lanzara la versión 18.0:

Para los SDK, siempre hay una versión disponible, ya que se trata de paquetes que se descargan. Sin embargo, más allá de su fecha de caducidad, es posible que dependan de API de marketing obsoletas o de métodos que ya no funcionan, por lo que, como puedes suponer, los SDK que caducaron dejan de ser funcionales.

Realizar solicitudes con versión

Todos los puntos de conexión de la API de marketing están disponibles a través de rutas con versiones. Agrega el identificador de la versión al inicio de la ruta de solicitud. Por ejemplo:

curl -G \
-d "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v20.0/me/adaccounts"

En este formato general, funciona para todas las versiones:

https://graph.facebook.com/v{n}/{request-path}

Donde n es la versión necesaria. Podrás ver una lista completa de versiones disponibles en nuestro registro de cambios. En toda la referencia de la API de marketing, se proporciona información de cada versión.

Migraciones

Las migraciones son solo para escenarios especiales en los que es necesario realizar cambios que no pueden incluirse en el control de versiones. En general, esto ocurre cuando el modelo de datos subyacente se modifica. Las migraciones se aplican en todas las versiones.

En nuestra página de migraciones, encontrarás la lista de las migraciones que se encuentran actualmente en curso. Las migraciones cuentan con un intervalo mínimo de 90 días durante el cual se debe realizar la migración de la app. Al iniciarse un nuevo intervalo, el comportamiento tras la migración será el predeterminado para las nuevas apps. Luego, cuando el intervalo de migración se complete, el comportamiento previo a la migración dejará de estar disponible.

Administración de migraciones mediante la API Graph

Las migraciones se pueden administrar desde el campo de migraciones en el nodo /app:

Puedes hacer una llamada de actualización al perímetro para activar y desactivar las migraciones.

Administración de migraciones mediante el panel de apps

Puedes activar y desactivar las migraciones disponibles en el panel de apps, en Configuración > Migraciones. Ten en cuenta que la lista de las migraciones puede ser diferente de la que aparece en la imagen siguiente, ya que las migraciones disponibles varían en función de las apps y del momento. Si ves una migración Use Graph API v2.0 by default, corresponde solamente a la API Graph, no a la API de marketing.

Activación temporal de las migraciones del lado del cliente

En lugar de activar una migración en el panel de apps o mediante la API de marketing, puedes agregar una marca especial a tus llamadas a la API de marketing que configure la migración. Esta marca se denomina migrations_override y requiere que se especifique un blob JSON que describa qué migraciones se desean activar o desactivar. Por ejemplo, si deseas hacer una llamada directa, puedes pasar:

http://graph.facebook.com/path?
  migrations_override={"migration1":true, "migration2":false}

De este modo, puedes llamar a la nueva API de marketing mediante actualizaciones del cliente, en lugar de hacer que todos los emisores de llamadas realicen la actualización para llamar a la nueva API de marketing al mismo tiempo. También te resultará muy útil para efectos de depuración.

Los nombres de estas migraciones se detallan en el nodo /app mencionado anteriormente.

Actualización automática de la versión

Debido a la rápida rotación de las versiones de la API de marketing, que se realiza cada aproximadamente cuatro meses, vamos a simplificar el proceso de actualización. A partir de mayo de 2024, activaremos la función de actualización automática de la versión en los puntos de conexión de la API de marketing que no se ven afectados entre versiones. Esto significa que entre una versión que va a quedar obsoleta y la siguiente versión disponible, si un punto de conexión no se ve afectado, la plataforma actualizará la llamada a la siguiente versión disponible, en lugar de rechazar directamente la solicitud. Este cambio se diseñó para garantizar una experiencia más fluida y eficiente de la API.

Por ejemplo, el 14 de mayo de 2024, quedará obsoleta la versión 17.0. Según el registro de cambios de la versión 18.0, se verán afectados los siguientes puntos de conexión:

  • POST /act_{ad-account-id}/reachfrequencypredictions
  • GET /act_{ad-account-id}/reachestimate
  • GET /act_{ad-account-id}/delivery_estimate
  • POST /act_{ad-account-id}/adsets
  • POST /{adset-id}
  • POST /act_{ad-account-id}/saved_audiences
  • POST /{saved-audience-id}
  • POST /act_{ad-account-id}/credit_cards

Si tu app hace una llamada a POST /{adset-id} con la versión 17.0 después de que quedó obsoleta, el 14 de mayo de 2024, esta solicitud de la API no se procesará correctamente, ya que la actualización automática no se aplica a los puntos de conexión afectados por la siguiente versión disponible (versión 18.0).

Si tu app hace una llamada a GET /{ad-account-id}/insights con la versión 17.0 después de que quedó obsoleta, la plataforma actualizará tu llamada a la siguiente versión disponible (versión 18.0).

Nota: Si tu app ya está realizando llamadas con versiones posteriores a la 17.0, no debería haber ningún cambio respecto de la fecha en que queda obsoleta la versión.

Para comprobar los puntos de conexión afectados en cada versión, consulta el registro de cambios de la API de marketing.

Preguntas frecuentes

Calendarios de las versiones

We refer to this as an unversioned call. Unversioned calls are invalid and will fail when made against Marketing API endpoints.

Enlace permanente

You can call the version of the Marketing API that was the latest available when the app was created, as long as it has not been deprecated. It can also make calls to any newer, undeprecated versions launched after the app is created.

Starting May 14, 2024, if a deprecated version is provided, the platform may upgrade selected endpoints to the next available version instead of failing the request. To learn more about the behavior, refer to Marketing API Auto-version upgrade.

For example:

  • If your app was created before the launch of v17.0, while v16.0 was available, then it will be able to make calls to v16.0 until the expiration date of that version. After v16.0 has been deprecated, calls to v16.0 will fail.
  • If your app was created after v17.0 was released, it will be able to make calls to v17.0 until the expiration date of that version, and any subsequent versions (v18.0, etc) until their expiration dates. After v17.0 has been deprecated, calls to v17.0 will fail.
  • Your app will not be able to make calls to v16.0, since 1) that was before your app was created and 2) that version is deprecated and calls to v16.0 may fail or be upgraded to the next available version.

If an app was not used - to make any Marketing API calls or requests - after being created, it will not have the ability to use those versions if any newer version is launched. Here's another example to explain this:

  • If your app was created while v16.0 was the latest version available, but not used until after v17.0 had launched, it will only be to use v17.0, and not v16.0.
  • If your app was created while v16.0 was the latest version available, and then used before v17.0 had launched, it will still be able to use v16.0 even after the launch of v17.0.
Enlace permanente

There are a few differences between how Marketing API and the rest of Graph API. For the details on Platform API versioning, see Graph API, Versioning.

  1. Marketing API is versioned on a 90-day deprecation schedule, whereas Platform API has core and extended APIs with a 2 year guarantee for core APIs.
  2. Marketing API does not support unversioned calls. If you do not specify a working version in your call, it fails.
Enlace permanente

Realizar solicitudes con versión

With migrations, you set migration on or off in App Dashboard, as described in the Migrations section. With versioning, we are making Marketing API functionality more transparent by moving the setting into the endpoint:

https://graph.facebook.com/v{n}/{request-path}

You can know what behavior to expect out without having to manually visit your app's migration panel.

Enlace permanente

Actualización automática de la versión

The upgrade will apply on any deprecated version to the next available version. This means hypothetically if your app is making calls to v15.0 after v16.0 is deprecated, the call will also be upgraded to v17.0 if the endpoint is not listed as affected endpoint on both v16.0 and v17.0.

Enlace permanente

No. We highly encourage developers to perform version upgrades before a version gets deprecated for the following reasons

  • You may still need to manually upgrade endpoints being impacted by next version.
  • You might want to upgrade to newer versions to benefit from new features instead of the lowest available version.
Enlace permanente

You can look up affected endpoints from Marketing API Changelog.

Enlace permanente

You can disable the version auto-upgrade via the Marketing API Version setting under Marketing API App Product Page > Settings.

Enlace permanente

If an API call targets a version that has been deprecated and has been automatically upgraded, an API response header is included for any call that has been auto-upgraded.

Example notification header

X-Ad-Api-Version-Warning: 'X-Ad-Api-Version-Warning: 'The call has been auto-upgraded to vXXX as vXXX has been deprecated''
Enlace permanente