Novedades de la API

Partners API — clientes, comisiones y payouts

*Entrada agregada el 2026-07-25: estos tres dominios se publicaron el 11 de julio junto con oportunidades y proyectos, pero se quedaron sin anuncio propio. Queda registrado para que el historial de met.partner.* esté completo.*

El namespace met.partner.* nace con su núcleo read-only, servido por el backend de partners y enrutado en el SDK a partnerBaseUrl:

• GET /partner/clients — clientes atribuidos al partner: plan, estado, ciclo de facturación, comisión y consumo de Energía. Scope partner:clients:read. En el SDK: met.partner.clients.list({ page, limit, search }).
• GET /partner/commissions — comisiones con monto, tasa aplicada, estado y trazabilidad de negocio. Scope partner:commissions:read. Filtra por status.
• GET /partner/payouts y GET /partner/payouts/summary — liquidaciones (bruto, fee, neto, cadencia, referencia de pago) y el resumen de wallet. Scope partner:payouts:read.

Todo curado: nunca salen la mecánica de cálculo interna de una comisión ni las notas privadas del staff sobre un cliente.

Los cuatro scopes son exclusivos de keys de partner. Una key de workspace que los pida recibe 403, y el servidor lo re-verifica en cada request por owner_type.

Los dominios financieros se mantienen read-only por diseño: crear o editar comisiones y payouts pasa por reconciliación humana.

Superficie pública inicial

Primera versión del contrato público de la Met API (F0 — contrato y anti-drift).

• Se declara la superficie pública con @ApiPublic/@ApiInternal: 179 operaciones públicas sobre 444 rutas de meteorus.
• Dominios públicos v1: collections, items (+content/comments/links/files), contacts, tasks (+steps/triggers/comments), rag, variables, files (workspace assets), skills, billing:read, automations:read.
• openapi.public.json generado del código; el drift-check de CI garantiza que nunca quede desactualizado.

Aún no hay credenciales de API ni ejecución por key — eso llega en F1. Esta entrada documenta la congelación del contrato.

Superficie conversacional en v1 (WhatsApp, handoff, flujos)

Lo conversacional es núcleo de Met, así que sube a la superficie pública v1 (antes marcado fase 2). Aditivo — no rompe nada de la superficie inicial. 179 → 215 operaciones públicas.

Nuevos scopes:

• conversations:read — leer conversaciones WhatsApp/CRM que Met gestiona (7 ops: listar/leer conversaciones y mensajes, búsqueda, tool-calls).
• handoff:manage — autopilot on/off/pause + marcar leído (3 ops).
• channels:read — estado de canales y broadcasts, sin permiso de envío (3 ops).
• channels:send — envío WhatsApp (buttons/list/location/contact/reaction/reply/template), mensajes a contacto y broadcasts (crear/cancelar/editar/borrar) — 13 ops.

Flujos suben bajo automations: listar/leer y ejecutar/publicar/testear (10 ops).

Curación (importante):

• En Canales se exponen solo los métodos de envío. La configuración/conexión (tokens de WhatsApp, registro de webhook, phones, templates, config de canal) queda interna — nunca sale por SDK.
• El chat crudo (/conversations/:id/messages/stream) sigue interno: la vía pública para *ejecutar/conversar con el Met* es la façade Runs (F1). Aquí solo se exponen las lecturas de conversación.

Deudas de runtime (F1, antes de que esto sea alcanzable — hoy no hay auth por key):

• channels:send exige gating anti-abuso (límites de Meta, anti-spam) antes de estar vivo.
• Los payloads de conversación/mensaje deben curarse (no filtrar campos internos) al cablear los guards.

Runs — ejecución de Mets por API (el plano agéntico)

Llega Runs: ejecutar el Met de tu workspace por API, con memoria opcional y streaming. Es el corazón de "infraestructura agéntica como servicio". Aditivo. 248 → 251 operaciones públicas.

Nuevos endpoints (scopes runs:execute / runs:read):

• POST /workspaces/:id/runs — ejecuta el Met sobre input. Con conversation_id el run tiene memoria; sin él corre en una conversación efímera. stream: true → respuesta SSE con los eventos en vivo.
• GET /runs/:id — estado + salida de un run.
• GET /workspaces/:id/runs — historial paginado (cursor opaco, { data, has_more }).

Esquema público de eventos (estable, versionado): run.started, run.step, run.output, run.completed, run.failed. El run.step es una proyección curada del trace interno — expone tipo de paso, iteración, nombre de tool y actor; nunca prompts internos, inputs crudos de tools, costos de proveedor ni conteos de tokens.

