API v1

Documentação da API

Crie links curtos e consulte métricas direto do seu sistema, CRM ou automação. A API usa JSON, HTTPS e datas em ISO 8601 (UTC). Base de todas as rotas:

https://admg.si/api/v1

1. Início rápido

Assine um plano com API (Starter ou Pro) e confirme seu e-mail.
No painel, abra API keys e gere uma key. Ela é exibida uma única vez — guarde num gerenciador de segredos.
Crie seu primeiro link:

bash

export ADMGSI_API_KEY="sk_live_..."

curl -X POST https://admg.si/api/v1/links \
  -H "X-API-Key: $ADMGSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://exemplo.com/produto?id=123",
    "source": "instagram",
    "tag": "black-friday"
  }'

2. Autenticação

Envie a key no header X-API-Key em toda requisição. Ela identifica a sua conta: você só enxerga e altera os próprios links.

X-API-Key: sk_live_...

Use a key somente no servidor. Nunca a coloque em código de navegador, app mobile ou repositório público.
Vazou? Revogue em API keys — o efeito é imediato — e gere outra.
Gerenciar keys, billing e dados da conta só é possível pelo painel; a API key cobre links, métricas e consulta da conta.

3. Criar link

POST/links

Campo	Tipo	Descrição
url	string	Obrigatório. Destino `https://`, até 2048 caracteres.
source	string	Opcional. Origem/campanha (1–64 chars) — usada nos relatórios.
tag	string	Opcional. Rótulo livre (1–64 chars), ex. posição do banner.
expires_at	string \| null	Opcional. Data ISO 8601 com fuso (ex. `2026-12-31T23:59:59Z`). Depois dela o link responde 410.
dedupe	boolean	Opcional, padrão `true`: se já existe link ativo com mesma url + source + tag, ele é devolvido em vez de criar outro (não consome quota).

Resposta 201 (link novo) ou 200 com "deduped": true (link reaproveitado):

json

{
  "code": "Ab3xK9q",
  "short_url": "https://admg.si/Ab3xK9q",
  "target_url": "https://exemplo.com/produto?id=123",
  "source": "instagram",
  "tag": "black-friday",
  "status": "active",
  "click_count": 0,
  "unique_count": 0,
  "expires_at": null,
  "created_at": "2026-09-29T14:03:12.481Z",
  "deduped": false
}

O campo status pode vir como pending_review quando o destino precisa de análise (domínio muito novo, TLD de risco). O link passa a redirecionar assim que for aprovado. O destino é imutável: para mudar, crie outro link.

4. Exemplos por linguagem

JavaScript / TypeScript (Node)

// Node 18+ (fetch nativo). Nunca exponha a API key no navegador.
const API = 'https://admg.si/api/v1';
const headers = {
  'X-API-Key': process.env.ADMGSI_API_KEY,
  'Content-Type': 'application/json',
};

async function encurtar(url, { source, tag } = {}) {
  const res = await fetch(`${API}/links`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ url, source, tag }),
  });
  const body = await res.json();
  if (!res.ok) throw new Error(`${body.error.code}: ${body.error.message}`);
  return body; // { short_url, code, status, ... }
}

const link = await encurtar('https://exemplo.com/produto?id=123', { source: 'whatsapp' });
console.log(link.short_url);

Python

# pip install requests
import os
import requests

API = "https://admg.si/api/v1"
HEADERS = {"X-API-Key": os.environ["ADMGSI_API_KEY"]}

def encurtar(url, source=None, tag=None):
    r = requests.post(
        f"{API}/links",
        headers=HEADERS,
        json={"url": url, "source": source, "tag": tag},
        timeout=10,
    )
    body = r.json()
    if not r.ok:
        raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")
    return body

link = encurtar("https://exemplo.com/produto?id=123", source="email")
print(link["short_url"])

PHP

<?php
$ch = curl_init('https://admg.si/api/v1/links');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . getenv('ADMGSI_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['url' => 'https://exemplo.com/produto?id=123']),
]);
$link = json_decode(curl_exec($ch), true);
echo $link['short_url'];

5. Listar links

GET/links

Mais recentes primeiro. Parâmetros opcionais: limit (1–100, padrão 20), cursor, source, tag, status (active | pending_review | disabled) e q (busca no code ou na URL de destino).

bash

# Primeira página (até 100 por página), filtrando por campanha
curl "https://admg.si/api/v1/links?limit=50&source=instagram" \
  -H "X-API-Key: $ADMGSI_API_KEY"

# Próxima página: repita com o next_cursor recebido
curl "https://admg.si/api/v1/links?limit=50&source=instagram&cursor=NEXT_CURSOR" \
  -H "X-API-Key: $ADMGSI_API_KEY"

