> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visitoai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Acciones: configuración e historial de ejecuciones

> Descubre acciones configuradas y consulta recibos canónicos de ejecución.

Estos endpoints de solo lectura bajo `/m2m/v1` incluyen integraciones (como Cloudbeds), acciones publicadas de captura, flujos de Sheets y herramientas HTTP. La credencial determina el espacio de trabajo.

| REST | MCP | Permiso |
| - | - | - |
| `GET /actions` | `list_actions` | `actions:read` |
| `GET /actions/{actionId}` | `get_action` | `actions:read` |
| `GET /action-executions` | `list_action_executions` | `action_executions:read` |
| `GET /action-executions/{executionId}` | `get_action_execution` | `action_executions:read` |

## Descubrir definiciones

Sigue `nextCursor` 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.

```http theme={null}
GET /m2m/v1/action-executions?environment=playground&actionId=hospitality.find_options
Authorization: Bearer TU_CLAVE_DE_SERVIDOR
```

Usa `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, usa `includeParameters=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.

```http theme={null}
GET /m2m/v1/action-executions/ejecucion-ejemplo?includeParameters=true
```

Ejemplo sintético:

```json theme={null}
{"version":1,"status":"available","values":{"arrival":"2026-12-01","guests":2,"email":"guest@example.test"},"redacted":0,"omitted":0}
```

`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`.

| REST | MCP | Permiso |
| - | - | - |
| `GET /actions/configurations` | `list_action_configurations` | `action_configurations:read` |
| `GET /actions/{actionId}/configuration` | `get_action_configuration` | `action_configurations:read` |
| `POST /actions` | `create_action` | `actions:write` |
| `PATCH /actions/{actionId}/configuration` | `update_action` | `actions:write` |
| `PATCH /actions/{actionId}/state` | `set_action_state` | `actions:write` |
| `POST /actions/{actionId}/lifecycle` | `change_action_lifecycle` | `actions:write` |
| `DELETE /actions/{actionId}` | `delete_action` | `actions:write` |
| `POST /actions/{actionId}/test` | `test_http_action` | `actions:http:execute` |
| `GET /actions/http/diagnostics` | `list_http_action_diagnostics` | `actions:http:diagnostics:read` |
| `GET /actions/http/diagnostics/{diagnosticId}` | `get_http_action_diagnostic` | `actions:http:diagnostics:read` |

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:

```json theme={null}
{"family":"http","configuration":{"name":"lookup_order","description":"Consultar un pedido cuando se solicite","parameters":{"type":"object","properties":{"order_number":{"type":"string"}},"required":["order_number"]},"endpoint":{"url":"https://example.com/order-status","method":"POST"},"auth":{"type":"none"},"active":false,"readOnly":true,"allowInPlayground":true}}
```

La respuesta usa `{ "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.

| REST anterior | MCP anterior | Actions REST | Actions MCP | Nuevo permiso |
| - | - | - | - | - |
| `GET /tools` | `list_tools` | `GET /actions/configurations?family=http` | `list_action_configurations` | `action_configurations:read` |
| `GET /tools/{toolId}` | `get_tool` | `GET /actions/{actionId}/configuration` | `get_action_configuration` | `action_configurations:read` |
| `POST /tools` | `create_tool` | `POST /actions (family=http)` | `create_action` | `actions:write` |
| `PATCH /tools/{toolId}` | `update_tool` | `PATCH /actions/{actionId}/configuration` | `update_action` | `actions:write` |
| `DELETE /tools/{toolId}` | `delete_tool` | `DELETE /actions/{actionId}` | `delete_action` | `actions:write` |
| `POST /tools/{toolId}/test` | `test_tool` | `POST /actions/{actionId}/test` | `test_http_action` | `actions:http:execute` |
| `GET /tools/logs` | `list_tool_logs` | `GET /actions/http/diagnostics` | `list_http_action_diagnostics` | `actions:http:diagnostics:read` |
| `GET /tools/logs/{logId}` | `get_tool_log` | `GET /actions/http/diagnostics/{diagnosticId}` | `get_http_action_diagnostic` | `actions:http:diagnostics:read` |

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 con `mode: "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:

```http theme={null}
GET /m2m/v1/action-executions/{executionId}?includeInspection=true
```

Requiere **`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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.