# API REST > Crie links, Smart Links, formulários e páginas Multilink pelo seu próprio código e leia as análises deles, com as mesmas regras do app do Walink. Com a API do Walink, um script, um backend ou qualquer ferramenta no-code que envie requisições HTTP faz o que você faz no app. Toda requisição passa pelas regras do próprio app, então endereços, cota e propriedade são verificados do mesmo jeito, e toda criação gera um rascunho, menos a de um link grátis, para que nada vá ao ar por acidente. Esta página leva você até a primeira chamada. Todos os endpoints e campos estão na [referência completa da API](https://api.walink.com/docs), que também tem um console para testar requisições. ## O que você pode automatizar | Recurso | O que a API faz | | ------------------------------------ | ------------------------------------------------------------------------------------------- | | Links Premium (`/v1/links`) | Listar, criar rascunhos, editar, publicar, voltar para rascunho, excluir, personalizar o QR | | Smart Links (`/v1/smart-links`) | O mesmo, com destinos e roteamento | | Formulários (`/v1/forms`) | O mesmo, mais as respostas que as pessoas enviaram | | Páginas Multilink (`/v1/multilinks`) | O mesmo | | Links grátis (`/v1/free-links`) | Listar, criar, ler, excluir | | Análises (`/v1/analytics`) | Números e detalhamentos por país, origem, dispositivo e mais | | Conta (`/v1/account`) | Perfil, cota em uso, links grátis da conta | Qualquer conta do Walink pode usar a API. Rascunhos são grátis. Publicar usa a cota da sua assinatura e as análises precisam de uma assinatura, como no app. ## Crie um token 1. [Entre no Walink](https://app.walink.com/login?lang=pt), abra o menu da conta (o botão redondo no canto superior direito) e selecione **Desenvolvedores**. 2. Em **Tokens de API**, selecione **Criar token**. 3. Dê um **Nome** a ele, como "Script de relatórios", e escolha o prazo em **Expira após**: **30 dias**, **90 dias**, **1 ano** (o padrão) ou **Sem expiração**. 4. Em **Permissões**, marque só o que o token precisa. **Predefinições rápidas** preenche **Somente leitura** ou **Acesso total**. As permissões não podem ser alteradas depois. 5. Selecione **Criar token**. A janela **Salve seu token** mostra o token uma única vez: copie para um lugar seguro, como um gerenciador de senhas, e selecione **Já salvei**. Os tokens começam com `wlk_live_`, e uma conta pode ter 25 tokens ativos. Na tabela de tokens, **Rotacionar** gera um novo token com o mesmo nome e as mesmas permissões, enquanto o antigo continua funcionando por 7 dias. **Revogar** desativa um token de vez, em até 30 segundos. ### Permissões `write` inclui `read`. Nada inclui `publish`, `delete` ou `responses:read`: cada uma é concedida separadamente, e nenhuma vem ativada por padrão. | Permissão | O que permite | | ------------------------- | ---------------------------------------------------------------------------------- | | `links:read` | Ler Links Premium, Smart Links e links grátis | | `links:write` | Criar e editar rascunhos | | `links:publish` | Publicar, voltar para rascunho, editar qualquer item publicado, criar links grátis | | `links:delete` | Excluir | | `forms:*`, `multilinks:*` | As mesmas quatro para formulários e páginas Multilink | | `account:read` | Perfil, cota e uso | | `analytics:read` | Análises | | `responses:read` | Respostas de formulários, que contêm dados pessoais que as pessoas enviaram a você | `analytics:read` e `multilinks:read` também mostram os nomes dos seus links, Smart Links e formulários publicados, mesmo sem a permissão de leitura de cada um. ## Sua primeira requisição A URL base é `https://api.walink.com/v1`. Envie o token como `Authorization: Bearer ` e os corpos das requisições em JSON. Os exemplos leem o token de uma variável de ambiente `WALINK_API_TOKEN`, para que ele fique fora do seu código. Liste seus Links Premium (precisa de `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 } ``` As listas vêm das mais recentes para as mais antigas. Elas aceitam `limit` (25 por padrão, 100 no máximo) e `cursor`: passe o `next_cursor` para obter a próxima página. ### Crie um rascunho Uma criação sempre gera um rascunho (precisa de `links:write`). Este abre uma conversa com um número dos EUA: ```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" }' ``` A resposta é `201` com o registro completo, seu `id` e `"status": "draft"`. - `handle` é o endereço depois de `wa.link/`. Ele não pode ser alterado depois que o link é criado, e um rascunho não o reserva: a primeira conta que publicar nele fica com ele. - `plan` é o tipo de link: `chat`, `catalog`, `channel` ou `group`. - `Idempotency-Key` torna segura uma nova tentativa durante 24 horas: a mesma chave e o mesmo corpo devolvem a primeira resposta, em vez de um segundo rascunho. ## Publique Publicar é uma chamada à parte, e precisa de `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" ``` Como o **Publicar** do app, ela usa uma unidade da sua cota de Links Premium ($9 USD por ano por link). Sem uma unidade livre, a resposta é `402 pool_exhausted`, com os números em `details`. Aumente a cota na página [Faturamento](https://app.walink.com/billing?lang=pt) do app ([como funciona o faturamento](https://walink.com/pt/docs/billing)). - `POST .../publish-check` é um teste sem efeito: mostra o que ainda impede a publicação e quanta cota ela usaria. - `POST .../unpublish` tira o link do ar e libera a unidade dele. O endereço para de funcionar, inclusive nos QR codes impressos, e outra conta pode então ficar com ele. - `PATCH /v1/links/{id}` muda só os campos que você envia. Em um link publicado a mudança vale na hora, então também precisa de `links:publish`. Smart Links, formulários e páginas Multilink seguem os mesmos passos, cada um no próprio caminho. Os Smart Links usam as permissões de `links`. ## Links grátis na API `/v1/free-links` cria os links grátis que toda conta pode ter, até 5. Eles funcionam de outro jeito: - Um link grátis vai ao ar no momento em que é criado, nunca é um rascunho. Por isso criar um precisa de `links:publish`, não de `links:write`. - O Walink escolhe o endereço aleatório. Você envia um número de telefone ou nome de usuário do WhatsApp, uma mensagem opcional e um `title` privado opcional, que não pode ser alterado depois. - Ele pode ser listado, lido e excluído, nunca editado. O id dele começa com `fln_`, e `/v1/links` nunca o mostra. - Editar o link ou ver as análises dele exige fazer upgrade para Premium no app, o que muda o id para `lnk_`. Com 5 links já criados, uma criação responde `409 free_link_limit_reached`, e excluir um libera a vaga dele. Saiba mais em [links grátis](https://walink.com/pt/docs/free-links). ## Erros e limites de requisições Todo erro tem o mesmo formato: ```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"] } } } ``` | Status | Códigos comuns | Significado | | ------ | ------------------------------------------------------------ | -------------------------------------------------------- | | 401 | `invalid_token` | Token ausente, expirado ou revogado | | 402 | `pool_exhausted`, `past_due_locked`, `subscription_required` | Cota ou cobrança, resolvidas no app | | 403 | `insufficient_scope` | `details.required` informa a permissão | | 404 | `not_found` | Também para ids de outras contas | | 409 | `handle_taken`, `free_link_limit_reached` | O endereço já está em uso, ou um limite foi atingido | | 422 | `validation_failed`, `handle_immutable` | Requisição inválida. `details.fields` lista os problemas | | 429 | `rate_limited` | Aguarde `Retry-After` segundos | | Requisições | Limite | | ------------------------------------------ | ------------------------ | | Leituras | 120 por minuto por token | | Criações, edições, publicações e exclusões | 30 por minuto por conta | | Análises | 10 por minuto por conta | | Verificações de endereço | 30 por minuto por conta | Os limites são aproximados, e ficar sem cota nunca gera um `429`. Pela API, uma conta pode ter até 500 rascunhos por produto. Toda resposta traz um cabeçalho `Request-Id`: informe esse valor quando falar com o suporte. ## Referência completa - [Referência da API](https://api.walink.com/docs): todos os endpoints e campos, com um console. - [Documento OpenAPI 3.1](https://api.walink.com/openapi.json) e [enums e limites](https://api.walink.com/v1/reference), sem precisar de token. - [llms.txt](https://api.walink.com/llms.txt): as regras da API, para ferramentas de IA. O mesmo token também conecta assistentes de IA: veja [Conectar assistentes de IA](https://walink.com/pt/docs/mcp).