Costo: cada run debita Energía por el mismo ledger de siempre, marcado execution_type='api' y atribuido a la key — el consumo por API aparece separado del chat interno en tu dashboard.

Forma del recurso (convención de recursos nuevos): id opaco run_<ULID> (ordenable por tiempo), object: "run", livemode (false en keys met_test_) y metadata libre.

Nota: el met del body es un hint informativo en v1 — el orquestador del workspace auto-rutea al especialista adecuado (mismo comportamiento que el chat). La gestión curada de Mets individuales llega con la fachada agents.

Integraciones — activar y ejecutar conectores MCP por API

Las integraciones MCP de Met (Shopify, Alegra, etc.) llegan a la API pública. Activa conectores, guarda sus credenciales y ejecuta sus tools desde tu código. Aditivo. 251 → 256 operaciones públicas.

Nuevos endpoints (scopes integrations:read / integrations:manage / integrations:execute):

• GET /workspaces/:id/integrations — catálogo + estado de conexión de cada integración.
• GET /workspaces/:id/integrations/:key/tools — tools disponibles de una integración.
• POST /workspaces/:id/integrations/:key/activate — activa la integración; opcional { credentials } (write-only).
• DELETE /workspaces/:id/integrations/:key — desactiva.
• POST /workspaces/:id/integrations/:key/tools/:tool — ejecuta una tool con el input del schema de la integración.

Reglas del camino público (importantes):

• Credenciales write-only: se guardan pero ningún GET las devuelve, ni enmascaradas. El estado observable es connection_status / last_tested_at.
• Errores del proveedor curados: si el tercero falla, recibes integration_upstream_error genérico — nunca el body crudo del proveedor (que podría traer credenciales o PII). El detalle queda en los logs internos.
• Allowlist opcional por key: una key puede restringirse a ejecutar solo tools específicas (mínimo privilegio para ISVs).
• Integración no activa → integration_not_active (409).

Agents — crear y configurar Mets por API

Cierra el ciclo agéntico: ahora puedes crear y configurar Mets por API, no solo ejecutarlos. Con Runs (ejecutar) + Agents (gestionar) + Skills/Functions/Integraciones (equipar), el Met completo es operable por código. Aditivo. 256 → 263 operaciones públicas.

Nuevos endpoints (scopes agents:read / agents:write):

• GET /workspaces/:id/agents — lista los Mets del workspace.
• POST /workspaces/:id/agents — crea un Met (name, title, mission, instructions).
• GET /agents/:id — detalle.
• PATCH /agents/:id — actualiza nombre, instrucciones, misión o estado (active).
• GET /agents/:id/skills — skills vinculadas al Met.
• POST /agents/:id/skills/:skillId — vincula una skill.
• DELETE /agents/:id/skills/:skillId — desvincula.

Diseño: es una fachada curada sobre el modelo interno de Mets — expone un contrato de "agente" limpio (name/instructions/mission) en vez de los item-endpoints crudos. Las skills se listan sin su prompt interno ni su config de conectores. La gestión fina de prompt (bloques, tools deshabilitadas) y los conectores MCP del Met llegan más adelante.

El ciclo completo por API: crear un Met (agents:write) → colgarle skills (agents:write) y conectores (integrations:manage) → ejecutarlo (runs:execute) → enterarte del resultado por webhook. Eso es infraestructura agéntica como servicio.

Funciones IA, Grupos de Mets, Webhooks entrantes, Recordatorios y Actividad

Cierre de huecos detectados cruzando el menú del producto contra la superficie. Aditivo. 215 → 248 operaciones públicas.

Nuevos scopes:

• functions:read / functions:write — Funciones IA (tools/código del Met): CRUD + link a un Met (8 ops).
• agents:read / agents:write — ahora en uso: Grupos de Mets (7 ops). *(La gestión completa de Mets llega con la fachada agents en F1.)*
• webhooks:manage — gestión de webhooks entrantes: CRUD, mappings, link a flujo, sample, rotate-secret (11 ops).
• events:read — feed de actividad/eventos del workspace (3 ops).
• reminders:read / reminders:write — Recordatorios (4 ops).

Notas de curación:

• POST /webhooks/:id/rotate-secret devuelve el secreto nuevo una sola vez (mismo patrón que crear una key) — es el owner rotando su propio secreto de ingress.
• GET /webhooks/:id/sample devuelve un payload de muestra del propio webhook del workspace.

Todavía interno (a propósito):

• Gestión de Mets (crear/configurar Mets) y sus conectores MCP → llegan con la fachada agents en F1 (los Mets son items; se necesita una superficie curada, no decorar item-endpoints). Es el hueco #1 de la visión agéntica, registrado en el plan.