API Perfil de ID/usuario de Facebook: perfiles masivos

Comprueba perfiles y páginas (Pages) de Facebook por ID numérico, nombre de usuario (vanity) o URL del perfil y obtén la foto de perfil (realojada en una URL permanente), el ID numérico, el usuario canónico, el nombre mostrado, la descripción corta y los recuentos de seguidores y de «personas hablando de esto». El producto solo lee la página pública del perfil tal como se ve sin iniciar sesión: no se usa ningún inicio de sesión ni se recogen datos de amigos. Los perfiles que no existen, están desactivados o no son visibles para visitantes sin sesión se devuelven como no activados. La tarea usa el flujo asíncrono estándar por lotes.

Formato de entrada

Sube un archivo de texto con un identificador de Facebook por línea. Formas aceptadas:

• ID numérico del perfil, p. ej. 4
• Nombre de usuario (vanity), p. ej. zuck o @zuck; letras, dígitos y puntos, de 1 a 50 caracteres, sin distinguir mayúsculas
• URL del perfil, p. ej. facebook.com/zuck, facebook.com/profile.php?id=100003012457235 o facebook.com/people/<Name>/<ID>

Las URLs de facebook.com que no son de perfil (grupos, páginas de administración, login y rutas similares) se rechazan como entradas no válidas.

4
zuck
@Meta
https://www.facebook.com/profile.php?id=100003012457235
https://www.facebook.com/people/Mark-Zuckerberg/4/

Crear una tarea

POST https://api.checknumber.ai/v1/tasks

curl --location 'https://api.checknumber.ai/v1/tasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'file=@"./input.txt"' \
--form 'task_type="facebook_profile"'

La API devuelve un ID de tarea. Guárdalo para consultar el estado.

Respuesta de carga

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "pending",
  "total": 5000,
  "estimated_amount": {
    "amount": "1.500000",
    "currency": "USD"
  },
  "message": "Task created successfully"
}

Consultar el estado

POST https://api.checknumber.ai/v1/gettasks

curl --location 'https://api.checknumber.ai/v1/gettasks' \
--header 'X-API-Key: YOUR_API_KEY' \
--form 'task_id="d4g8o46p2jvh04o9uolg"'

Consulta hasta que status sea exported. No trates pending ni processing como resultado final.

Respuesta en proceso

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "processing",
  "total": 5000,
  "success": 2500,
  "failure": 0
}

Respuesta exportada

{
  "task_id": "d4g8o46p2jvh04o9uolg",
  "status": "exported",
  "total": 5000,
  "success": 5000,
  "failure": 0,
  "result_url": "https://example-link-to-results.zip",
  "actual_amount": {
    "amount": "1.500000",
    "currency": "USD"
  }
}

Campos del resultado

El CSV de resultados tiene las siguientes columnas, en este orden: username,activated,avatar,fb_id,fb_username,name,image,tagline,followers,talking_about.

Campo	Descripción	Ejemplo
username	Identificador enviado (ID, usuario o URL del perfil), tal cual.	4
activated	Si se obtuvo una página de perfil pública (yes/no). no significa que el perfil no existe, está desactivado o no es visible sin iniciar sesión; Facebook muestra la misma página «este contenido no está disponible» en los tres casos, por lo que no se pueden distinguir.	yes
avatar	URL permanente de la foto de perfil, realojada por nosotros en fb.waavatar.xyz. Vacía cuando activated es no.	https://fb.waavatar.xyz/ins/62e8bb6110133ef3115f55454ff66c4d.jpg
fb_id	ID numérico del perfil de Facebook extraído de la página.	4
fb_username	Nombre de usuario canónico (vanity) que muestra Facebook; vacío en perfiles que solo tienen ID.	zuck
name	Nombre mostrado.	Mark Zuckerberg
image	URL firmada del CDN de Facebook con la foto de perfil. Caduca en pocos días; usa avatar para un enlace duradero.	https://scontent.xx.fbcdn.net/v/…jpg?…&oe=…
tagline	Texto corto de la biografía tomado de la descripción de la página; puede estar vacío.	Bringing the world closer together.
followers	Número de seguidores. En las páginas (Pages) es el número de «Me gusta». Entero; vacío si no se muestra.	121439077
talking_about	Recuento de «personas hablando de esto» de Facebook. Entero; vacío si no se muestra.	918893

Filas de ejemplo:

username,activated,avatar,fb_id,fb_username,name,image,tagline,followers,talking_about
4,yes,https://fb.waavatar.xyz/ins/62e8bb6110133ef3115f55454ff66c4d.jpg,4,zuck,Mark Zuckerberg,https://scontent.xx.fbcdn.net/v/....jpg?...&oe=...,Bringing the world closer together.,121439077,918893
zzqqxxjjkk993827a,no,,,,,,,,

Se admiten tanto perfiles personales como páginas (Pages). Por ejemplo, Meta se resuelve a fb_id 100080376596424 y su valor de followers es el número de «Me gusta» de la página.

Manejo del archivo

Descarga el archivo desde result_url solo cuando la tarea esté exportada. Conserva los nombres de columna al procesarlo.

Campos de respuesta

Campo	Descripción
created_at	Fecha de creación de la tarea.
updated_at	Fecha de la última actualización.
task_id	Identificador único de la tarea.
status	pending, processing, exported o failed.
total	Total de valores procesados.
success	Valores procesados correctamente.
failure	Valores con error.
result_url	URL de descarga cuando la tarea está exportada.
actual_amount	Importe final liquidado, si está disponible.
estimated_amount	Importe estimado devuelto al crear la tarea.

Códigos de estado

Estado	Descripción
200	Solicitud correcta.
202	Tarea creada y cargo estimado aplicado.
400	Archivo no válido, tipo de tarea no admitido o muy pocas entradas válidas.
401	Clave de API ausente o inválida.
402	Saldo insuficiente.
403	Producto no disponible para tu cuenta (retirado o solo lista blanca); contacta con soporte.
404	Tarea no encontrada.
413	El archivo subido es demasiado grande.
500	Error interno; reintenta más tarde.
503	Producto temporalmente no disponible (en mantenimiento); no se cobra, reintenta más tarde.

Notas operativas

• La tarea es asíncrona; usa el ID para consultar el estado.
• Precio: 3 $ por cada 10.000 identificadores. Se factura por cantidad enviada: cada identificador enviado se cobra, se encuentre o no un perfil. La cantidad mínima facturable por tarea es de 500 identificadores; las tareas más pequeñas se facturan como 500.
• Los resultados reflejan la página pública del perfil en el momento de la comprobación. No se aplica caché; cada envío se vuelve a comprobar.
• Revisa los límites de entrada del producto antes de subir.
• Las filas con error se reflejan en el resultado exportado y en los contadores.
• Los campos se basan en la muestra actual y pueden cambiar si cambia la estructura de la página de origen.