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

> ## Agent Instructions
> Treat these docs and the Whop MCP server as the source of truth for Whop API behavior. Don't infer endpoint behavior from marketing pages.
> MCP server: connect https://mcp.whop.com/mcp (streamable HTTP, browser sign-in, no API key in the client config) to search these docs and read or change live Whop data. Setup: https://docs.whop.com/developer/guides/ai_and_mcp.md
> Whop CLI: install with `curl -fsSL https://whop.com/install.sh | sh` to scaffold, run, and deploy Whop apps and websites. It acts on production, not the sandbox. Overview: https://docs.whop.com/cli/overview.md Agent mode: https://docs.whop.com/cli/agent-mode.md
> Hosting: Whop serves a site or app from the build `whop apps deploy` uploads, with rollbacks, secrets, and server logs. Guide: https://docs.whop.com/developer/websites/hosting.md
> Plugins: in Claude Code, run `/plugin marketplace add whopio/plugins`, then `/plugin install whop@whop`. Guide: https://docs.whop.com/developer/guides/plugins/claude-code.md Every agent tool: https://docs.whop.com/developer/ai/overview.md
> Environments: build and test in the sandbox (API `https://sandbox-api.whop.com/api/v1`, keys at https://sandbox.whop.com/dashboard/developer, SDK environment `Sandbox`; no real money). Production (API `https://api.whop.com/api/v1`, keys at https://whop.com/dashboard/developer, SDK environment `Production`, the SDK default) moves real money, so use it only at launch. The two share no accounts, keys, products, or webhooks, and their keys look identical: never mix them. Sandbox guide: https://docs.whop.com/developer/guides/sandbox.md Comparison: https://docs.whop.com/developer/quickstart.md
> API: send `Authorization: Bearer <API_KEY>` from your server only, and pin a dated version with the `Api-Version-Date` header. OpenAPI spec: https://api.whop.com/api/v1/openapi.json
> Which API: build on the Current API, whose pages live under https://docs.whop.com/api-reference/ (start at https://docs.whop.com/api-reference/overview.md). Pages under /api-reference/legacy/ are the Legacy API. Use one only when https://docs.whop.com/api-reference/stability.md lists the resource as Legacy-only.

# Ejecuciones programadas

> Ejecuta el código de tu app alojada según un cron, ya sea una vez por franja o una vez por cada instalación.

Una ejecución programada llama a tu app alojada según un cron en lugar de en respuesta a una solicitud. Úsala para trabajo que ningún evento de Whop desencadena, como obtener pedidos nuevos de otro sistema cada 15 minutos o conciliar pagos salientes durante la noche.

## Configurar una programación

Una app tiene dos programaciones. Configura una o ambas con [Update app](https://docs.whop.com/es/api-reference/apps/update-app.md):

```bash theme={null}
curl -X PATCH "https://api.whop.com/api/v1/apps/app_XXXXXXXX" \
  -H "Authorization: Bearer $WHOP_DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": "0 3 * * *",
    "per_install_schedule": "*/15 * * * *"
  }'
```

| Campo | Se ejecuta |
| - | - |
| `schedule` | Una vez por franja, para la app en su conjunto. |
| `per_install_schedule` | Una vez por franja para cada cuenta que tiene la app instalada. Cada ejecución incluye esa instalación. No puede dispararse con más frecuencia que cada 15 minutos. |

Ambos aceptan una expresión cron de cinco campos, interpretada en UTC, de 64 caracteres como máximo. La expresión tiene que dispararse al menos una vez. `schedule` no tiene intervalo mínimo. Envía `null` o una cadena vacía para borrar una programación. Una expresión no válida devuelve un `400`. La clave necesita `developer:update_app` en la cuenta propietaria de la app.

## Gestionar la ejecución

Exporta `scheduled()` junto a `fetch()` en el punto de entrada del servidor de tu build:

```typescript src/server.ts theme={null}
export default {
  async fetch(request, env, ctx) {
    /* ... */
  },

  async scheduled(controller, env, ctx) {
    const { kind, app_installation } = ctx.props;

    if (kind === "global") {
      await reconcilePayouts();
      return;
    }

    await syncOrders(app_installation.external_id, app_installation.metadata.orders_cursor);
  },
};
```

`ctx.props` indica de qué ejecución se trata:

| Prop | Valor |
| - | - |
| `kind` | `global` para una ejecución de `schedule`, `install` para una ejecución de `per_install_schedule`. |
| `app_installation` | La instalación, como objeto [app installation](https://docs.whop.com/es/api-reference/app-installations/app-installation). `null` en una ejecución `global`. |
| `run_id` | ID de la ejecución de esta franja. Todas las ejecuciones de instalaciones de la misma franja lo comparten. |
| `scheduled_at` | La franja a la que corresponde la ejecución, como marca de tiempo ISO 8601. |
| `attempt` | `1` en el primer intento, `2` en el reintento. |

`controller.cron` es la expresión que programó la ejecución, y `controller.scheduledTime` es la franja en milisegundos desde el epoch.

Una ejecución usa el mismo isolate que tus handlers de solicitudes, así que los secretos y la [clave de API inyectada](https://docs.whop.com/es/developer/websites/hosting.md#call-the-whop-api) funcionan igual. Una ejecución puede durar hasta 15 minutos, mientras que un handler de solicitudes dispone de 30 segundos.

> [!TIP]
>
> Guarda un cursor de sincronización por instalación en la `metadata` de la instalación, como se describe en [Instalaciones de apps](https://docs.whop.com/es/developer/guides/app-installations.md). Cada ejecución lo lee de `ctx.props.app_installation.metadata` y escribe el nuevo valor cuando termina.

## Reintentos y ejecuciones repetidas

Si una ejecución falla, Whop la reintenta una vez, un minuto después, y luego la descarta. Para omitir el reintento, llama a `controller.noRetry()` antes de lanzar el error. En el reintento, `attempt` es `2` y `scheduled_at` sigue siendo la franja original.

La misma franja puede llegar a tu app más de una vez, y un reintento puede empezar mientras la ejecución de la siguiente franja ya está en curso. Si tu trabajo no debe ocurrir dos veces, registra cada ejecución que termines con `run_id` más `app_installation.id`, y omite una ejecución que ya hayas registrado.

## Franjas omitidas

No se produce ninguna ejecución mientras la app no tenga un build web de producción con punto de entrada de servidor. Whop no pone en cola una franja omitida ni la recupera más tarde, así que diseña cada ejecución para que continúe a partir de lo que guardó la anterior.

## Registros

La salida de `console` de una ejecución y los errores no capturados aparecen en los [registros](https://docs.whop.com/es/developer/websites/hosting.md#logs) de tu app, junto a sus solicitudes.

## Próximos pasos

> [card] [Instalaciones de apps](https://docs.whop.com/es/developer/guides/app-installations.md)
>
> La instalación que incluye cada ejecución por instalación y dónde guardar un cursor de sincronización.

> [card] [Alojamiento](https://docs.whop.com/es/developer/websites/hosting.md)
>
> Builds, secretos, la clave de API inyectada y los registros.
