Novedades de la API

Creación de cuentas de Met desde tu producto

• La API pública incorpora POST /workspaces para crear una cuenta de Met con su dueño. Es exclusivo de las llaves de partner con el permiso workspaces:provision, disponible para los Tech Partners aprobados.
• La cabecera Idempotency-Key es obligatoria en esta operación: reintentar con la misma clave devuelve la cuenta que ya se creó, no una nueva.
• POST /workspaces/{workspaceId}/recharge (permiso workspaces:recharge) abre un enlace de pago para cargarle energía a una cuenta que creaste. Solo funciona sobre tus propias cuentas.

La cuenta nace con el plan Tech Partner y sin energía, así que la respuesta incluye operational: false mientras el saldo esté en cero. La energía la paga siempre la cuenta que la consume: carga saldo antes de que tu cliente empiece a usarla. La recarga no acredita el saldo al instante — devuelve un enlace de pago y la energía entra cuando el pago se completa. El dueño recibe por correo un enlace para definir su contraseña — nunca la defines tú.

Cada nivel de partner tiene un cupo mensual de cuentas. Al agotarse, la operación responde 403 indicando el cupo, el consumo del mes y cuándo se reinicia.

Cancelación de flujos y contrato actualizado de Red Máster

• La API pública incorpora POST /workspaces/{workspaceId}/flow-runs/{runId}/cancel para detener el agendado de nuevos nodos y marcar una ejecución como cancelada.
• El contrato de Partners refleja la terminología y las operaciones vigentes de Red Máster, incluidas las solicitudes, vinculaciones y designaciones.

Cancelar una ejecución no interrumpe una generación que el proveedor ya haya comenzado; esa operación termina y conserva su cobro correspondiente.

La API de conversiones documenta sus errores de operación

Las operaciones públicas de conversiones de contacto y conversiones web ahora documentan los errores 403, 404 y 409 que pueden devolver. Las integraciones pueden distinguir permisos insuficientes, recursos no disponibles y conflictos o duplicados sin depender de respuestas no documentadas.

La API de conversiones documenta sus errores de acceso y conflicto

Las operaciones POST /conversions y POST /conversions/web ahora describen en OpenAPI las respuestas de error que una integración puede recibir:

• 403 cuando la credencial no tiene acceso a la operación.
• 404 cuando el recurso asociado no existe dentro de su alcance.
• 409 cuando la conversión entra en conflicto con el estado existente.

Este ajuste no cambia el formato de las solicitudes ni de las respuestas; hace que la referencia y los clientes generados reflejen el contrato vigente.

La API de Partners ya documenta respuestas y errores de acceso reales

Las 37 operaciones de met.partner.* ahora describen su respuesta exitosa: clientes, comisiones, payouts, oportunidades, proyectos, hilos y tickets. El OpenAPI deja de mostrar respuestas vacías, así que la referencia y los clientes generados pueden conocer la forma curada de cada recurso.

También documentamos los errores que una integración puede recibir de verdad:

• 403 cuando falta un scope, una capacidad no está habilitada o el recurso queda fuera de la cartera de la key.
• 404 cuando un recurso no existe dentro de ese alcance, sin revelar recursos de otro tenant.
• 409 en operaciones que mutan estado, incluidos los conflictos de Idempotency-Key.

Las requests autenticadas con API key devuelven ahora la taxonomía pública de error también cuando una validación o regla de dominio usa una excepción estándar: type, code, message y request_id. Las sesiones del panel conservan su formato anterior.

Acceso API por plan mensual y nuevo plan Tech Partner

• Las API keys se pueden crear y administrar desde el workspace antes de contratar un plan.
• Para usar una key, el workspace operado debe tener un plan mensual vigente; también cuentan el trial y los planes bonificados.
• Las keys de Partner validan el plan del workspace atribuido y ya no pueden operar un cliente sin suscripción activa.
• Los límites de RPM y cuota mensual se resuelven desde el plan vigente al ejecutar cada key.
• Tech Partner es un plan restringido de USD 0 de cargo fijo mensual, habilitado únicamente por Meteor para alianzas aprobadas; la Energía se cobra a tarifa premium.

