Write-Back (Meta CAPI)

Envía conversiones atribuidas a la API de Conversiones de Meta con flujo de preview, dry-run y confirm

La herramienta send_meta_conversions te permite enviar conversiones atribuidas de Atribu a la API de Conversiones de Meta (CAPI). Esto mejora la optimización de entrega de anuncios de Meta alimentando datos reales de conversión al algoritmo.

Atribu tiene una segunda herramienta de escritura con las mismas puertas y el mismo flujo de seguridad: apply_recommendation, que aplica recomendaciones del media buyer de IA (pausas / cambios de presupuesto) contra Meta. La mayor parte de esta página cubre send_meta_conversions; las diferencias de apply_recommendation están al final.

Acción irreversible

Las conversiones confirmadas se envían a Meta y no pueden ser retiradas. La herramienta aplica un flujo de seguridad de tres pasos para prevenir envíos accidentales.

Prerrequisitos

Antes de usar write-back, las cuatro condiciones deben cumplirse:

Scope del token -- tu token MCP debe incluir mcp:write
Configuración del workspace -- un administrador del workspace debe habilitar MCP write-back en la configuración
Rol de usuario -- debes ser propietario o administrador del workspace
Conexión Meta -- debe haber una conexión de Meta Ads activa

Si alguna condición no se cumple, la herramienta devuelve un error tipado explicando qué falta y cómo solucionarlo.

El flujo de tres pasos

Paso 1: Preview

Construye eventos de conversión localmente e inspecciónalos sin llamar a Meta.

Envía mis conversiones de payment_received de los últimos 7 días a Meta en modo preview

La herramienta devuelve:

Conteo total de eventos
Eventos de muestra (primeros 3) con campos mapeados
Desglose de calidad de coincidencia (excelente / buena / débil) basado en datos de usuario disponibles

Ningún dato sale de Atribu durante el preview — no se hace ninguna llamada a Meta. El preview igualmente queda registrado en el rastro de auditoría.

Paso 2: Dry-run

Envía eventos a Meta con un código de evento de prueba. Meta valida el formato del payload y la calidad de coincidencia sin registrar conversiones reales.

Haz un dry-run de esas conversiones con pixel ID 1234567890

La herramienta devuelve:

Conteo de events_received de Meta
fbtrace_id para depuración en Meta Events Manager
Cualquier advertencia de validación de Meta

Eventos de prueba

Los eventos de dry-run aparecen en Meta Events Manager bajo la pestaña Test Events. No afectan la entrega de anuncios ni los reportes.

Paso 3: Confirm

Envía eventos a Meta de forma real. Requiere una clave de idempotencia para prevenir envíos duplicados.

Confirma el envío de esas conversiones. Usa clave de idempotencia "abril-semana2-pagos"

La herramienta de IA debe generar una clave de idempotencia única (típicamente un UUID o string descriptivo) e incluirla en la llamada de confirm. Si la misma clave se usa dos veces, la herramienta devuelve el resultado anterior en lugar de enviar de nuevo.

Mapeo de tipos de evento

Los tipos de outcome de Atribu se mapean a eventos estándar de Meta:

Evento Atribu	Evento Meta
`payment_received`	`Purchase`
`order_placed`	`Purchase`
`closed_won`	`Purchase`
`appointment_booked`	`Schedule`
`lead_created`	`Lead`
`checkout_started`	`InitiateCheckout`
`add_to_cart`	`AddToCart`
`add_payment_info`	`AddPaymentInfo`
`view_content`	`ViewContent`
`search`	`Search`

Controles de seguridad

Idempotencia

Cada llamada confirm requiere un idempotency_key. Si un confirm con la misma clave ya fue procesado para este perfil, la herramienta devuelve el resultado anterior. Esto previene envíos dobles accidentales incluso si la herramienta de IA reintenta.

Circuit breaker

Si 3 o más operaciones confirm fallan para el mismo perfil en 30 minutos, la herramienta entra en estado circuit-open y rechaza nuevas llamadas de confirm. Espera al enfriamiento o investiga las fallas.

Rastro de auditoría

Cada operación (preview, dry-run, confirm) crea un registro de auditoría inmutable con:

Hash del payload, conteo de eventos, fechas de ventana
IDs de envío externos (en caso de éxito)
Estado del resultado y detalles de error
Request ID para trazabilidad

Los registros de auditoría son visibles para administradores del workspace en el dashboard.

Calidad de coincidencia

El paso de preview estima qué tan bien Meta puede hacer coincidir tus eventos con clics en anuncios. Los identificadores fuertes son email, teléfono, fbc (ID de clic de Meta) y ctwa_clid (ID de clic de Click-to-WhatsApp):

Calidad	Criterios
Excelente	Tiene 2 o más identificadores fuertes
Buena	Tiene exactamente 1 identificador fuerte, o una cookie `fbp` (de navegador)
Débil	Ninguno de los anteriores -- Meta puede no hacer coincidir este evento

Mayor calidad de coincidencia significa que Meta puede atribuir mejor la conversión al clic correcto del anuncio, mejorando la entrega futura de anuncios.

apply_recommendation — la segunda herramienta de escritura

apply_recommendation aplica una recomendación del media buyer de IA (pausar un anuncio de bajo rendimiento, escalar un ganador, reasignar presupuesto entre ad sets) contra Meta. Comparte la maquinaria de write-back:

Mismos tres modos -- preview (sin efectos secundarios; muestra el anuncio/ad-set objetivo, las llamadas a Meta planeadas y el % de cambio de presupuesto), dry_run (registra una fila de auditoría capturando la intención), confirm (ejecuta de verdad).
Mismas puertas -- scope mcp:write + write-back del workspace habilitado + rol de propietario/administrador, aplicadas en dry_run y confirm. preview funciona sin ellas.
Mismo costo -- 10 unidades.
Mismo rastro de auditoría -- cada operación escribe en el mismo log de auditoría que los administradores ven en el dashboard.

Diferencias respecto a send_meta_conversions:

La clave de idempotencia es opcional. Cuando se omite en confirm, se deriva automáticamente de (usuario, recomendación, día) — así, repetir la misma recomendación el mismo día deduplica, mientras que un reintento deliberado al día siguiente es distinto. Repetir una clave ya procesada devuelve la aplicación existente, no una escritura duplicada.
Confirm es asíncrono. confirm encola un trabajo para el pipeline worker, que captura el estado de Meta pre-cambio, ejecuta la(s) escritura(s) en Meta y verifica que el cambio realmente se aplicó unos 5 minutos después. Usa diagnose_recommendation para inspeccionar la aplicación, su estado pre/post y el resultado de la verificación.
Confirm requiere una recomendación abierta. Las recomendaciones ya aplicadas, descartadas, reemplazadas, expiradas o revertidas se rechazan (el preview sigue funcionando como consulta de historial).
creative_refresh_pre_fatigue nunca llama a Meta. Ese kind devuelve una URL de handoff a Ads Lab.