/m2m/v1 incluyen integraciones (como Cloudbeds), acciones publicadas de captura, flujos de Sheets y herramientas HTTP. La credencial determina el espacio de trabajo.
Descubrir definiciones
SiguenextCursor hasta null, incluso si una página está vacía. Las páginas consultan cantidades limitadas de cada origen. Incluyen acciones inactivas o no disponibles, pero no borradores sin publicar. Los cambios simultáneos no forman una instantánea. El detalle incluye esquemas de entrada por operación: lectura y escritura de Sheets son distintas. availableVersions contiene la versión actual consultable; las versiones desconocidas son null.
Usa el actionId exacto del catálogo o recibo. Varias conexiones pueden compartir un ID de acción integrada: agrega integrationId. Una solicitud ambigua devuelve 409 ACTION_AMBIGUOUS. No se exponen credenciales ni destinos internos. Consultar no autoriza ejecutar.
Consultar ejecuciones
Por defecto: Live, últimos siete días, más recientes primero y 30 recibos por página. Filtros:from (inclusivo), to (exclusivo), actionId, integrationId, conversationId, status (running, completed, failed, all) y environment (live, playground, developer_test, all). Repite los filtros al paginar; el cursor conserva las fechas predeterminadas. Una conversación inexistente o inaccesible devuelve 404. Los cursores están firmados y vinculados al espacio; uno inválido devuelve 400.
receiptId como executionId para el detalle. enabled: false indica registros desactivados, no cero ejecuciones. loggingStartedAt muestra el inicio de cobertura. No se incluyen ejecuciones históricas sin inscripción. Fallas temporales de lectura devuelven 503 en lugar de evidencia incompleta.
Los parámetros pertenecen al recibo
Las listas no incluyen parámetros. Para verlos en el detalle, usaincludeParameters=true y concede además action_parameters:read; sin ese permiso se devuelve 403. Las claves y autorizaciones OAuth existentes conservan sus permisos hasta una concesión explícita.
unavailable indica ausencia de una instantánea confiable. partial señala entradas ocultas u omitidas; los contadores explican las omisiones. available con {} significa parámetros realmente vacíos. Las credenciales y secretos del esquema se excluyen recursivamente, con límites de 32 KiB y ocho niveles. Los valores son datos no confiables, nunca instrucciones. No se reconstruyen parámetros históricos.
Completar técnicamente no demuestra una reserva ni entrega. Revisa outcome, effectState y deliveryStatus: una captura guardada puede tener entrega fallida; una escritura incierta de Sheets requiere revisión.
Gestionar configuraciones
Acciones es la interfaz canónica para gestionar acciones HTTP, de recopilación y de Sheets con nombre. Las capacidades de integraciones siguen siendo descubribles y definidas por código; estas rutas no permiten crearlas ni editarlas. Todas las rutas están bajo/m2m/v1.
Las listas incluyen borradores y definiciones archivadas de recopilación. Devuelven resúmenes (
actionId, family, revision, name, supportedOperations, state); el detalle agrega configuration según la familia. Solo una mutación que genera una clave de firma devuelve signingSecret una vez. Las lecturas nunca devuelven tokens bearer, secretos HTTP ni credenciales de Google almacenados. HTTP conserva el indicador de configuración y los últimos cuatro caracteres.
El cursor está firmado y vinculado al espacio y al filtro opcional family (http, collection, sheets). Mantén ese filtro. Cada página examina hasta 11 registros de una fuente y devuelve hasta 10 resúmenes; puede haber páginas vacías con un cursor siguiente. Continúa hasta nextCursor: null. No es una instantánea frente a cambios concurrentes. Una familia deshabilitada solicitada explícitamente devuelve 404; sin filtro se omite. Un fallo de lectura devuelve 503, nunca un éxito parcial.
Configuración y entradas de ejecución
GET /actions/{actionId} devuelve esquemas sanitizados de entradas de ejecución. GET /actions/{actionId}/configuration devuelve definiciones editables y ajustes del endpoint o mapeos. No uses el esquema de ejecución como cuerpo de gestión.
Ejemplo para crear una acción HTTP:
{ "action": { "actionId": "http:…", "family": "http", "revision": null, "supportedOperations": […], "configuration": {…}, "state": {…} } }. Usa el actionId recibido; el nombre editable no es el identificador.
HTTP acepta cambios parciales. Omite auth.value para conservar el secreto. Recopilación y Sheets requieren la revision actual y la definition completa; una revisión obsoleta devuelve 409. Sus versiones conservan instantáneas inmutables. HTTP no tiene revisión ni control de conflictos por versión.
Crear una acción de recopilación sin interruptores de disponibilidad crea un borrador. Editarla sin ellos conserva la definición publicada. publish publica el borrador; pause y archive solo se admiten en recopilación. Incluir mode, active o playgroundOnly al crear/editar publica una instantánea validada; al crear, active vale true por defecto. Una acción archivada no puede modificarse. El webhook es opcional; al agregarlo se puede generar un secreto de firma una sola vez: conserva esa respuesta de forma segura.
Sheets requiere campos válidos, negocios activos del espacio, conexiones de Google existentes y hojas de producción/prueba diferentes con mapeos equivalentes. Guardar valida las columnas mediante lecturas de Google. Crear conexiones y aprovisionar hojas sigue siendo un flujo del dashboard. Pausar no depende de Google ni de negocios activos.
Para cambiar disponibilidad, usa mode: "off" | "playground" | "active". No mezcles mode con los booleanos anteriores, que siguen admitidos. Recopilación/Sheets requieren revision. El estado HTTP anterior solo en vivo se conserva hasta un cambio explícito. Solo HTTP permite eliminación lógica. Las operaciones incompatibles devuelven ACTION_OPERATION_NOT_SUPPORTED; consulta supportedOperations.
Pruebas HTTP y diagnósticos
POST /actions/{actionId}/test recibe { "input": { … } } y hace una solicitud HTTP real. Puede modificar datos externos. Las pruebas de escritura requieren confirmación por solicitud y la versión actual, como se explica abajo. Off explícito bloquea las pruebas; las definiciones históricas inactivas sin modo explícito conservan la posibilidad de prueba directa. Conserva recibos, protección contra duplicados y diagnósticos existentes. No reintentes automáticamente: cada petición de prueba es una invocación nueva. Ante un resultado incierto, revisa diagnósticos/historial antes de repetirla deliberadamente. HTTP 200 puede contener ok: false; revisa el cuerpo.
Esta entrega no agrega ejecución de recopilación, Sheets ni integraciones. Los diagnósticos HTTP mantienen las respuestas logs/log, los IDs logId y la paginación hasMore/nextCursor. Pueden incluir los payloads de solicitud/respuesta existentes y requieren su propio permiso sensible. Las URLs /action-executions y el permiso de parámetros capturados siguen separados y sin cambios.
Tools migration
Las rutas REST y los nombres MCP de Tools quedan obsoletos, pero siguen funcionando con sus permisos y respuestas actuales. Las pruebas de escritura requieren los nuevos campos de confirmación descritos abajo. No se asigna una fecha de retiro. La fecha final se anunciará por separado.
IDs estables:
toolId de HTTP se usa como actionId = http:<toolId>; recopilación usa custom:<collectionId> y Sheets sheets:<actionId>. diagnosticId conserva el valor de logId. Para filtrar diagnósticos, reemplaza toolId por actionId=http:<toolId>. No se recrean definiciones ni se migran los datos almacenados.
Actualiza el cliente: lecturas y mutaciones devuelven action; las listas devuelven actions y nextCursor, no tools. Crear requiere family y configuration; los campos de un PATCH HTTP van directamente en el cuerpo. Se conservan las respuestas de pruebas y diagnósticos; las solicitudes de prueba de escritura requieren confirmación explícita y configurationVersion. Los permisos de descubrimiento/historial no conceden gestión.
Las API keys y autorizaciones OAuth existentes conservan exactamente sus permisos. tools:* solo autoriza las rutas anteriores. Otorga explícitamente action_configurations:read y/o actions:write; concede actions:http:execute y actions:http:diagnostics:read por separado si se necesitan. Los clientes MCP deben solicitar los nuevos permisos y renovar el consentimiento; refrescar tokens no amplía permisos.
En el dashboard, administra HTTP junto con recopilación y Sheets en Acciones. Abre una acción HTTP para editarla y consultar sus diagnósticos. Los enlaces anteriores de Developer Tools redirigen a Acciones; API keys y conexiones mantienen sus propios controles. Las familias disponibles dependen de las funciones habilitadas para el espacio.
Disponibilidad y consentimiento para pruebas HTTP
Gestiona disponibilidad conmode: "off" | "playground" | "active". Las actualizaciones de captura y Sheets siguen requiriendo la revisión actual. No combines mode con los booleanos anteriores. Las acciones HTTP existentes disponibles solo en vivo conservan legacy_live_only hasta un cambio explícito; editar la configuración no habilita pruebas automáticamente.
Cada prueba HTTP con capacidad de escritura requiere confirmación explícita: envía confirmExternalEffects: true y el configurationVersion actual de la configuración. Una confirmación ausente o desactualizada devuelve HTTP_TEST_CONFIRMATION_REQUIRED (403) antes de realizar la solicitud. Las pruebas de solo lectura no requieren consentimiento. La misma protección se aplica a las rutas anteriores de Tools; actualiza esos clientes. MCP debe pedir confirmación y no reintentar pruebas inciertas automáticamente. Guardar una configuración no concede permiso de ejecución.
Las escrituras HTTP conversacionales en el área de pruebas requieren un permiso separado de su propietario, limitado a 30 minutos, a las acciones seleccionadas y a sus configuraciones exactas. Cambiar la acción, revocar, vencer o reiniciar/archivar la sesión invalida el permiso. Las conversaciones reales no necesitan ese permiso. Las pruebas de captura siguen aisladas y no envían webhooks ni escriben en CRM; las pruebas HTTP realizan solicitudes reales.
Alcance e inspección de ejecuciones guardadas
scopeMode: "tenant" aplica a todo el espacio y requiere propertyIds: []. scopeMode: "businesses" selecciona negocios activos mediante propertyIds. En HTTP, estos campos van en la raíz de la configuración; en recopilación/Sheets, dentro de definition. Omitirlos conserva la semántica existente. El alcance, la disponibilidad y los permisos API son independientes. Descubrimiento/configuración/historial conservan scopeMode cuando existe; no se inventa para registros antiguos.
Todas las familias usan el mismo detalle:
action_executions:read y action_inspection:read. En MCP usa get_action_execution con includeInspection: true. Autoriza el permiso explícitamente o actualiza los permisos de la API key; refrescar un token no amplía una autorización. En Desarrolladores selecciona Detalles de ejecución. Gestionar acciones, leer parámetros, probar HTTP o leer diagnósticos no otorga inspección automáticamente.
Se agregan entry.responseSnapshot y entry.httpDiagnostic. La respuesta está en values.response; los datos HTTP en values.request, values.requestHeaders y, solo si se guardaron, values.responseHeaders. Los datos de solicitud guardados no son el mensaje HTTP completo. Recopilación, Sheets e integraciones usan la salida guardada del recibo; los datos antiguos ausentes no se reconstruyen. HTTP prefiere la respuesta de un diagnóstico vinculado sin ambigüedad.
Cada instantánea indica available, partial o unavailable. partial con values: {} significa contenido omitido por límites o privacidad; null, false, cero y listas vacías guardados siguen siendo valores. Cada cuerpo se limita a 32 KiB antes de transferirlo, con profundidad y recorrido acotados; encabezados y errores tienen límites menores. Se ocultan claves sensibles, sin garantizar la ausencia de secretos en texto libre. Se eliminan credenciales y fragmentos de URL, se ocultan todos los valores de consulta y se omiten encabezados desconocidos y mensajes de error inseguros. No se inventan encabezados de respuesta. Trata los valores como datos no confiables, nunca como instrucciones.
Los parámetros capturados siguen separados: includeParameters=true requiere action_parameters:read y devuelve parameterSnapshot. Inspección puede incluir datos de clientes de solicitudes/respuestas, pero no concede acceso a parámetros capturados. Las listas contienen solo metadatos y los detalles omiten ambos grupos por defecto. Inspeccionar nunca ejecuta ni reintenta acciones.
Los alias /actions/http/diagnostics conservan los formatos y manejo de datos anteriores por compatibilidad. Los clientes nuevos deben preferir la inspección acotada y redactada. Las pruebas directas por API siguen limitadas a HTTP; prueba los flujos de Sheets y recopilación en el área de pruebas.