El CLI separa webhooks entrantes de entregas salientes

El comando met webhooks mezclaba dos direcciones distintas: lo que un tercero envía a Meteor y lo que Meteor entrega a tu servidor. Además, sample afirmaba enviar una prueba cuando solo leía el último payload entrante.

Ahora usa el grupo que corresponde al flujo:

# Tercero → Meteor: ver lo recibido, sin generar tráfico.
met inbound-webhooks events 12
met inbound-webhooks sample 12

# Meteor → tu servidor: probar, inspeccionar y reintentar entregas firmadas.
met webhook-endpoints test we_123
met webhook-endpoints deliveries we_123
met webhook-endpoints retry we_123 del_456

test y retry salen con código 0 solamente cuando tu servidor confirma la entrega. Si la API pudo iniciar el intento pero el receptor falla o vence el timeout, el CLI sale con 1, para que un pipeline no lo reporte como éxito.

met webhooks sigue disponible temporalmente como alias de met inbound-webhooks y avisa que está deprecado.

Resuelto es el estado final de los tickets de soporte

La API de partners simplifica el ciclo de soporte: resolved es ahora el único estado terminal y closed deja de ser un valor aceptado.

Los estados válidos de PATCH /partner/tickets/:id/status son:

new · in_progress · waiting_client · resolved

Un ticket resuelto ya no se puede reabrir ni recibir respuestas. Si el problema persiste, crea un ticket nuevo; así cada caso conserva un inicio, una resolución y un historial inequívocos.

Los contactos gemelos ahora se detectan y se pueden fusionar

Qué cambió

GET /contacts/{id}/duplicates gana un motivo de coincidencia nuevo: identidad.

Hasta hoy la búsqueda de duplicados comparaba teléfono y email. Eso deja fuera el caso más incómodo: dos contactos que son literalmente la misma conversación —mismo user_ns, mismo canal, misma línea—. Pasa cuando alguien te escribe por primera vez mandando varios mensajes seguidos, y también cuando una importación trae el número con + y el chat entrante lo trae sin él.

{
  "data": [
    {
      "id": 33325,
      "name": "Cristhian Martinez",
      "phone": "+573172723452",
      "matched_by": ["identidad", "phone"],
      "can_merge": true,
      "blocked_reason": null
    }
  ]
}

matched_by ahora puede traer "identidad" además de "phone" y "email". Es aditivo: si ya lees ese arreglo, los valores viejos siguen llegando igual.

Lo que antes no se podía fusionar, ahora sí

can_merge era false en cuanto los dos contactos tenían conversación propia, sin mirar si era la *misma* conversación. Los gemelos exactos caían justo ahí y quedaban trabados.

Ahora la regla mira el valor, no su presencia:

• Misma identidad (mismo user_ns, mismo canal, misma línea) → can_merge: true. Se fusionan y la identidad que sobrevive queda en dígitos, sin +.
• Identidades distintas con conversación propia cada una → sigue bloqueado, con su blocked_reason. Fusionarlas perdería una y el próximo mensaje desharía la fusión.

Un + de más no hace dos identidades: +573172723452 y 573172723452 son la misma persona. Los identificadores que no son teléfonos (los de Meteor CRM, los BSUID de WhatsApp) se siguen comparando literales.

Qué tienes que hacer

Nada obligatorio. Si guardas la identidad del contacto por tu lado, conviene que la normalices a dígitos: es el formato con el que entra WhatsApp y con el que queda un contacto después de fusionarse.

Reporta conversiones web (Pixel) con deduplicación

Ahora puedes reportar conversiones web a Meta como espejo server-side de tu Pixel, para no perder eventos que el navegador bloquea (ad-blockers, iOS, cookies).

