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.

La herramienta encola; el pipeline envía

send_meta_conversions no llama a Meta. confirm escribe filas en el ledger conversion_exports de Atribu y encola un job de exportación; el pipeline worker realiza la entrega real. Esto es deliberado: el worker envía bajo el event_id canónico del booking cluster, de modo que una conversión que llegó a Atribu por varias vías (tracker del navegador, webhook del CRM, sync masivo) se envía una sola vez y la deduplicación de 48 horas de Meta la colapsa contra tu Pixel. Un segundo emisor usando otro id contaría el mismo dinero dos veces.

Acción irreversible

Una vez encolada, la conversión se entrega a Meta y no puede ser retirada. 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
Un destino de exportación habilitado -- Conversion Sync debe tener un destino meta_capi activo para el perfil (además de la cuenta de Meta Ads conectada). Ese destino es el que decide el pixel/dataset donde aterrizan los eventos; el argumento pixel_id solo se valida contra él, nunca decide el enrutamiento.

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

Planifica la corrida contra el ledger de exportación. No se escribe ni se encola nada.

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

La herramienta devuelve:

counts.scoped — registros fuente que la ventana + los tipos de evento capturaron
counts.would_enqueue — cuántos se encolarían realmente
counts.already_delivered — ya están en Meta bajo su event id canónico, así que no se reenvían
counts.already_queued — ya hay un job en camino para ellos
counts.not_ledgered — el pipeline todavía no construyó un candidato de exportación para ellos
Los destinos a los que apuntaría la corrida y el estado de la puerta legal del perfil

El preview queda registrado en el rastro de auditoría.

Paso 2: Dry-run

El mismo plan, registrado en el log de auditoría de write-back como intención. Sigue sin encolar nada.

Haz un dry-run de esas conversiones

Sin llamada de test-event a Meta

Antes de que la herramienta pasara al ledger de exportación, dry_run posteaba a Meta con un test_event_code. Ya no lo hace — una herramienta que nunca envía tampoco puede enviar de prueba. test_event_code se sigue aceptando y se ignora. Para validar la forma del payload contra la pestaña Test Events de Meta, usa la superficie de Conversion Sync en el dashboard.

Paso 3: Confirm

Encola la corrida. 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 devuelve result: "queued" — no "sent" — más:

batch_id — consulta GET /api/v1/exports/{batch_id} para el progreso de esta corrida
queued_job_ids — los mensajes de cola que se crearon
counts — el mismo desglose que preview, con enqueued en lugar de would_enqueue
observe — la URL del ledger con los resultados de entrega

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 encolar de nuevo.

Dónde llega la respuesta

La entrega es asíncrona. GET /api/v1/exports/ledger es el ledger de entregas sin PII: estado por fila (pending → sent / failed / skipped), número de intentos, el event id canónico que se envió y el trace id del proveedor.

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.

El ledger de exportación

El ledger es lo que hace que "ya fue entregado" sea una pregunta contestable, y está indexado por el event id canónico, no por la vía que ingirió la conversión. Una fila ya sent nunca se resetea ni se reencola, sin importar cuántas veces dispares la ventana — así que un confirm repetido es un no-op, no una segunda conversión en Meta.

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
El resultado del encolado en caso de éxito: el batch id, los ids de fila del ledger y los ids de mensaje de cola
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

La herramienta ya no estima la calidad de coincidencia. Antes lo hacía desde su propia copia del constructor de payloads — respondiendo sobre un payload que nunca era el que se enviaba, porque el pipeline de exportación construye el suyo con resolución de identidad más rica y la postura de privacidad del perfil aplicada.

Los números reales son los de Meta y viven en Conversion Sync → Match Quality en el dashboard: la tabla de cobertura por parámetro (email, teléfono, fbc, fbp, external_id, ctwa_clid) leída desde el EMQ de Meta, con la derivación de "podemos llenar N de M con datos que ya tenemos".

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 también es asíncrono, en su propia cola. 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.