HTTP API · V1

Contrato pequeno. Comportamento previsível.

JSON, criação idempotente e token de gerenciamento para operações privadas. O mesmo contrato atende web e aplicativo.

GET/api/v1/health

Saúde

Confirma disponibilidade da aplicação e do banco de dados.

POST/api/v1/links

Criar link

Cria um endereço curto com idempotência, alias opcional, tags e expiração.

GET/api/v1/aliases/:alias

Verificar alias

Valida o formato e informa se um alias personalizado está disponível.

GET/api/v1/links/:id

Consultar

Retorna os dados de um link usando o token de gerenciamento.

PATCH/api/v1/links/:id

Atualizar

Altera destino, título, tags, expiração ou estado sem trocar o endereço curto.

DELETE/api/v1/links/:id

Excluir

Remove o link e seus eventos associados.

GET/api/v1/links/:id/analytics

Métricas

Retorna acessos totais, períodos, série diária, dispositivos, navegadores, origens e países.

Criar um link

O header Idempotency-Key deve repetir o clientRequestId do corpo.

POST /api/v1/links
Idempotency-Key: req-8e6e32aa
Content-Type: application/json

{
  "destinationUrl": "https://exemplo.com/artigo?utm_source=linkedin",
  "title": "Artigo",
  "customAlias": "artigo",
  "tags": ["conteudo"],
  "expiresAt": "2026-09-15T12:00:00.000Z",
  "clientRequestId": "req-8e6e32aa"
}

Métricas

GET /api/v1/links/:id/analytics
Authorization: Bearer <managementToken>

{
  "totalClicks": 42,
  "clicksToday": 5,
  "clicksLast7Days": 18,
  "clicksLast30Days": 42,
  "dailyClicks": [{ "date": "2026-08-15", "count": 5 }],
  "devices": [{ "label": "Celular", "count": 28 }],
  "referrers": [{ "label": "Direto", "count": 24 }]
}

Abrir especificação OpenAPI →