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

# Exécutions planifiées

> Exécutez le code de votre application hébergée selon un cron, soit une fois par créneau, soit une fois pour chaque installation.

Une exécution planifiée appelle votre application hébergée selon un cron plutôt qu'en réponse à une requête. Utilisez-en une pour les tâches qu'aucun événement Whop ne déclenche, comme récupérer les nouvelles commandes d'un autre système toutes les 15 minutes ou rapprocher les versements pendant la nuit.

## Définir une planification

Une application dispose de deux planifications. Définissez l'une ou les deux avec [Update app](https://docs.whop.com/fr/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 * * * *"
  }'
```

| Champ | Exécution |
| - | - |
| `schedule` | Une fois par créneau, pour l'application dans son ensemble. |
| `per_install_schedule` | Une fois par créneau pour chaque compte ayant installé l'application. Chaque exécution porte cette installation. Ne peut pas se déclencher plus souvent que toutes les 15 minutes. |

Les deux acceptent une expression cron à cinq champs, interprétée en UTC, d'au plus 64 caractères. L'expression doit se déclencher au moins une fois. `schedule` n'a pas d'intervalle minimal. Envoyez `null` ou une chaîne vide pour supprimer une planification. Une expression invalide renvoie une erreur `400`. La clé doit disposer de `developer:update_app` sur le compte propriétaire de l'application.

## Gérer l'exécution

Exportez `scheduled()` à côté de `fetch()` dans le point d'entrée serveur de votre 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` indique de quelle exécution il s'agit :

| Prop | Valeur |
| - | - |
| `kind` | `global` pour une exécution `schedule`, `install` pour une exécution `per_install_schedule`. |
| `app_installation` | L'installation, sous la forme de l'objet [installation d'application](https://docs.whop.com/fr/api-reference/app-installations/app-installation). `null` lors d'une exécution `global`. |
| `run_id` | ID de l'exécution de ce créneau. Toutes les exécutions des installations dans le même créneau le partagent. |
| `scheduled_at` | Le créneau concerné par l'exécution, sous forme d'horodatage ISO 8601. |
| `attempt` | `1` lors du premier essai, `2` lors de la nouvelle tentative. |

`controller.cron` est l'expression qui a planifié l'exécution, et `controller.scheduledTime` est le créneau en millisecondes depuis l'epoch.

Une exécution utilise le même isolat que vos gestionnaires de requêtes : les secrets et la [clé API injectée](https://docs.whop.com/fr/developer/websites/hosting.md#call-the-whop-api) fonctionnent donc de la même manière. Une exécution peut durer jusqu'à 15 minutes, alors qu'un gestionnaire de requêtes dispose de 30 secondes.

> [!TIP]
>
> Conservez un curseur de synchronisation par installation dans les `metadata` de l'installation, comme décrit dans [Installations d'application](https://docs.whop.com/fr/developer/guides/app-installations.md). Chaque exécution le lit depuis `ctx.props.app_installation.metadata` et réécrit la nouvelle valeur à la fin.

## Nouvelles tentatives et exécutions répétées

Si une exécution échoue, Whop la relance une fois, une minute plus tard, puis l'abandonne. Pour ignorer la nouvelle tentative, appelez `controller.noRetry()` avant de lever une exception. Lors de la nouvelle tentative, `attempt` vaut `2` et `scheduled_at` reste le créneau d'origine.

Le même créneau peut atteindre votre application plusieurs fois, et une nouvelle tentative peut démarrer alors que l'exécution du créneau suivant est déjà en cours. Si votre tâche ne doit pas se produire deux fois, enregistrez chaque exécution terminée sous `run_id` plus `app_installation.id`, et ignorez toute exécution déjà enregistrée.

## Créneaux ignorés

Aucune exécution n'a lieu tant que l'application n'a pas de build web de production avec un point d'entrée serveur. Whop ne met pas en file d'attente un créneau ignoré et ne le rattrape pas plus tard : concevez donc chaque exécution pour qu'elle reprenne là où la précédente s'est arrêtée.

## Journaux

La sortie `console` d'une exécution et ses erreurs non interceptées apparaissent dans les [journaux](https://docs.whop.com/fr/developer/websites/hosting.md#logs) de votre application, à côté de ses requêtes.

## Étapes suivantes

> [card] [Installations d'application](https://docs.whop.com/fr/developer/guides/app-installations.md)
>
> L'installation portée par chaque exécution par installation, et l'endroit où conserver un curseur de synchronisation.

> [card] [Hébergement](https://docs.whop.com/fr/developer/websites/hosting.md)
>
> Builds, secrets, clé API injectée et journaux.
