API de marketing

Recuperación de clientes potenciales

Puedes consultar los datos de los clientes potenciales con Webhooks o la lectura masiva.

Antes de empezar

Para leer campos específicos de anuncios, como ad_id o campaign_id, necesitarás lo siguiente:

Para leer todos los datos de los clientes potenciales y los anuncios, necesitarás lo siguiente:

Nota: Si este administrador de páginas nunca ha personalizado los clientes potenciales ni ha concedido ningún permiso de acceso mediante el administrador de acceso a la información de clientes potenciales, TODOS los administradores de la página tendrán el permiso de acceso a la información de clientes potenciales. Si los administradores del negocio personalizan el permiso de acceso a la información sobre clientes potenciales, dependerá de la configuración de dichos administradores si un administrador de nivel básico de la página tiene permiso de acceso a esta información o no.

Límites de frecuencia

El límite de frecuencia es 200 multiplicado por 24 y por el número de clientes potenciales creados en los últimos 90 días para una página de Facebook. Si superas este número de llamadas en un periodo de 24 horas, la solicitud devuelve un error.

Filtración por intervalo de fechas

Envía una solicitud GET al extremo /ads/lead_gen/export_csv/ en la que los formatos de fecha sean las marcas de tiempo POSIX o UNIX:

curl -i -X GET "https://www.facebook.com/ads/lead_gen/export_csv/
    ?id=<FORM_ID>
    &type=form
    &from_date=1482698431
    &to_date=1482784831"

Advertencias

  • Si from_date no se establece o es anterior a la hora de creación del formulario, se usará la hora de creación de este.

  • Si to_date no se establece o es posterior a la hora actual, se utilizará la hora actual.

  • Si alguna entrada no incluye el identificador del anuncio o del grupo de anuncios en el archivo TSV, puede deberse a los siguientes motivos:

    • El cliente potencial se genera a partir del alcance orgánico. En este caso, el parámetro is_organic del archivo TSV es 1; de lo contrario, el valor es 0.
    • El cliente potencial se puede enviar desde una vista previa del anuncio.
    • La persona que solicita los clientes potenciales no tiene privilegios de anunciante en la cuenta publicitaria.

Webhooks

Obtén actualizaciones en tiempo real de los anuncios para clientes potenciales.

Paso 1: primeros pasos

Visita nuestra guía de introducción a Webhooks para configurar el extremo y el webhook.

Paso 2: obtención de un identificador de acceso a la página de larga duración

Genera un solo identificador de acceso a la página de larga duración a fin de recuperar datos de manera continua sin tener que preocuparte por si caducan.

Paso 3: instalación de la aplicación en la página

Visita nuestra guía de Webhooks para páginas para obtener información sobre cómo instalar una aplicación en una página.

Respuesta del webhook

Al crear un cliente potencial, la aplicación recibe la respuesta del webhook siguiente:

array(
  "object" => "page",
  "entry" => array(
    "0" => array(
      "id" => 153125381133,
      "time" => 1438292065,
      "changes" => array(
        "0" => array(
          "field" => "leadgen",
          "value" => array(
            "leadgen_id" => 123123123123,
            "page_id" => 123123123,
            "form_id" => 12312312312,
            "adgroup_id" => 12312312312,
            "ad_id" => 12312312312,
            "created_time" => 1440120384
          )
        ),
        "1" => array(
          "field" => "leadgen",
          "value" => array(
            "leadgen_id" => 123123123124,
            "page_id" => 123123123,
            "form_id" => 12312312312,
            "adgroup_id" => 12312312312,
            "ad_id" => 12312312312,
            "created_time" => 1440120384
          )
        )
      )
    )
  )
)

