Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Actualizado el 2026-10-05

Meta Ads (Facebook e Instagram) — conector

Lee el informe de Insights de Meta Ads (Facebook e Instagram) — una fila por día — en tres tablas Bronze (campañas, conjuntos y anuncios).

En esta página (16)

Lea antes: ../conectores.md (mapa de estados) y fichas.md (índice de las fichas).


Qué es#

Lee el informe de Insights de Meta Ads (Facebook e Instagram) — una fila por día — en tres tablas Bronze (campañas, conjuntos y anuncios).

Modos de ingestión soportados:

  • Nós buscamos — Nosotros buscamos los datos en su fuente.

Para qué sirve#

Traer los datos de Meta Ads (Facebook e Instagram) a su datalake y ponerlos a disposición en las capas Bronze/Silver/Gold, en los modelos de BI y en el asistente de preguntas en lenguaje natural.

Cuándo usar / cuándo no usar#

Use cuando necesita consolidar esta fuente en el datalake de forma programada, con aislamiento por workspace.

Úselo con el token de su empresa: el conector lee la cuenta publicitaria con un token de usuario del sistema de su propio Business Manager, con el permiso ads_read. Ninguna app nuestra necesita aprobación.

Plan y permisos#

  • Plan: núcleo del producto (los conectores forman parte de todos los planes; el límite es el número de fuentes del plan).
  • Acceso: requiere un workspace activo — si la suscripción está en atraso, suspendida o cancelada, la ejecución queda bloqueada.
  • Desconexión: la ejecución de ingestión puede ser apagada temporalmente (mantenimiento o incidente). Cuando eso ocurre, la pantalla informa que el recurso está indisponible en este momento.

Requisitos previos#

  • Acceso de administrador al Business Manager de la empresa dueña de la cuenta publicitaria.
  • El ID de la cuenta publicitaria, en el formato act_… (aparece en el Administrador de Anuncios, junto al nombre de la cuenta).

Cómo generar el token (usuario del sistema)#

  1. En el Business Manager, abra Configuración del negocio.
  2. En Usuarios → Usuarios del sistema, use Agregar. Dele un nombre (ej.: ingestia-lectura) y elija el rol Empleado — la lectura es suficiente.
  3. Con el usuario del sistema seleccionado, use Asignar activos → Cuentas publicitarias, marque la cuenta que desea leer y conceda Ver rendimiento (sin permiso para administrar campañas).
  4. Todavía en el usuario del sistema, use Generar nuevo token. Elija la app de su negocio, marque el permiso ads_read y, si la pantalla lo ofrece, la validez Nunca caduca.
  5. Copie el token (empieza con EAA…). Solo aparece una vez.
  6. En ingestia.io, en Dados → Conexões → Nova conexão → Meta Ads (Facebook e Instagram), pegue el token en Token de acesso y complete Conta de anúncios con el act_….
  7. Use Testar conexão. Si da Autenticação: Falhou, verifique que la cuenta publicitaria esté asignada al usuario del sistema y que el token tenga ads_read.

El token pertenece a su empresa: para cortar el acceso, revóquelo en el propio Business Manager (o elimine el usuario del sistema). Cambiar el token aquí no lo revoca allá.

Credenciales#

Forma de autenticación: Token de acceso pegado por usted. Está cifrado (AES-256-GCM) y nunca se muestra de nuevo, ni aparece en logs o mensajes de error.

Campos sensibles. Están cifrados (AES-256-GCM) y nunca quedan en el config de la conexión, en la definición del pipeline, en el export o en la DAG. Por defecto el valor cifrado queda en la base; mover la credencial de esta conexión al cofre externo de credenciales es una elección explícita, hecha por conexión después de guardar — ver ../../administracao/credenciais-e-rotacao.md.

  • Token de acceso (accessToken)

Los secretos nunca se vuelven a mostrar y pasan por redacción en todo error/log (token crudo, URL-encoded y en JSON).

Campos del formulario#

