API URLW em JavaScript: integração completa em Node.js com fetch

Quer esteja a construir um backend Node.js, um worker Cloudflare ou um script de automatização, integrar a API URLW em JavaScript é rápido e sem dependências externas. Eis um guia completo com código pronto a implementar.

Configuração e autenticação

A API URLW autentica-se através de um Bearer token nos cabeçalhos HTTP. Em Node.js, armazene a sua chave API numa variável de ambiente:

# No seu ficheiro .env (nunca versionado!)
URLW_API_KEY=a_sua_chave_api_aqui

// config.js
const URLW_API_BASE = 'https://urlw.fr/api/v1';
const URLW_API_KEY = process.env.URLW_API_KEY;

if (!URLW_API_KEY) {
throw new Error('A variável de ambiente URLW_API_KEY é obrigatória');
}

module.exports = { URLW_API_BASE, URLW_API_KEY };

Encurtar um URL com fetch em Node.js

Eis uma classe UrlwClient completa utilizando a API fetch nativa (disponível em Node.js 18+):

// urlw-client.js
const { URLW_API_BASE, URLW_API_KEY } = require('./config');

class UrlwClient {
constructor(apiKey = URLW_API_KEY) {
this.apiKey = apiKey;
this.baseUrl = URLW_API_BASE;
}

get headers() {
return {
  'Authorization': `Bearer ${this.apiKey}`,
  'Content-Type': 'application/json',
  'Accept': 'application/json',
};
}

async shorten(url, options = {}) {
const body = { url, ...options };

const response = await fetch(`${this.baseUrl}/links`, {
  method: 'POST',
  headers: this.headers,
  body: JSON.stringify(body),
});

if (!response.ok) {
  const error = await response.json().catch(() => ({}));
  throw new Error(
    `Erro API URLW (${response.status}): ${error.message || 'Erro desconhecido'}`
  );
}

return response.json();
}

async getStats(linkId) {
const response = await fetch(`${this.baseUrl}/links/${linkId}/stats`, {
  headers: this.headers,
});

if (!response.ok) {
  throw new Error(`Impossível recuperar as estatísticas: HTTP ${response.status}`);
}

return response.json();
}

async list(page = 1, limit = 50) {
const params = new URLSearchParams({ page, limit });
const response = await fetch(`${this.baseUrl}/links?${params}`, {
  headers: this.headers,
});

if (!response.ok) {
  throw new Error(`Erro ao recuperar os links: HTTP ${response.status}`);
}

return response.json();
}
}

module.exports = UrlwClient;

Exemplo de utilização prática

Eis como utilizar este cliente num script Node.js:

// main.js
const UrlwClient = require('./urlw-client');

async function main() {
const client = new UrlwClient();

try {
// Criar um link curto com um slug personalizado
const link = await client.shorten(
  'https://exemplo.com/artigo-muito-longo-com-parametros?utm_source=newsletter',
  {
    slug: 'artigo-junho',
    domain: 'go.a-sua-marca.fr',
  }
);

console.log('Link curto:', link.short_url);
console.log('ID do link:', link.id);

// Recuperar as estatísticas 24h depois
const stats = await client.getStats(link.id);
console.log(`Cliques: ${stats.total_clicks} (${stats.unique_clicks} únicos)`);

} catch (error) {
console.error('Erro:', error.message);
process.exit(1);
}
}

main();

Gestão de erros e retry automático

Para uma aplicação em produção, implemente um mecanismo de retry com backoff exponencial para gerir erros transitórios e limites de velocidade:

async function withRetry(fn, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
  return await fn();
} catch (error) {
  if (attempt === maxRetries) throw error;

  // Aguardar antes de tentar novamente: 1s, 2s, 4s...
  const delayMs = Math.pow(2, attempt - 1) * 1000;
  console.warn(`Tentativa ${attempt} falhou, nova tentativa em ${delayMs}ms`);
  await new Promise(resolve => setTimeout(resolve, delayMs));
}
}
}

// Utilização
const link = await withRetry(() => client.shorten('https://exemplo.com/pagina'));

Para utilização em TypeScript, as interfaces e tipos da API URLW estão disponíveis na documentação oficial. Para começar, crie a sua conta URLW e gere a sua chave API.