Puedes utilizar leadgen_id para recuperar los datos asociados al cliente potencial:

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/{lead-id}/
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<LEAD_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
};
const sample_code = (new Lead(id)).get(
  fields,
  params
);
logApiCallResult('sample_code api call complete.', sample_code);
Open In Graph API Explorer
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Lead;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<LEAD_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
);
echo json_encode((new Lead($id))->getSelf(
  $fields,
  $params
)->exportAllData(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<LEAD_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
}
print Lead(id).get(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<LEAD_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Lead(id, context).get()
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<LEAD_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

lead = FacebookAds::Lead.get(id ,'')
Open In Graph API Explorer

Cuando esta operación se completa correctamente, la aplicación recibe la respuesta siguiente:

{
  "created_time": "2015-02-28T08:49:14+0000", 
  "id": "<LEAD_ID>", 
  "ad_id": "<AD_ID>",
  "form_id": "<FORM_ID>",
  "field_data": [{
    "name": "car_make",
    "values": [
      "Honda"
    ]
  }, 
  {
    "name": "full_name", 
    "values": [
      "Joe Example"
    ]
  }, 
  {
    "name": "email", 
    "values": [
      "joe@example.com"
    ]
  },
  {
    "name": "selected_dealer", 
    "values": [
      "99213450"
    ]
  }],
  ...
}

Más información

Puedes ver un ejemplo de esta implementación en nuestro repositorio de GitHub.

Lectura masiva

Las aplicaciones creadas a partir del 2 de julio de 2018 deben usar el permiso leads_retrieval para consultar datos de los clientes potenciales.

El parámetro leads existe tanto en el grupo de anuncios como en los nodos del formulario. Este devuelve todos los datos asociados con sus respectivos objetos. Dado que un formulario puede reutilizarse para muchos anuncios, este puede contener muchos más clientes potenciales que un anuncio que lo utilice.

Para realizar una lectura masiva por anuncio:

curl -X GET \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/{adgroup-id}/leads
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_GROUP_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
};
const leadss = (new Ad(id)).getLeads(
  fields,
  params
);
logApiCallResult('leadss api call complete.', leadss);
Open In Graph API Explorer
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Object\Lead;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_GROUP_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
);
echo json_encode((new Ad($id))->getLeads(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.ad import Ad
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
}
print Ad(id).get_leads(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_GROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).getLeads()
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad = FacebookAds::Ad.get(id)
leadss = ad.leads({
    fields: {  },
})
Open In Graph API Explorer

Para realizar una lectura por formulario:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'fields=created_time,id,ad_id,form_id,field_data' \
  https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads

La respuesta:

{
  "data": [
    {
      "created_time": "2018-02-28T08:49:14+0000", 
      "id": "<LEAD_ID>", 
      "ad_id": "<AD_ID>",
      "form_id": "<FORM_ID>",
      "field_data": [
        {
          "name": "car_make",
          "values": [
            "Honda"
          ]
        }, 
        {
          "name": "full_name", 
          "values": [
            "Joe Example"
          ]
        }, 
        {
          "name": "email", 
          "values": [
            "joe@example.com"
          ]
        },
      ], 
      ...
    }
  ],
  "paging": {
    "cursors": {
      "before": "OTc2Nz3M8MTgyMzU1NDMy", 
      "after": "OTcxNjcyOTg8ANTI4NzE4"
    }
  }
}

Lectura de un valor de pregunta de ubicación del negocio

La pregunta de ubicación del negocio no es diferente de cualquier otra. Una pregunta de ubicación del negocio también tiene un identificador de campo que se le asigna durante la creación del formulario. También se envía de manera parecida a las demás preguntas. El valor transmitido procede del número de tienda de la ubicación seleccionada.

Por ejemplo, supongamos que tienes una pregunta de ubicación del negocio con el identificador de campo selected_dealer. Para recuperar los clientes potenciales de forma masiva, puedes realizar la siguiente llamada:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  -d 'fields=created_time,id,ad_id,form_id,field_data' \
  https://graph.facebook.com/<API_VERSION>/<FORM_ID>/leads

La respuesta:

{
  "data": [
    {
      "created_time": "2018-02-28T08:49:14+0000", 
      "id": "<LEAD_ID>", 
      "ad_id": "<AD_ID>",
      "form_id": "<FORM_ID>",
      "field_data": [
        {
          "name": "car_make",
          "values": [
            "Honda"
          ]
        }, 
        {
          "name": "full_name", 
          "values": [
            "Joe Example"
          ]
        }, 
        {
          "name": "email", 
          "values": [
            "joe@example.com"
          ]
        },
        {
          "name": "selected_dealer", 
          "values": [
            "99213450"
          ]
        }
      ], 
      ...
    }
  ],
  "paging": {
    "cursors": {
      "before": "OTc2Nz3M8MTgyMzU1NDMy", 
      "after": "OTcxNjcyOTg8ANTI4NzE4"
    }
  }
}

Lectura de respuestas del descargo de responsabilidad personalizado

El valor field_data no contiene las respuestas a las casillas de descargo de responsabilidad personalizado opcionales que el usuario habría rellenado. Para recuperar las respuestas, utiliza el campo custom_disclaimer_responses.

curl -X GET \
"https://graph.facebook.com/<API_VERSION>/<LEADGEN_ID>?
fields=custom_disclaimer_responses"

Respuesta:

{
  "custom_disclaimer_responses": [
    {
      "checkbox_key": "optional_1",
      "is_checked": "1"
    },
    {
      "checkbox_key": "optional_2",
      "is_checked": ""
    }
  ],
  "id": "1231231231"
}

Filtrado de clientes potenciales

En este ejemplo, se filtran los clientes potenciales en función de las marcas de tiempo. Las marcas de tiempo deben ser UNIX.

curl -X GET \
  -d 'filtering=[
       {
         "field": "time_created",
         "operator": "GREATER_THAN",
         "value": 1731609415
       }
     ]' \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v21.0/{adgroup-id}/leads