CampoRótuloTipoObligatorioObservación
adAccountIdConta de anúnciostextosimEl ID aparece en el Administrador de Anuncios, en el formato act_…
levelGranularidadselecciónnãopadrão: campaign; opções: campaign / adset / ad
datePresetVentana de datosselecciónnãopadrão: last_30d; opções: last_7d / last_14d / last_30d / last_90d / this_month / last_month
apiVersionVersión de la APItextonãopadrão: v21.0; Sólo modifique si Meta descontinúa la versión actual.
accessToken 🔒Token de accesocontraseña/secretosimsecreto (cifrado; cofre externo opcional)

Paso a paso#

  1. En el menú Dados → Conexões, use Nova conexão.
  2. Elija Meta Ads (Facebook e Instagram) en el catálogo.
  3. Complete los campos del formulario (vea la tabla arriba).
  4. Use Testar conexão. El resultado viene separado en Conectividade, Autenticação y Listagem/leitura — cada uno con OK, Falló, No aplica o No probado. Una capacidad sin prueba propia para este conector aparece como No aplica, y No aplica nunca cuenta como éxito.
  5. Use Salvar conexão. Guardar NO inicia ninguna ingestión.
  6. En la tarjeta de la conexión, use Montar extração (o vaya a Orquestração → Pipelines y use Conectar fonte). El pipeline apunta a la conexión guardada — la credencial no se copia.
  7. En la revisión, Publicar (agenda desligada) crea la versión 1 sin ejecutar nada. Después, Ativar agenda y Executar agora son acciones separadas.

Ejemplo — prueba de conexión#

Configuración de ejemplo (todos los valores son ficticios; los secretos aparecen enmascarados):

text
# Exemplo sintético (valores fictícios — não são credenciais reais)
adAccountId = act_1234567890
level = campaign
datePreset = last_30d
apiVersion = v21.0
accessToken = •••••• (cifrado — nunca exibido)

Resultado esperado#

El Testar conexão devuelve la lista de tablas/recursos descubiertos. Tras la primera carga, las filas aparecen en la capa Bronze de su workspace, listas para el pipeline.

Límites y costos#

  • Paginación: tope duro por ejecución (default 10.000 páginas / 5.000.000 filas); guarda anti-loop.
  • Carga SaaS: default batchSize 5.000, maxRows 200.000 por recurso.
  • Volumen estimado: ~0.5 GB/mes (estimación de catálogo, no medición).
  • **

Seguridad#

  • Alcance por workspace: cada cliente lee y escribe solo en su propio datalake (<prefixo>_bronze / _silver / _gold); nunca hay filtración entre workspaces.
  • Secretos cifrados: material sensible se cifra con AES-256-GCM antes de ser grabado. El cofre externo de credenciales es opcional y se activa por conexión; sin él, el valor cifrado queda en la base. Cambiar el valor aquí NO revoca la credencial en el origen.
  • Redaction: todo error/log pasa por la redacción de secretos (crudo, URL-encoded y en JSON).
  • Producción no simula: un camino que caería en mock activa la guarda de producción (fallo explícito en vez de simular éxito).

Errores comunes#

  • Credencial rechazada (401/403) — el proveedor no aceptó la credencial: expirada, revocada o sin el permiso necesario. Reconecte la fuente (la fuente y el historial se preservan; no recree la fuente).
  • Límite de peticiones (429) — el proveedor pidió esperar. La extracción respeta Retry-After y reintenta; si se repite, espere y reduzca la frecuencia de la agenda.
  • Recurso no encontrado — verifique el identificador del recurso (cuenta, objeto, informe) y los permisos concedidos.
  • Cursor de paginación bloqueado — la extracción termina cuando el cursor de la API no avanza (guarda anti-loop). Si ocurre en ejecuciones seguidas, abra un ticket con soporte indicando el conector y el recurso.
  • Ruta de registros vacía — la respuesta llegó sin registros en el lugar esperado. Verifique el recurso seleccionado y los filtros (período, cuenta, estado) antes de asumir que no hay datos.

Solución de problemas#

  • Use Testar conexão para aislar problemas de credencial/red antes de programar.
  • Siga las ejecuciones en la observabilidad por conector (tasa de error, p50/p95, freshness).
  • Un cambio de esquema en el origen es señalado por el schema drift (columna nueva = info; columna removida/tipo cambiado = atención).

Relacionados#


Última revisión: 2026-10-05. Ficha generada automáticamente del catálogo de conectores del producto.

Enlaces relacionados