# API REST > Crea links, Smart Links, formularios y páginas Multilink desde tu propio código, y lee su analítica, con las mismas reglas que la app de Walink. La API de Walink permite que un script, un backend o cualquier herramienta sin código que envíe solicitudes HTTP haga lo mismo que tú haces en la app. Cada solicitud pasa por las reglas de la app, así que las direcciones, el cupo y la propiedad se revisan de la misma forma, y cada creación hace un borrador, excepto la de un link gratis, para que nada se publique por accidente. Esta página te lleva hasta tu primera llamada. Todos los endpoints y campos están en la [referencia completa de la API](https://api.walink.com/docs), que también tiene una consola para probar solicitudes. ## Qué puedes automatizar | Recurso | Qué hace la API | | ------------------------------------ | ------------------------------------------------------------------------------------------ | | Links Premium (`/v1/links`) | Listar, crear borradores, editar, publicar, pasar a borrador, eliminar, personalizar el QR | | Smart Links (`/v1/smart-links`) | Lo mismo, con destinos y enrutamiento | | Formularios (`/v1/forms`) | Lo mismo, más las respuestas que envió la gente | | Páginas Multilink (`/v1/multilinks`) | Lo mismo | | Links gratis (`/v1/free-links`) | Listar, crear, leer, eliminar | | Analítica (`/v1/analytics`) | Cifras y desgloses por país, fuente, dispositivo y más | | Cuenta (`/v1/account`) | Perfil, cupo en uso, links gratis que tiene | Cualquier cuenta de Walink puede usar la API. Los borradores son gratis. Publicar usa el cupo de tu suscripción y la analítica necesita una suscripción, igual que en la app. ## Crea un token 1. [Inicia sesión en Walink](https://app.walink.com/login?lang=es), abre el menú de la cuenta (el botón redondo de arriba a la derecha) y selecciona **Desarrolladores**. 2. En **Tokens de API**, selecciona **Crear token**. 3. Ponle un **Nombre**, como "Script de reportes", y elige cuándo vence en **Vence después de**: **30 días**, **90 días**, **1 año** (el valor predeterminado) o **Sin vencimiento**. 4. En **Permisos**, marca solo lo que el token necesita. **Selección rápida** llena **Solo lectura** o **Acceso total**. Los permisos no se pueden cambiar después. 5. Selecciona **Crear token**. La ventana **Guarda tu token** lo muestra una sola vez: cópialo en un lugar seguro, como un administrador de contraseñas, y luego selecciona **Ya lo guardé**. Los tokens empiezan con `wlk_live_`, y una cuenta puede tener 25 tokens activos. En la tabla de tokens, **Rotar** te da un token nuevo con el mismo nombre y los mismos permisos, mientras el anterior sigue funcionando 7 días. **Revocar** detiene un token para siempre, en menos de 30 segundos. ### Permisos `write` incluye `read`. Nada incluye `publish`, `delete` ni `responses:read`: cada uno se concede por separado, y ninguno viene activado de forma predeterminada. | Permiso | Permite | | ------------------------- | ------------------------------------------------------------------------------- | | `links:read` | Leer Links Premium, Smart Links y links gratis | | `links:write` | Crear y editar borradores | | `links:publish` | Publicar, pasar a borrador, editar cualquier cosa publicada, crear links gratis | | `links:delete` | Eliminar | | `forms:*`, `multilinks:*` | Los mismos cuatro para formularios y páginas Multilink | | `account:read` | Perfil, cupo y uso | | `analytics:read` | Analítica | | `responses:read` | Respuestas de formularios, que contienen datos personales que te envió la gente | `analytics:read` y `multilinks:read` también muestran los nombres de tus links, Smart Links y formularios publicados, aun sin su propio permiso de lectura. ## Tu primera solicitud La URL base es `https://api.walink.com/v1`. Envía el token como `Authorization: Bearer ` y los cuerpos de las solicitudes como JSON. Los ejemplos leen el token de una variable de entorno `WALINK_API_TOKEN`, para que quede fuera de tu código. Lista tus Links Premium (necesita `links:read`): ```sh curl https://api.walink.com/v1/links \ -H "Authorization: Bearer $WALINK_API_TOKEN" ``` ```json { "data": [ { "id": "lnk_3f2a9c1e-7b4d-4e8a-9f10-2c6d8e4b1a77", "title": "Tienda Luna orders", "handle": "tienda-luna", "plan": "chat", "status": "published", "url": "https://wa.link/tienda-luna", "created_at": "2026-11-05T14:32:07.000Z", "updated_at": "2026-11-05T14:32:07.000Z" } ], "has_more": false, "next_cursor": null } ``` Las listas van de lo más reciente a lo más antiguo. Aceptan `limit` (25 de forma predeterminada, 100 como máximo) y `cursor`: envía `next_cursor` para obtener la página siguiente. ### Crea un borrador Una creación siempre hace un borrador (necesita `links:write`). Este abre un chat con un número de Estados Unidos: ```sh curl -X POST https://api.walink.com/v1/links \ -H "Authorization: Bearer $WALINK_API_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: tienda-luna-promo-1" \ -d '{ "handle": "tienda-luna-promo", "plan": "chat", "title": "Tienda Luna promo", "phone": "4155550123", "country_code": "1", "country_alpha": "US", "message": "Hello Tienda Luna, I saw your promo" }' ``` La respuesta es `201` con el registro completo, su `id` y `"status": "draft"`. - `handle` es la dirección que va después de `wa.link/`. No se puede cambiar después de crear el link, y un borrador no la aparta: se la queda la primera cuenta que publique con ella. - `plan` es el tipo de link: `chat`, `catalog`, `channel` o `group`. - `Idempotency-Key` hace que un reintento sea seguro durante 24 horas: la misma clave y el mismo cuerpo devuelven la primera respuesta en lugar de un segundo borrador. ## Publica Publicar es una llamada aparte, y necesita `links:publish`: ```sh curl -X POST https://api.walink.com/v1/links/lnk_3f2a9c1e-7b4d-4e8a-9f10-2c6d8e4b1a77/publish \ -H "Authorization: Bearer $WALINK_API_TOKEN" ``` Igual que **Publicar** en la app, usa una unidad de tu cupo de Links Premium ($9 USD al año por link). Sin una unidad libre, la respuesta es `402 pool_exhausted`, con los números en `details`. Agrega cupo en la página de [Facturación](https://app.walink.com/billing?lang=es) de la app ([cómo funciona la facturación](https://walink.com/es/docs/billing)). - `POST .../publish-check` es un ensayo: qué impide todavía la publicación y cuánto cupo usaría. - `POST .../unpublish` saca el link de línea y libera su unidad. Su dirección deja de funcionar, incluidos los códigos QR impresos, y otra cuenta puede tomarla desde ese momento. - `PATCH /v1/links/{id}` cambia solo los campos que envías. En un link publicado el cambio se aplica al instante, así que también necesita `links:publish`. Los Smart Links, los formularios y las páginas Multilink siguen los mismos pasos en sus propias rutas. Los Smart Links usan los permisos de `links`. ## Links gratis en la API `/v1/free-links` crea los links gratis que puede tener cada cuenta, hasta 5. Funcionan distinto: - Un link gratis queda publicado en el momento en que se crea; nunca es borrador. Por eso crear uno necesita `links:publish`, no `links:write`. - Walink elige su dirección aleatoria. Tú envías un número de teléfono o un nombre de usuario de WhatsApp, un mensaje opcional y un `title` privado opcional, que no se puede cambiar después. - Se puede listar, leer y eliminar, nunca editar. Su id empieza con `fln_`, y `/v1/links` nunca lo muestra. - Para editarlo o ver su analítica hay que pasarlo a Premium en la app, lo que cambia su id a `lnk_`. Con 5 ya creados, una creación responde `409 free_link_limit_reached`, y eliminar uno libera su espacio. Más en [links gratis](https://walink.com/es/docs/free-links). ## Errores y límites de uso Todos los errores tienen la misma forma: ```json { "error": { "code": "insufficient_scope", "message": "This token needs the links:publish scope.", "param": null, "doc_url": "https://api.walink.com/docs#description/errors", "request_id": "req_4f1c9a0b7d2e4c8f9a1b3c5d7e9f0a2b", "details": { "required": ["links:publish"] } } } ``` | Estado | Códigos comunes | Significado | | ------ | ------------------------------------------------------------ | --------------------------------------------------------- | | 401 | `invalid_token` | Token faltante, vencido o revocado | | 402 | `pool_exhausted`, `past_due_locked`, `subscription_required` | Cupo o facturación, se resuelve en la app | | 403 | `insufficient_scope` | `details.required` indica el permiso | | 404 | `not_found` | También para ids de otras cuentas | | 409 | `handle_taken`, `free_link_limit_reached` | La dirección está ocupada, o se llegó a un límite | | 422 | `validation_failed`, `handle_immutable` | Solicitud no válida. `details.fields` lista los problemas | | 429 | `rate_limited` | Espera `Retry-After` segundos | | Solicitudes | Límite | | ---------------------------------------------------- | ------------------------ | | Lecturas | 120 por minuto por token | | Creaciones, ediciones, publicaciones y eliminaciones | 30 por minuto por cuenta | | Analítica | 10 por minuto por cuenta | | Revisiones de direcciones | 30 por minuto por cuenta | Los límites son aproximados, y quedarse sin cupo nunca es un `429`. Mediante la API, una cuenta puede tener hasta 500 borradores por producto. Cada respuesta trae un encabezado `Request-Id`: cítalo cuando contactes a soporte. ## Referencia completa - [Referencia de la API](https://api.walink.com/docs): todos los endpoints y campos, con una consola. - [Documento OpenAPI 3.1](https://api.walink.com/openapi.json) y [enumeraciones y límites](https://api.walink.com/v1/reference), sin necesidad de token. - [llms.txt](https://api.walink.com/llms.txt): las reglas de la API, para herramientas de IA. El mismo token también conecta asistentes de IA: consulta [Conecta asistentes de IA](https://walink.com/es/docs/mcp).