# l4y.ovh

> Encurtador de links com API REST. Transforma uma URL longa em um
> link curto (https://l4y.ovh/meu-link) que redireciona para o destino
> original e contabiliza os acessos.

## Conceito importante: multi-dominio

O sistema atende varios dominios. O slug e UNICO E GLOBAL: o mesmo
slug responde em TODOS os dominios ativos.

  https://l4y.ovh/exemplo  e  https://abre.ovh/exemplo
  levam ao MESMO destino.

O campo "domain" escolhe apenas qual endereco volta em "short_url".
Nao cria um link separado nem restringe o acesso a esse dominio.

Dominios ativos:
  - l4y.ovh  (padrao)
  - abre.ovh
  - notipay.net

## Autenticacao

Header obrigatorio em toda requisicao:

  X-API-Token: SEU_TOKEN

O token fica em https://l4y.ovh/profile (usuario logado).
SOMENTE pelo cabecalho: ?token= na query string foi removido porque
gravava a credencial em texto puro no log de acesso.

Requisitos da conta: e-mail verificado E permissao de API (individual
ou global). Sem isso toda chamada responde 401.
API global neste momento: HABILITADA.

## Endpoints

Base: https://l4y.ovh/api?action=<acao>
Respostas sempre em JSON. Erros no formato {"error": "descricao"}.

### shorten — cria um link curto

POST https://l4y.ovh/api?action=shorten
Body JSON:
  url    (obrigatorio) URL completa de destino, com http:// ou https://
  slug   (opcional)    apelido desejado: 3-64 caracteres [a-zA-Z0-9_-]
                       sem slug, o sistema gera um numerico de 6 digitos
  domain (opcional)    hostname para exibir no short_url

Exemplo:
  curl -X POST https://l4y.ovh/api?action=shorten \
    -H "X-API-Token: SEU_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"url":"https://exemplo.com/pagina","slug":"promo"}'

Resposta 201:
  {"slug":"promo","short_url":"https://l4y.ovh/promo"}

### list — lista os links

GET https://l4y.ovh/api?action=list
Retorna os links do proprio usuario.
Admin pode usar ?all=1 para ver os de todos os usuarios.

Resposta 200: {"links":[{...}]}, cada item com os campos:
  id            inteiro
  slug          apelido na URL
  original_url  destino do redirect
  short_url     URL curta pronta para uso
  is_custom     true = slug escolhido; false = gerado automaticamente
  domain        dominio exibido, ou null (usa o dominio do acesso)
  clicks        total de acessos
  expires_at    data de expiracao "YYYY-MM-DD HH:MM:SS", ou null
  has_password  true = exige senha do visitante antes do redirect
  qr_code       URL da imagem do QR code
  user_id       dono, ou null se criado por visitante
  created_at, updated_at

### update — altera um link existente

PUT (ou POST) https://l4y.ovh/api?action=update
Body JSON:
  id     (obrigatorio) id do link
  url    (obrigatorio) novo destino
  slug   (opcional)    novo apelido
  domain (opcional)    OMITIR mantem o dominio atual;
                       enviar null volta ao dominio do acesso

Resposta 200: {"slug":"...","short_url":"..."}

### delete — remove um link

DELETE (ou POST) https://l4y.ovh/api?action=delete&id=123
Resposta 200: {"status":"ok"}

### domains — lista os dominios disponiveis

GET https://l4y.ovh/api?action=domains
Resposta 200: {"domains":[{"hostname":"...","scheme":"https","is_default":true}]}
Use antes de mandar "domain" em shorten/update, para nao errar o hostname.

## Codigos de resposta

  200  ok
  201  link criado
  400  action inexistente na URL
  401  token ausente/invalido, conta nao verificada ou API desligada
  403  link de outro usuario, ou link automatico sendo apagado por nao-admin
  404  id nao encontrado
  405  metodo HTTP errado (update: PUT/POST; delete: DELETE/POST)
  422  url invalida, slug fora do padrao, slug em uso, ou dominio nao cadastrado
  429  rate limit excedido — ver cabecalho Retry-After

## Regras e armadilhas comuns

- A URL de destino precisa ser completa e valida, com protocolo.
  "exemplo.com" e rejeitado com 422; use "https://exemplo.com".
- Slug e case-sensitive e deve ter no minimo 3 caracteres.
- Slug ja em uso responde 422: trate o erro e tente outro, em vez de
  assumir que o link foi criado.
- Um usuario comum so edita/apaga os proprios links personalizados.
  Links automaticos (slug numerico) so podem ser apagados por admin.
- Em update, omitir "domain" NAO limpa o campo: mantem o que estava.
- O redirect e 302 (temporario), de proposito: permite trocar o destino
  de um link ja distribuido sem que o navegador sirva do cache.
- Link expirado responde 410; slug inexistente responde 404.
- Rate limit: 60 requisicoes/minuto, das quais no maximo 20 podem ser
  de escrita (shorten/update/delete). Sem token valido: 10/minuto por IP.
  Ao estourar, a resposta e 429 com o cabecalho Retry-After em segundos.
  Respeite o Retry-After em vez de repetir a chamada imediatamente.
  Toda resposta traz X-RateLimit-Limit e X-RateLimit-Remaining.
- Destino aceito: apenas http:// e https://, ate 2000 caracteres.
  Enderecos internos (localhost, 127.0.0.1, 192.168.x, 10.x, 169.254.x)
  sao recusados com 422.

## Paginas

- https://l4y.ovh/        encurtador (uso sem login, slug automatico)
- https://l4y.ovh/docs    documentacao da API em HTML
- https://l4y.ovh/profile token de API do usuario
- https://l4y.ovh/llms.txt este arquivo

Ultima atualizacao: 2026-09-16