API de encurtamento de URL: integre o URLW nas suas aplicações

A API REST URLW permite-lhe integrar a criação, a gestão e a análise de links curtos diretamente nas suas aplicações, scripts ou fluxos de trabalho automatizados. Quer esteja a construir um CRM, uma plataforma de email marketing ou uma ferramenta interna, a API URLW integra-se em poucas linhas de código.

Autenticação por chave API

Todos os pedidos à API URLW devem ser autenticados através de uma chave API transmitida no cabeçalho Authorization. Para obter a sua chave:

1. Ligue-se à sua conta URLW
2. Aceda a Definições → API
3. Clique em "Gerar uma nova chave API"
4. Copie e guarde esta chave num local seguro — só será exibida uma vez

Transmita a sua chave em cada pedido através do cabeçalho HTTP:

Authorization: Bearer A_SUA_CHAVE_API

Nunca exponha a sua chave API em código do lado do cliente (JavaScript front-end, aplicações móveis). Utilize sempre um backend intermediário para as chamadas API.

Primeiros passos: encurtar um URL com curl

Eis como criar o seu primeiro link curto via API URLW com o comando curl:

curl -X POST https://urlw.fr/api/v1/links \
-H "Authorization: Bearer A_SUA_CHAVE_API" \
-H "Content-Type: application/json" \
-d '{
"url": "https://exemplo.com/o-meu-url-de-destino-muito-longo",
"slug": "o-meu-link",
"domain": "go.a-sua-marca.fr"
}'

Resposta em caso de sucesso (HTTP 201):

{
"id": "lnk_abc123",
"short_url": "https://go.a-sua-marca.fr/o-meu-link",
"original_url": "https://exemplo.com/o-meu-url-de-destino-muito-longo",
"slug": "o-meu-link",
"clicks": 0,
"created_at": "2025-06-01T10:00:00Z"
}

Endpoints principais da API URLW

A API URLW expõe os seguintes endpoints REST:

• POST /api/v1/links — Criar um novo link curto
• GET /api/v1/links — Listar os seus links (com paginação)
• GET /api/v1/links/{id} — Recuperar um link pelo seu identificador
• PATCH /api/v1/links/{id} — Modificar um link existente (URL de destino, slug, expiração)
• DELETE /api/v1/links/{id} — Eliminar um link
• GET /api/v1/links/{id}/stats — Obter as estatísticas de cliques de um link
• POST /api/v1/links/batch — Criar vários links num único pedido

A documentação completa, com os parâmetros, os códigos de resposta e exemplos para cada endpoint, está disponível em /pt/docs.

Limites de velocidade e boas práticas

Para garantir a qualidade de serviço para todos os utilizadores, a API URLW aplica limites de velocidade (rate limits) de acordo com o seu plano:

• Plano Starter: 60 pedidos por minuto
• Plano Pro: 300 pedidos por minuto
• Plano Business: 1 000 pedidos por minuto

Quando excede o limite, a API retorna uma resposta HTTP 429 Too Many Requests com um cabeçalho Retry-After indicando o tempo de espera. Implemente um mecanismo de retry com backoff exponencial nas suas aplicações.

Boas práticas para uma integração robusta:

• Utilize o endpoint batch para criar vários links num único pedido em vez de multiplicar as chamadas individuais
• Coloque em cache as respostas da API do lado da aplicação para evitar pedidos a cada visualização
• Trate sistematicamente os códigos de erro HTTP (400, 401, 404, 422, 429, 500) no seu código
• Utilize os webhooks do URLW para receber notificações sobre eventos (clique, expiração) em vez de fazer polling à API

Para começar a utilizar a API, crie a sua conta URLW e consulte a documentação API completa.