Open In Graph API Explorer
'use strict';
const bizSdk = require('facebook-nodejs-business-sdk');
const Ad = bizSdk.Ad;
const Lead = bizSdk.Lead;

const access_token = '<ACCESS_TOKEN>';
const app_secret = '<APP_SECRET>';
const app_id = '<APP_ID>';
const id = '<AD_GROUP_ID>';
const api = bizSdk.FacebookAdsApi.init(access_token);
const showDebugingInfo = true; // Setting this to true shows more debugging info.
if (showDebugingInfo) {
  api.setDebug(true);
}

const logApiCallResult = (apiCallName, data) => {
  console.log(apiCallName);
  if (showDebugingInfo) {
    console.log('Data:' + JSON.stringify(data));
  }
};

let fields, params;
fields = [
];
params = {
  'filtering' : [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}],
};
const leadss = (new Ad(id)).getLeads(
  fields,
  params
);
logApiCallResult('leadss api call complete.', leadss);
Open In Graph API Explorer
require __DIR__ . '/vendor/autoload.php';

use FacebookAds\Object\Ad;
use FacebookAds\Object\Lead;
use FacebookAds\Api;
use FacebookAds\Logger\CurlLogger;

$access_token = '<ACCESS_TOKEN>';
$app_secret = '<APP_SECRET>';
$app_id = '<APP_ID>';
$id = '<AD_GROUP_ID>';

$api = Api::init($app_id, $app_secret, $access_token);
$api->setLogger(new CurlLogger());

$fields = array(
);
$params = array(
  'filtering' => array(array('field' => 'time_created','operator' => 'GREATER_THAN','value' => 1721709809)),
);
echo json_encode((new Ad($id))->getLeads(
  $fields,
  $params
)->getResponse()->getContent(), JSON_PRETTY_PRINT);
Open In Graph API Explorer
from facebook_business.adobjects.ad import Ad
from facebook_business.adobjects.lead import Lead
from facebook_business.api import FacebookAdsApi

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'
FacebookAdsApi.init(access_token=access_token)

fields = [
]
params = {
  'filtering': [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}],
}
print Ad(id).get_leads(
  fields=fields,
  params=params,
)
Open In Graph API Explorer
import com.facebook.ads.sdk.*;
import java.io.File;
import java.util.Arrays;

public class SAMPLE_CODE_EXAMPLE {
  public static void main (String args[]) throws APIException {

    String access_token = \"<ACCESS_TOKEN>\";
    String app_secret = \"<APP_SECRET>\";
    String app_id = \"<APP_ID>\";
    String id = \"<AD_GROUP_ID>\";
    APIContext context = new APIContext(access_token).enableDebug(true);

    new Ad(id, context).getLeads()
      .setParam(\"filtering\", \"[{\\"field\\":\\"time_created\\",\\"operator\\":\\"GREATER_THAN\\",\\"value\\":1721709809}]\")
      .execute();

  }
}
Open In Graph API Explorer
require 'facebook_ads'

access_token = '<ACCESS_TOKEN>'
app_secret = '<APP_SECRET>'
app_id = '<APP_ID>'
id = '<AD_GROUP_ID>'

FacebookAds.configure do |config|
  config.access_token = access_token
  config.app_secret = app_secret
end

ad = FacebookAds::Ad.get(id)
leadss = ad.leads({
    fields: {  },
    filtering: [{'field':'time_created','operator':'GREATER_THAN','value':1721709809}],
})
Open In Graph API Explorer

El parámetro operator tiene uno de los valores siguientes.

OperadorSignificado

LESS_THAN

Filtros para valores inferiores a la marca de tiempo.

GREATER_THAN

Filtros para valores superiores a la marca de tiempo.

GREATER_THAN_OR_EQUAL

Filtros para valores mayores o iguales que la marca de tiempo.

Tokenización

Si el formulario tiene identificadores de campo personalizados, los campos y los valores devueltos serán los campos y los valores especificados.

Recursos