API

Crie e faça a gestão de ligações curtas a partir de scripts e aplicações. A API é gratuita. Crie uma chave no seu painel, em Chaves de API, e envie-a como token bearer.

Autenticação

Authorization: Bearer gz_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

As chaves são mostradas uma única vez. Trate-as como palavras-passe: quem tiver a sua chave pode criar e editar ligações na sua conta. Revogue no painel qualquer chave que tenha sido exposta.

Limites

60 pedidos por minuto por chave.
500 novas ligações por dia por conta.
Os destinos são verificados no Google Safe Browsing e na nossa lista de bloqueio. Não é possível usar outros encurtadores de ligações como destino.

Criar uma ligação

curl -X POST https://gozi.to/api/my/links \
  -H "Authorization: Bearer $GOZI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/launch", "code": "launch"}'

code é opcional (4–32 letras, números, - ou _). Deixe-o de fora para obter um código aleatório de 7 caracteres. Resposta 201:

{
  "link": {
    "code": "launch",
    "shortUrl": "https://gozi.to/launch",
    "url": "https://example.com/launch",
    "status": "active",
    "statusReason": null,
    "custom": true,
    "createdAt": 1790000000000,
    "expiresAt": null
  }
}

Listar ligações

GET /api/my/links?limit=25&cursor=<nextCursor>&q=<search>&clicks=1

Mais recentes primeiro. Envie o nextCursor da página anterior para obter a seguinte. clicks=1 acrescenta a contagem de cliques humanos desde sempre.

Obter, editar, eliminar

GET    /api/my/links/{code}
PATCH  /api/my/links/{code}   {"url": "https://new.example"}  or  {"status": "disabled" | "active"}
DELETE /api/my/links/{code}

Estatísticas

GET /api/my/links/{code}/stats

Devolve os cliques humanos dos últimos 90 dias e de sempre, os cliques por dia e os principais países, origens, dispositivos, navegadores e sistemas operativos. Os bots e as pré-visualizações de ligações (Slack, WhatsApp, etc.) são contados à parte em botClicks. Os resultados ficam em cache durante cerca de 5 minutos.

Erros

Os erros usam códigos de estado HTTP e um corpo JSON:

{ "error": { "code": "slug_taken", "message": "That custom link is already taken." } }

400 dados inválidos (invalid_url, invalid_slug, …)
401 chave em falta, inválida ou revogada
409 ligação personalizada já ocupada
422 destino não permitido (destination_blocked)
429 limite por minuto ou diário atingido

Uma descrição legível por máquina de todos os endpoints está em /openapi.json.