Meta Ads
Piloto privado en preparación para consultar el gasto diario de una cuenta publicitaria de Meta, al total de la cuenta y por campaña. Solo lectura; pendiente de validación real y aún no habilitado para conectar cuentas.
Piloto privado en preparación. La integración está pendiente de completar su validación con Meta real y aún no está habilitada para conectar cuentas. Esta guía describe el funcionamiento previsto para cuando se abra el piloto.
meta_ads está diseñado para leer el gasto y la entrega diarios de una cuenta publicitaria de Meta (Facebook e Instagram), al total de la cuenta y por campaña, y guardarlos en Connect para consultarlos sin volver a llamar a Meta. Cada conexión tendrá un conn_… que identifica la cuenta y viaja en toda llamada (en REST, el header X-Connect-Connection).
Una vez validado, Emisso podrá habilitar el piloto por organización. El conector solo estará disponible en el catálogo, el alta y la ejecución de las organizaciones invitadas.
El alcance previsto es solo lectura. Las herramientas del conector no crean, editan, pausan ni publican anuncios, campañas, presupuestos, públicos ni píxeles, y no administran la facturación de la cuenta publicitaria.
El gasto es una métrica publicitaria estimada, no un comprobante. Es la cifra que Meta informa en sus estadísticas de anuncios: no son facturas, recibos, cobros ni impuestos de Meta, y no sirve como respaldo contable.
Qué necesitarás al habilitarse el piloto
Para participar en el piloto, necesitas una cuenta en Meta (Facebook) con acceso a la cuenta publicitaria que quieres leer, y tu usuario debe tener permiso sobre ella. Autorizarás con ese usuario: Connect no creará cuentas publicitarias ni las administrará.
El formulario previsto pedirá dos datos, y ninguno es un secreto:
| Campo | Qué es |
|---|---|
| RUT de la empresa | La empresa a la que pertenece la cuenta publicitaria. Lo declaras tú. |
| ID de la cuenta publicitaria | El identificador de la cuenta en Meta, con o sin el prefijo act_. Lo ves en el Administrador de anuncios. |
Meta no confirma ese RUT. Su autorización no informa a qué contribuyente pertenece la cuenta publicitaria, así que Connect no tiene contra qué compararlo: el RUT queda como lo escribiste. Si conectas varias empresas, revisa que cada conexión lleve el RUT correcto.
En el flujo previsto del piloto, el navegador sale a Meta para que apruebes el acceso y vuelve a Connect. Connect no te pedirá tu contraseña de Facebook. Guardará cifrado el permiso emitido, sin mostrarlo al agente.
Permisos previstos
Para activar una conexión del piloto, Connect pedirá y exigirá un solo permiso de Meta: lectura de anuncios (ads_read), que permite leer las estadísticas de las cuentas publicitarias a las que tiene acceso quien autoriza. No pide permisos de gestión de anuncios ni de administración del negocio.
Revisa los permisos que muestra Meta antes de autorizar. Si no concedes la lectura de anuncios, o la concesión trae algún permiso que Connect no reconoce, la autorización será rechazada y la conexión no se activará.
La cuenta publicitaria queda fijada
Al autorizar, Connect comprueba que la persona que autoriza pueda leer la cuenta publicitaria indicada y recién entonces la fija a la conexión. Una conexión lee una sola cuenta publicitaria y no cambia de cuenta: para leer otra, conéctala en una conexión aparte.
El permiso vence
La vigencia del permiso la determina Meta y no se renueva automáticamente. Cuando vence, la sincronización responde connection_credential_required y hay que volver a autorizar.
Revocar el acceso
Una vez conectada la cuenta, podrás revocar el acceso de dos formas:
- Desde Meta: en la configuración de tu cuenta de Facebook, donde aparecen las integraciones comerciales con acceso, quita la aplicación de Connect. Desde ese momento Meta rechaza el permiso y la próxima sincronización responde
connection_credential_required. - Desde Connect: elimina la conexión. Eso detiene la sincronización; para que Meta también deje de reconocer el permiso, revócalo además desde tu cuenta.
Para volver a leer la cuenta después de revocar o de que venza el permiso, entra a Ajustes de la conexión y usa Volver a autorizar. La conexión conserva sus datos y su cuenta publicitaria; la persona que autoriza tiene que seguir teniendo acceso a esa misma cuenta.
El alcance
El piloto contempla un alcance, gasto, con el permiso meta_ads:read. Una sola sincronización traerá los dos niveles mediante estas herramientas:
| Tool | Qué hace |
|---|---|
meta_ads.conexion.sincronizar | Trae de Meta el gasto diario de la cuenta y por campaña y lo guarda. Es el único camino que llama a Meta por datos. |
meta_ads.conexion.verificar | Comprueba que la autorización siga vigente y que la cuenta fijada siga legible. No trae gasto. |
meta_ads.gasto_cuenta.consultar | Lee el gasto ya guardado del total de la cuenta publicitaria, un día por fila: gasto, impresiones, alcance y clics. |
meta_ads.gasto_campanas.consultar | Lee el gasto ya guardado por campaña, un día de una campaña por fila, con las mismas métricas. |
Sincronizar
Ejemplo previsto para una conexión del piloto habilitada:
curl -X POST https://connect.emisso.ai/api/v1/tools/meta_ads.conexion.sincronizar/execute \
-H "Authorization: Bearer connect_sk_..." \
-H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
-H "Content-Type: application/json" \
-d '{"input":{}}'Respuesta ilustrativa:
{
"data": { "periodo": "2026-10", "estado": "encolado", "jobId": "sjb_3h5j7k9m1n2p4q6r8s0t1", "yaEnCurso": false },
"meta": { "request_id": "req_...", "tool_id": "meta_ads.conexion.sincronizar", "plane": "read" }
}La llamada está diseñada para responder con estado: "encolado" y un jobId; el resultado de la corrida llegará por webhook o en el estado de la conexión. La cadencia automática prevista es cada cuatro horas.
El sync no trabaja por mes: relee los últimos 28 días, porque Meta corrige cifras recientes, y completa hacia atrás unos 13 meses de historial por tramos. periodo es opcional y solo organiza la ejecución; un período que no es el corriente no vuelve a consultar Meta. Cada ejecución guarda los tramos completos y, si quedan pendientes, termina con estado partial y un detalle que los explica. La capacidad para cuentas con muchas campañas aún debe validarse antes de ampliar el piloto.
Consultar
Ejemplo previsto para una conexión del piloto habilitada, con datos ya sincronizados:
curl -X POST https://connect.emisso.ai/api/v1/tools/meta_ads.gasto_cuenta.consultar/execute \
-H "Authorization: Bearer connect_sk_..." \
-H "X-Connect-Connection: conn_9tKfR2mQx4Vb" \
-H "Content-Type: application/json" \
-d '{"input":{"desde":"2026-10-01","hasta":"2026-10-20"}}'Respuesta (datos ficticios):
{
"data": {
"cuenta": { "cuentaId": "1234567890123456", "moneda": "CLP", "zonaHoraria": "America/Santiago" },
"filas": [{
"fecha": "2026-10-19",
"moneda": "CLP",
"zonaHoraria": "America/Santiago",
"gasto": "48250",
"impresiones": 61234,
"alcance": 30211,
"clics": 1402,
"clicsEnlace": 988,
"diaCerrado": true,
"versionApi": "v26.0",
"sincronizadoEn": "2026-10-20T16:00:02.000Z"
}],
"cobertura": {
"desde": "2025-09-21",
"hasta": "2026-10-20",
"completa": true,
"diasSinLeer": [],
"pendiente": null,
"sincronizadoEn": "2026-10-20T16:00:02.000Z"
},
"cursor": null
},
"meta": { "request_id": "req_...", "tool_id": "meta_ads.gasto_cuenta.consultar", "plane": "action" }
}Los filtros desde y hasta son días (AAAA-MM-DD) en la zona horaria de la cuenta publicitaria. meta_ads.gasto_campanas.consultar acepta además campanaId para traer una sola campaña. Para seguir con la página siguiente, reenvía el cursor tal cual.
El gasto es texto, con su moneda
gasto viene como decimal en texto ("48250", "12.34") en la moneda de la cuenta publicitaria, que cada fila repite en moneda. No lo conviertas a un número de coma flotante para sumarlo, y no sumes gastos de monedas distintas: si la cuenta cambia de moneda, Connect vuelve a leer el historial desde cero.
Los días son los de la cuenta publicitaria
Meta corta los días en la zona horaria de la cuenta (zonaHoraria), que puede no ser la de Chile. Un día con diaCerrado en false todavía no terminaba al leerlo y sus cifras pueden crecer en la próxima sincronización.
Cuenta y campañas no se suman
Las filas de meta_ads.gasto_cuenta.consultar ya son el total de la cuenta: no les sumes las de campañas. Tampoco supongas que la suma de las campañas cuadra con la cuenta, porque Meta puede no informar campañas eliminadas. El alcance (personas únicas) no se suma entre días ni entre campañas, y un null significa que Meta no lo informó: null no es cero.
Verdades operativas
cobertura dice qué está guardado
Las dos tools de consulta devuelven cobertura. Dentro de desde y hasta, un día sin fila es un día en que Meta no informó entrega, salvo que caiga en diasSinLeer: ahí el gasto es desconocido, no cero. completa es true solo si el historial llegó a unos 13 meses, no quedó ningún tramo sin leer y la última sincronización no quedó a medias. Con completa en false, una lista vacía no prueba que no hubo gasto.
Lo que este conector no es
- No son facturas ni cobros. Connect no lee facturas, recibos, métodos de pago ni impuestos de Meta.
- No mide resultados de negocio. No trae conversiones, ventas ni retorno de la inversión publicitaria; solo gasto, impresiones, alcance y clics.
- No es en tiempo real. Lo guardado es lo que leyó la última sincronización, y Meta puede corregir cifras de hasta 28 días atrás.
- No baja de campaña. Esta versión no trae conjuntos de anuncios ni anuncios individuales.
Errores previstos
| Código | Qué significa | Qué hacer |
|---|---|---|
428 connection_credential_required | Meta ya no acepta el permiso: venció, se revocó, no incluye la lectura de anuncios o quien autorizó perdió el acceso a la cuenta publicitaria. | En Ajustes de la conexión, usa Volver a autorizar con un usuario que tenga acceso a esa cuenta. |
409 connection_identity_mismatch | La cuenta publicitaria que respondió no es la fijada a la conexión. | Avísanos: la conexión no se usará con otra cuenta. |
502 upstream_error | Meta no respondió a tiempo o limitó las consultas. | Reintenta más tarde. La sincronización programada lo reintenta sola y conserva lo ya guardado. |
502 upstream_unexpected_response | Meta rechazó una consulta o respondió con una forma que Connect no reconoce. | Avísanos: hay que revisar la aplicación de Connect o el conector. |
Cuando la autorización deja de valer, la sincronización responde connection_credential_required; una caída o un límite de Meta responde upstream_error y no invalida la autorización. El envelope de cada código está en el catálogo de errores.
Próximos pasos
- Las cuatro tools, con contrato completo: referencia de
meta_ads. - La separación entre escribir la caché y leerla: Sincronizar y consultar.
Mercado Pago
Piloto privado en preparación para consultar pagos recibidos, reembolsos y comisiones de Mercado Pago. Pendiente de completar la validación real; aún no habilitado para conectar cuentas.
Mercado Público
Pide una licitación, una Compra Ágil o una solicitud de cotización pública de Convenio Marco por su ID, o busca las cotizaciones publicadas de desarrollo y mantención de software, y recibe sus documentos en PDF, Word, Excel o imagen, con enlaces de descarga. Sin clave: la conexión sólo pide la empresa.