API — URLs curtas

Endpoints para criar, redirecionar e consultar analytics de URLs curtas.

---

POST /api/v1/short-urls

Cria uma URL curta para um destino. Se o destino já tem uma URL curta, retorna a existente (deduplicação).

Headers: Authorization: Bearer {token}

Body

{
  "target_path": "/workspaces/produto/issues/FE-7"
}

target_path deve ser um caminho relativo de uma issue válida no CloudTasks.

Response 201 (nova URL) ou 200 (URL existente retornada)

{
  "id": "01J8X...",
  "code": "aB3xK7",
  "target_path": "/workspaces/produto/issues/FE-7",
  "short_url": "https://tasks.cloudface.tech/s/aB3xK7",
  "created_at": "2026-04-18T12:00:00Z"
}

Exemplo

curl -X POST https://tasks.cloudface.tech/api/v1/short-urls \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"target_path": "/workspaces/produto/issues/FE-7"}'

---

GET /s/:code

Redireciona para o destino da URL curta. Registra o clique.

Sem autenticação — endpoint público.

Response 302 — header Location: {target_url}

Se o código não existir: Response 404

Exemplo

curl -I https://tasks.cloudface.tech/s/aB3xK7
# HTTP/1.1 302 Found
# Location: https://tasks.cloudface.tech/workspaces/produto/issues/FE-7

---

GET /api/v1/short-urls/:code/stats

Retorna analytics de uma URL curta. O usuário deve ter acesso ao workspace da issue alvo.

Headers: Authorization: Bearer {token}

Response 200

{
  "code": "aB3xK7",
  "target_path": "/workspaces/produto/issues/FE-7",
  "short_url": "https://tasks.cloudface.tech/s/aB3xK7",
  "stats": {
    "total_clicks": 47,
    "unique_visitors": 23,
    "clicks_last_24h": 8,
    "top_referrers": [
      { "referrer": "https://slack.com", "count": 19 },
      { "referrer": "https://github.com", "count": 12 },
      { "referrer": "(direto)", "count": 16 }
    ],
    "clicks_by_day": [
      { "date": "2026-04-18", "count": 8 },
      { "date": "2026-04-17", "count": 15 },
      { "date": "2026-04-16", "count": 24 }
    ]
  },
  "created_at": "2026-04-15T10:00:00Z"
}

Exemplo

curl https://tasks.cloudface.tech/api/v1/short-urls/aB3xK7/stats \
  -H "Authorization: Bearer {token}"

Formato do código

Os códigos são gerados por codificação Base62 de um ID sequencial interno. Alfabeto: 0-9a-zA-Z. Tamanho: 6–8 caracteres dependendo do volume.

Base62 garante que IDs sequenciais gerem códigos distintos e curtos sem colisões.