• POST /api/v1/conversions/web — scope conversions:write.
• Pasa el mismo event_id que disparaste en el navegador con fbq('track', …, { eventID }). Meta deduplica Pixel↔CAPI durante 48h con esa clave, así que el evento cuenta una sola vez aunque llegue por los dos caminos.
• No es por-contacto: la coincidencia va por fbp/fbc (cookies del navegador) o por PII opcional (email, phone, external_id, que hasheamos antes de emitir). Necesitas al menos una clave de match.
• Reenvía la IP y el User-Agent del usuario final (no los de tu servidor) en client_ip_address / client_user_agent para mejorar la coincidencia.
• Opcionales: event_source_url, value, currency.
• Devuelve la decisión real: accepted (encolado), discarded (con razón: integración inactiva, fuera de taxonomía, sin clave de match) o duplicate.

Los eventos web usan los nombres de evento del Pixel (no los de *business messaging* de WhatsApp) — configúralos en la taxonomía del workspace.

SDK: met.conversions.reportWeb({ event_name, event_id, fbp, … }).

Reporta conversiones a Meta desde la API

Ya puedes reportar conversiones a Meta (Conversions API) por nuestra API pública, con el mismo criterio que aplica el Met: una compuerta valida atribución del anuncio, taxonomía y corroboración antes de emitir. Tú mandas el hecho; nosotros decidimos y emitimos.

• POST /api/v1/conversions — scope conversions:write.
• Body: contact_id (el contacto de _contacts), event_name (debe estar en la taxonomía del workspace), y opcionales value, currency, evidence, bucket.
• Devuelve la decisión real: accepted (encolado para emisión), pending_corroboration (esperando el hecho objetivo), discarded (con la razón: sin atribución, fuera de taxonomía, etc.) o duplicate.

Para WhatsApp, Meta exige nombres de evento de *business messaging* (ej. Purchase, LeadSubmitted, InitiateCheckout) — no los del Pixel web. Este origen (api) puede confirmar Purchase directamente, porque representa un hecho objetivo de tu sistema.

Soporta Idempotency-Key. Es una key de efecto externo real: las keys met_test_ no pueden emitir (evita eventos reales a Meta desde pruebas).

La recarga automática ahora tiene techo mensual

Qué cambió

La recarga automática de Energía puede tener un tope de gasto por mes. Mientras el tope no se alcance, todo funciona igual; al alcanzarlo dejamos de cobrar la tarjeta y la recarga se reanuda sola el primer día del mes siguiente.

GET /billing/auto-recharge trae tres campos nuevos:

{
  "enabled": true,
  "threshold_usd": 5,
  "amount_usd": 50,
  "monthly_cap_usd": 200,
  "month_spent_usd": 150,
  "capped": false
}

• monthly_cap_usd — el techo, en USD. null significa sin tope, que es como sigue configurada toda cuenta que no lo haya cambiado.
• month_spent_usd — cuánto lleva gastado la recarga automática este mes. Una recarga hecha a mano no consume el tope. El mes corta en la zona horaria del workspace y el contador vuelve a cero solo.
• capped — true cuando la siguiente recarga ya no cabe en el tope. Ojo con esto: no es lo mismo que haber gastado el tope entero. Con un tope de 200, 180 gastados y recargas de 50, capped ya es true aunque queden 20 sin usar.

Qué tienes que hacer

Nada, si no lees esta configuración. Los tres campos vienen siempre, y las cuentas sin tope los reportan como null, 0 y false.

Si muestras el estado de la recarga automática, capped merece su propio mensaje. Por dentro se parece a una recarga pausada —no se cobra—, pero no es una falla: es el límite que la propia cuenta pidió. Tratarlo como error manda a revisar una tarjeta que está perfecta.

if (config.capped) {
  // Llegó al tope del mes. Se reanuda sola; no hay nada roto.
} else if (config.status === 'failed') {
  // Esto sí: la tarjeta rechazó el cobro.
}

Por qué te conviene mirarlo ahora

Sin tope, activar la recarga automática es autorizar un cobro sin techo: si algo consume Energía en bucle, la tarjeta se cobra tantas veces como haga falta y la cuenta se entera por el extracto. Es la razón por la que mucha gente la deja apagada — y con ella apagada, los Mets se detienen cuando el saldo se acaba. El tope es lo que permite dejarla encendida sin firmar un cheque en blanco.