json

{
  "items": [ { "code": "Ab3xK9q", "short_url": "...", "click_count": 42, ... } ],
  "next_cursor": "MTc1OTE1NDE5MjQ4MXw..."   // null = última página
}

6. Métricas de um link

GET/links/{code}/stats

days (1–365, padrão 30) define a janela da série diária e dos totais; previous traz o período anterior de mesmo tamanho, para comparar tendência.

bash

curl "https://admg.si/api/v1/links/Ab3xK9q/stats?days=7" \
  -H "X-API-Key: $ADMGSI_API_KEY"

json

{
  "code": "Ab3xK9q",
  "click_count": 42,
  "unique_count": 37,
  "first_click_at": "2026-09-22T10:15:00.000Z",
  "last_click_at": "2026-09-29T13:58:41.000Z",
  "series": [ { "date": "2026-09-23", "clicks": 5, "unique": 4 }, ... ],
  "period":   { "clicks": 40, "unique": 35 },
  "previous": { "clicks": 12, "unique": 11 },
  "referrers": [ { "host": "instagram.com", "clicks": 30 }, { "host": null, "clicks": 10 } ],
  "devices": [ { "type": "mobile", "clicks": 33 }, { "type": "desktop", "clicks": 9 } ],
  "hours": [0, 0, 1, ...],      // 24 posições, horário de Brasília
  "weekdays": [3, 8, 6, ...]    // domingo..sábado
  // ...demais campos do link
}

7. Resumo por campanha

GET/stats/summary

Agrupa links e cliques por source ou tag (group_by) no intervalo from–to (ISO 8601; padrão: últimos 30 dias). key: null agrupa links sem source/tag.

bash

curl "https://admg.si/api/v1/stats/summary?group_by=source&from=2026-09-01T00:00:00Z" \
  -H "X-API-Key: $ADMGSI_API_KEY"

json

{
  "from": "2026-09-01T00:00:00.000Z",
  "to": "2026-09-29T14:10:00.000Z",
  "group_by": "source",
  "groups": [
    { "key": "instagram", "links": 12, "clicks": 480, "unique_clicks": 410 },
    { "key": null, "links": 3, "clicks": 20, "unique_clicks": 18 }
  ],
  "totals": { "links": 15, "clicks": 500, "unique_clicks": 428 },
  "top_links": [ { "code": "Ab3xK9q", "short_url": "...", "target_url": "...", "click_count": 42 } ]
}

8. Apagar link

DELETE/links/{code}

Responde 204 sem corpo. O link curto deixa de funcionar e as métricas dele são removidas. Não há como desfazer.

bash

curl -X DELETE https://admg.si/api/v1/links/Ab3xK9q \
  -H "X-API-Key: $ADMGSI_API_KEY"

9. Conta e uso

GET/account

Plano atual, limites e uso do mês (usage.links_this_month, usage.clicks_this_month). Útil para checar a quota antes de um lote grande. O ciclo é o mês-calendário em UTC.

bash

curl https://admg.si/api/v1/account -H "X-API-Key: $ADMGSI_API_KEY"

10. Erros e limites

Todo erro tem o mesmo formato — use o code na sua lógica:

json

{
  "error": {
    "code": "quota_exceeded",
    "message": "Limite de links do plano Starter atingido (500/mês)."
  }
}

HTTP	code	Quando
400	invalid_payload	Corpo ou parâmetro fora do formato (ex. source com mais de 64 chars).
400	invalid_url	URL inválida, sem https://, com usuário/senha ou apontando para rede interna.
400	url_blocked	Destino bloqueado (Safe Browsing ou outro encurtador).
401	unauthorized	API key ausente, inválida ou revogada.
402	quota_exceeded	Limite mensal de links do plano atingido.
403	api_not_allowed	O plano atual não inclui acesso à API.
403	email_not_verified	Confirme o e-mail da conta antes de criar links.
403	account_suspended	Conta suspensa: criação de links bloqueada.
404	not_found	Link não existe ou não pertence à sua conta.
429	rate_limited	Muitas requisições. Aguarde e tente de novo.

Criação de links: até 60 requisições por minuto. Acima disso a resposta é 429 — espere alguns segundos e tente de novo (backoff exponencial).
Quota mensal de links conforme o plano; links já criados nunca param de redirecionar ao atingir o limite.
Em lotes, mantenha dedupe: true para que reenvios após falha de rede não gerem links duplicados.

Link curto https://admg.si/{code}: 302 para o destino, 404 se não existe e 410 se expirou ou foi desativado. Viu um link abusivo? Denuncie.