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

# Instalaciones de apps

> Entérate de cuándo una cuenta instala o elimina tu app y vincula cada instalación con el registro al que pertenece en tu propio sistema.

Una instalación de app es una instalación de tu app en una cuenta de Whop. Tu app recibe `app_installation.created` cuando una cuenta la instala y `app_installation.deleted` cuando una cuenta la elimina. Cada instalación también guarda dos valores que solo tu app puede cambiar. `external_id` vincula la instalación con un registro de tu sistema, y `metadata` contiene valores pequeños, como un cursor de sincronización.

## Una tienda online que cobra pagos a través de Whop

Esta guía sigue una app inventada. Market Lane es un creador de tiendas online, y su app de Whop permite que un negocio cobre pagos en su tienda de Market Lane a través de Whop. Cada tienda tiene un identificador, como `river-coffee`, y cada checkout en Market Lane empieza con ese identificador.

Market Lane necesita saber tres cosas:

1. Cuándo un negocio instala la app, para poder conectar la tienda del negocio.
2. Qué cuenta de Whop recibe el pago cuando empieza un checkout en una tienda.
3. Cuándo un negocio elimina la app, para que su tienda deje de ofrecer Whop en el checkout.

**1. Solicita los permisos que necesita tu app**

En los [permisos](https://docs.whop.com/es/developer/guides/permissions.md) de tu app, solicita `checkout_configuration:create` para crear checkouts en la cuenta y `webhook_receive:payments` para enterarte de cuándo se pagan. El negocio aprueba ambos cuando instala la app.

**2. Suscribe el webhook de tu app**

Crea un webhook que pertenezca a tu app, no a tu cuenta: establece `resource_id` con el ID de tu app. Recibe los eventos de instalación de cada cuenta que instala tu app, además de los eventos de pago que esas cuentas concedieron.

```bash theme={null}
curl -X POST "https://api.whop.com/api/v1/webhooks" \
  -H "Authorization: Bearer $WHOP_DEVELOPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://marketlane.example/webhooks/whop",
    "resource_id": "app_XXXXXXXX",
    "events": ["app_installation.created", "app_installation.deleted", "payment.succeeded"]
  }'
```

La clave necesita `developer:manage_webhook` en la cuenta propietaria de la app. Guarda el `webhook_secret` de la respuesta y verifica cada entrega como se describe en [Webhooks](https://docs.whop.com/es/developer/guides/webhooks.md).

Solo los webhooks propios de tu app reciben eventos de instalación. Los webhooks de una cuenta nunca los reciben, ni siquiera para las apps instaladas en esa cuenta.

**3. Conecta la tienda cuando un negocio instala la app**

`app_installation.created` lleva la instalación en `data`. El `account_id` del sobre es el negocio que instaló la app:

```json theme={null}
{
  "type": "app_installation.created",
  "account_id": "biz_J8n2R5p9T1w4Kx",
  "data": {
    "id": "aag_T4k8M2p6W9r3Qx",
    "app": { "id": "app_XXXXXXXX", "name": "Market Lane" },
    "account": { "id": "biz_J8n2R5p9T1w4Kx", "title": "River Coffee" },
    "external_id": null,
    "metadata": {},
    "requesting_reauthorization": false
  }
}
```

Market Lane pregunta al negocio qué tienda conectar. Cuando elige `river-coffee`, Market Lane guarda el identificador en la instalación como `external_id`:

```bash theme={null}
curl -X PATCH "https://api.whop.com/api/v1/app_installations/aag_T4k8M2p6W9r3Qx" \
  -H "Authorization: Bearer $WHOP_APP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "river-coffee",
    "metadata": { "connected_at": "2026-10-26T00:00:00Z" }
  }'
```

**4. Encuentra la cuenta cuando empieza un checkout**

Un comprador hace el checkout en `river-coffee`. La solicitud solo lleva el identificador de la tienda, así que Market Lane busca la instalación por `external_id`:

```bash theme={null}
curl "https://api.whop.com/api/v1/app_installations?external_id=river-coffee" \
  -H "Authorization: Bearer $WHOP_APP_API_KEY"
```

El resultado tiene como máximo una instalación, y su `account.id` es la cuenta que recibe el pago. Market Lane crea un checkout en esa cuenta con `POST /checkout_configurations`, pone su propio ID de pedido en `metadata` y envía al comprador a la `purchase_url`. Market Lane no mantiene ninguna tabla de identificadores de tienda y cuentas de Whop, porque la instalación es la correspondencia.

**5. Marca el pedido como pagado**

`payment.succeeded` llega al mismo webhook. Su `account_id` es el negocio de la tienda y el pago lleva los `metadata` del checkout, así que Market Lane encuentra el pedido por su ID y lo marca como pagado.

**6. Desactiva los pagos de Whop cuando el negocio elimina la app**

`app_installation.deleted` llega en cuanto un negocio elimina tu app. Market Lane deja de ofrecer Whop en el checkout de `river-coffee` de inmediato, para que ningún comprador llegue a un checkout que fallaría. La instalación deja de aparecer en `GET /app_installations` y tu app ya no puede actuar sobre esa cuenta.

**7. Vuelve a conectar al reinstalar**

Si el negocio vuelve a instalar la app, recibes otro `app_installation.created`. Es la misma instalación: el `id`, `created_at`, `external_id` y `metadata` vuelven todos. Market Lane ve `external_id: "river-coffee"` en la carga útil y reactiva los pagos de Whop para esa tienda, sin pedir al negocio que la vuelva a conectar.

## Guarda tu propio ID en una instalación

* **`external_id` es único entre las instalaciones de tu app.** Establecer un valor que ya tiene otra instalación devuelve un `409`, así que dos negocios nunca pueden reclamar la misma tienda. Los valores distinguen mayúsculas y minúsculas: `River-Coffee` y `river-coffee` son distintos.
* **`metadata` se fusiona.** Las claves que envías se establecen, una clave con valor `null` se elimina, las claves que omites no cambian y `{}` borra todas las claves. Los valores son cadenas.
* **Una instalación eliminada conserva su `external_id`.** Mientras un negocio tenga tu app eliminada, ninguna otra instalación de tu app puede tomar ese valor. Si el negocio vuelve a instalar la app, el valor regresa con ella.
* **No guardes secretos.** Tu cuenta de desarrollador puede leer `metadata` y `external_id`.

## Gestionar eventos repetidos

* **Cuenta con repeticiones.** Un negocio puede instalar, eliminar y volver a instalar tu app. Trata un `app_installation.created` de una instalación que ya conoces como una reinstalación.
* **Ignora los duplicados por `webhook-id`.** Whop reintenta las entregas que no obtienen una respuesta `2xx`, y un reintento conserva el mismo `webhook-id`.

## Quién puede leer las instalaciones

| Llamante | Acceso |
| - | - |
| La clave de API de tu app | Lista, obtiene y actualiza las instalaciones de tu app, incluidos `metadata` y `external_id`. La clave necesita `developer:app_installation:read` para leer y `developer:app_installation:update` para actualizar. |
| Tu cuenta de desarrollador | Lista todas las instalaciones de tu app con `GET /app_installations?app_id=app_XXXXXXXX`. Necesita `developer:basic:read`. |
| La cuenta en la que está instalada la app | Lista las apps instaladas en ella. Siempre ve `metadata` y `external_id` como `null`. |

## Próximos pasos

> [card] [Webhooks](https://docs.whop.com/es/developer/guides/webhooks.md)
>
> Verifica firmas, gestiona reintentos y consulta todos los eventos.

> [card] [Referencia de la API de instalaciones de apps](https://docs.whop.com/es/api-reference/app-installations/app-installation)
>
> Todos los campos y endpoints de las instalaciones de apps.

> [card] [Aceptar pagos](https://docs.whop.com/es/developer/guides/accept-payments.md)
>
> Crea checkouts y entrega pedidos a partir de `payment.succeeded`.

> [card] [Permisos](https://docs.whop.com/es/developer/guides/permissions.md)
>
> Declara los permisos que tu app solicita al instalarse.


## Related topics

- [Ejecuciones programadas](https://docs.whop.com/es/developer/guides/scheduled-runs.md)
- [Webhooks](https://docs.whop.com/es/developer/guides/webhooks.md)
- [API de App Installations](https://docs.whop.com/es/api-reference/app-installations/app-installation.md)
