# REST API > Crea link, Smart Links, moduli e pagine Multilink dal tuo codice, e leggi le loro statistiche, con le stesse regole dell’app Walink. L’API di Walink permette a uno script, a un backend o a qualsiasi strumento no-code che invia richieste HTTP di fare ciò che fai tu nell’app. Ogni richiesta passa per le regole dell’app, quindi indirizzi, quota e proprietà vengono controllati allo stesso modo, e ogni creazione produce una bozza, tranne nel caso di un link gratis, così nulla va online per sbaglio. Questa pagina ti porta fino alla prima chiamata. Ogni endpoint e ogni campo sono nel [riferimento completo dell’API](https://api.walink.com/docs), che ha anche una console per provare le richieste. ## Cosa puoi automatizzare | Risorsa | Cosa fa l’API | | ----------------------------------- | --------------------------------------------------------------------------------------------------- | | Link Premium (`/v1/links`) | Elencare, creare bozze, modificare, pubblicare, riportare in bozza, eliminare, personalizzare il QR | | Smart Links (`/v1/smart-links`) | Lo stesso, con destinazioni e instradamento | | Moduli (`/v1/forms`) | Lo stesso, più le risposte inviate dalle persone | | Pagine Multilink (`/v1/multilinks`) | Lo stesso | | Link gratis (`/v1/free-links`) | Elencare, creare, leggere, eliminare | | Statistiche (`/v1/analytics`) | Dati e suddivisioni per paese, sorgente, dispositivo e altro | | Account (`/v1/account`) | Profilo, quota in uso, link gratis presenti | Qualsiasi account Walink può usare l’API. Le bozze sono gratis. Pubblicare usa la quota del tuo abbonamento e le statistiche richiedono un abbonamento, come nell’app. ## Crea un token 1. [Accedi a Walink](https://app.walink.com/login?lang=it), apri il menu dell’account (il pulsante rotondo in alto a destra) e seleziona **Developers** (sviluppatori). 2. In **API Tokens**, seleziona **Create token** (crea token). 3. Dagli un **Name** (nome), come "Script dei report", e scegli la scadenza in **Expires after** (scade dopo): **30 days**, **90 days**, **1 year** (il valore predefinito) o **No expiration** (nessuna scadenza). 4. In **Scopes** (ambiti), spunta solo ciò che serve al token. **Quick presets** (preimpostazioni rapide) compila **Read only** (sola lettura) o **Full access** (accesso completo). Gli ambiti non si possono cambiare in seguito. 5. Seleziona **Create token**. La finestra **Save your token** (salva il tuo token) lo mostra una sola volta: copialo in un posto sicuro, come un gestore di password, poi seleziona **I've saved it** (l’ho salvato). I token iniziano con `wlk_live_`, e un account può avere 25 token attivi. Nella tabella dei token, **Rotate** (ruota) ti dà un nuovo token con lo stesso nome e gli stessi ambiti, mentre quello vecchio continua a funzionare per 7 giorni. **Revoke** (revoca) blocca un token definitivamente, entro 30 secondi. ### Ambiti `write` include `read`. Niente include `publish`, `delete` o `responses:read`: ognuno viene concesso a parte, e nessuno è attivo di default. | Ambito | Permette | | ------------------------- | ---------------------------------------------------------------------------------------- | | `links:read` | Leggere Link Premium, Smart Links e link gratis | | `links:write` | Creare e modificare bozze | | `links:publish` | Pubblicare, riportare in bozza, modificare qualsiasi cosa pubblicata, creare link gratis | | `links:delete` | Eliminare | | `forms:*`, `multilinks:*` | Gli stessi quattro per moduli e pagine Multilink | | `account:read` | Profilo, quota e utilizzo | | `analytics:read` | Statistiche | | `responses:read` | Risposte ai moduli, che contengono i dati personali che le persone ti hanno inviato | `analytics:read` e `multilinks:read` mostrano anche i nomi dei tuoi link, Smart Links e moduli pubblicati, anche senza il rispettivo ambito di lettura. ## La tua prima richiesta L’URL di base è `https://api.walink.com/v1`. Invia il token come `Authorization: Bearer ` e i corpi delle richieste in JSON. Gli esempi leggono il token da una variabile d’ambiente `WALINK_API_TOKEN`, così resta fuori dal tuo codice. Elenca i tuoi Link Premium (richiede `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 } ``` Gli elenchi partono dal più recente. Accettano `limit` (25 di default, 100 al massimo) e `cursor`: passa `next_cursor` per avere la pagina successiva. ### Crea una bozza Una creazione produce sempre una bozza (richiede `links:write`). Questa apre una chat con un numero statunitense: ```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 risposta è `201` col record completo, il suo `id` e `"status": "draft"`. - `handle` è l’indirizzo dopo `wa.link/`. Non si può cambiare dopo la creazione del link, e una bozza non lo blocca: lo ottiene il primo account che pubblica con quell’indirizzo. - `plan` è il tipo di link: `chat`, `catalog`, `channel` o `group`. - `Idempotency-Key` rende sicuro un nuovo tentativo per 24 ore: la stessa chiave e lo stesso corpo restituiscono la prima risposta invece di una seconda bozza. ## Pubblica La pubblicazione è una chiamata a parte, e richiede `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" ``` Come **Publish** nell’app, usa un’unità della tua quota di Link Premium ($9 USD all’anno per link). Senza un’unità libera la risposta è `402 pool_exhausted`, coi numeri in `details`. Aggiungi quota nella pagina [Billing](https://app.walink.com/billing?lang=it) dell’app ([come funziona la fatturazione](https://walink.com/it/docs/billing)). - `POST .../publish-check` è una prova a vuoto: cosa blocca ancora la pubblicazione e quanta quota userebbe. - `POST .../unpublish` mette offline il link e libera la sua unità. Il suo indirizzo smette di funzionare, codici QR stampati compresi, e a quel punto un altro account può prenderlo. - `PATCH /v1/links/{id}` cambia solo i campi che invii. In un link pubblicato la modifica è subito online, quindi richiede anche `links:publish`. Smart Links, moduli e pagine Multilink seguono gli stessi passaggi coi propri percorsi. Gli Smart Links usano gli ambiti `links`. ## Link gratis nell’API `/v1/free-links` crea i link gratis che ogni account può avere, fino a 5. Funzionano in modo diverso: - Un link gratis è online dal momento in cui viene creato, mai una bozza. Per questo crearne uno richiede `links:publish`, non `links:write`. - Walink sceglie il suo indirizzo casuale. Tu invii un numero di telefono o un nome utente WhatsApp, un messaggio facoltativo e un `title` privato facoltativo, che non si può cambiare in seguito. - Si può elencare, leggere ed eliminare, mai modificare. Il suo id inizia con `fln_`, e `/v1/links` non lo mostra mai. - Per modificarlo o vedere le sue statistiche bisogna passarlo a Premium nell’app, e questo cambia il suo id in `lnk_`. Se ne hai già 5, una creazione risponde `409 free_link_limit_reached`, ed eliminarne uno libera il suo posto. Maggiori dettagli in [link gratis](https://walink.com/it/docs/free-links). ## Errori e limiti di frequenza Ogni errore ha la stessa 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"] } } } ``` | Stato | Codici comuni | Significato | | ----- | ------------------------------------------------------------ | -------------------------------------------------------- | | 401 | `invalid_token` | Token mancante, scaduto o revocato | | 402 | `pool_exhausted`, `past_due_locked`, `subscription_required` | Quota o fatturazione, da sistemare nell’app | | 403 | `insufficient_scope` | `details.required` indica l’ambito | | 404 | `not_found` | Anche per gli id di altri account | | 409 | `handle_taken`, `free_link_limit_reached` | L’indirizzo è occupato, o è stato raggiunto un limite | | 422 | `validation_failed`, `handle_immutable` | Richiesta non valida. `details.fields` elenca i problemi | | 429 | `rate_limited` | Aspetta i secondi indicati in `Retry-After` | | Richieste | Limite | | --------------------------------------------------- | ------------------------ | | Letture | 120 al minuto per token | | Creazioni, modifiche, pubblicazioni ed eliminazioni | 30 al minuto per account | | Statistiche | 10 al minuto per account | | Controlli degli indirizzi | 30 al minuto per account | I limiti sono approssimativi, ed esaurire la quota non dà mai un `429`. Tramite l’API, un account può avere fino a 500 bozze per prodotto. Ogni risposta ha un’intestazione `Request-Id`: citala quando contatti l’assistenza. ## Riferimento completo - [Riferimento dell’API](https://api.walink.com/docs): ogni endpoint e ogni campo, con una console. - [Documento OpenAPI 3.1](https://api.walink.com/openapi.json) ed [enum e limiti](https://api.walink.com/v1/reference), senza bisogno di un token. - [llms.txt](https://api.walink.com/llms.txt): le regole dell’API, per gli strumenti di IA. Lo stesso token collega anche gli assistenti IA: vedi [Collegare gli assistenti IA](https://walink.com/it/docs/mcp).