Pular para o conteúdo

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

  1. Assine um plano com API (Starter, Pro ou Business) e confirme seu e-mail.
  2. No painel, abra Chaves de API e gere uma chave. Ela é exibida uma única vez — guarde num gerenciador de segredos.
  3. 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 Chaves de API — o efeito é imediato — e gere outra.
  • Gerenciar keys, billing e dados da conta só é possível pelo painel; a API key cobre links, workspaces, métricas e consulta da conta.

Empresas (workspaces) e clientes do seu SaaS

Cada empresa cliente da sua agência ou do seu SaaS é um workspace. Uma chave da conta gerencia todos eles. Crie um para cada cliente, se quiser usando o ID do seu sistema como external_id. A chave deve ficar no seu backend, que decide qual cliente pode acessar cada workspace.

POST/workspaces

JSON

{
  "name": "Padaria Bom Dia",
  "external_id": "cliente-123",
  "contact_name": "Ana Souza",
  "trade_name": "Padaria Bom Dia",
  "document": "12.345.678/0001-90",
  "phone": "(11) 99999-0000",
  "email": "[email protected]",
  "address": "Rua das Flores, 10 — São Paulo/SP"
}

Só name é obrigatório. Os campos da empresa (responsável, nome fantasia, CPF/CNPJ, telefone, e-mail e endereço) são opcionais; documento e telefone são guardados só com dígitos. Retorna 201 com o workspace (id, name, external_id, is_default, status, created_at e os campos da empresa). Guarde o id retornado.

  • Mesmo e-mail = mesma empresa. O e-mail é único por conta: um POST com o e-mail de uma empresa que já existe responde 200 com a existente, sem alterá-la. Assim todas as plaquinhas do mesmo cliente ficam juntas.
  • Repetir o external_id também devolve 200 com o existente, inclusive em chamadas simultâneas.

GET/workspaces?limit=100&offset=0

Resposta: items e next_offset (null ao terminar). O filtro external_id localiza o cliente. GET /workspaces/{id} consulta um workspace.

Rotas por cliente

POST   /workspaces/{id}/links
GET    /workspaces/{id}/links
GET    /workspaces/{id}/links/{code}/stats
DELETE /workspaces/{id}/links/{code}
GET    /workspaces/{id}/stats/summary

Os corpos e filtros são os mesmos das rotas de links abaixo. Todas as respostas de link incluem workspace_id. Listas, métricas, exclusão e deduplicação respeitam o workspace. Um workspace de outra conta ou um link de outro workspace retorna 404.

PATCH/workspaces/{id}

JSON

{ "name": "Cliente A", "status": "archived" }

Nome, status e os campos da empresa são opcionais (null limpa um campo). Use active para restaurar. Arquivar bloqueia novos links, preservando redirects e consultas. O workspace Principal não pode ser arquivado (409). Trocar para o e-mail de outra empresa da conta responde 409 conflict. Não há exclusão de workspace.

GET/workspaces/overview

Lista de clientes da conta com os totais por empresa: plaquinhas, plaquinhas ainda sem destino, scans em 30 dias, acessos do cliente, status do Google e da cobrança.

json

{
  "items": [{
    "id": "6f1c…", "name": "Padaria Bom Dia", "email": "[email protected]", ...,
    "plates": 4, "unassigned": 1, "scans_30d": 312, "last_scan_at": "2026-10-03T12:40:00.000Z",
    "users": 1, "users_pending": 0,
    "google_status": "active", "google_rating_avg": 4.7, "google_reviews": 128,
    "charge_status": "active", "charge_value_cents": 9900
  }]
}

Painel do cliente (plano Business): convide o cliente para ver só a própria empresa, em modo leitura, com POST /workspaces/{id}/users { "email": "..." }. Ele recebe o convite por e-mail. Também há GET da lista, reenvio (POST …/users/{userId}/resend) e remoção (DELETE …/users/{userId}), que corta o acesso na hora.

Plano, cobrança, retenção e quotas pertencem à conta e são compartilhados pelos workspaces. As rotas existentes continuam compatíveis: POST /links cria no Principal; GET /links e /stats/summary agregam a conta inteira; consultas e exclusões por code continuam disponíveis para a conta. Para separar clientes, use sempre as rotas com workspace.

3. Criar link

POST/links

CampoTipoDescrição
urlstringObrigatório, exceto no plano Business (sem url = plaquinha sem destino). Destino https://, até 2048 caracteres.
sourcestringOpcional. Origem/campanha (1–64 chars) — usada nos relatórios.
tagstringOpcional. Rótulo livre (1–64 chars), ex. posição do banner.
expires_atstring | nullOpcional. Data ISO 8601 com fuso (ex. 2026-12-31T23:59:59Z). Depois dela o link responde 410.
dedupebooleanOpcional, 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

{
  "workspace_id": "6f1c…",
  "code": "Ab3xK9q",
  "short_url": "https://admg.si/Ab3xK9q",
  "target_url": "https://exemplo.com/produto?id=123",
  "source": "instagram",
  "tag": "black-friday",
  "serial": null,
  "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. Fora do plano Business o destino é imutável: para mudar, crie outro link. No Business ele pode ser trocado (veja abaixo).

QR dinâmico e plaquinhas (plano Business)

Imprima o QR antes de saber o destino e troque para onde ele leva quando quiser, sem reimprimir. Fora do Business estas rotas respondem 403 plan_required. Um link sem destino ainda não redireciona: quem lê o QR vê a página "Link ainda não ativado".

POST/links/reserve

Reserva um lote de 1 a 100 links sem destino (count, e opcionalmente source e tag). Cada um recebe um número sequencial da conta em serial (1, 2, 3…, nunca reaproveitado) para o controle das plaquinhas impressas. Cada plaquinha conta na quota mensal. O lote nasce sem empresa (no workspace Principal); cada plaquinha vai para a empresa na ativação, com PATCH /links/{code} e workspace_id.

bash

curl -X POST https://admg.si/api/v1/links/reserve \
  -H "X-API-Key: $ADMGSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "count": 50, "tag": "lote-outubro" }'
# → 201 { "items": [ { "code": "…", "serial": 101, "target_url": null, ... }, ... ] }

PATCH/links/{code}

Define ou troca o destino (url), move o link para outra empresa (workspace_id) e renomeia (tag). Os três são opcionais. O destino novo passa pelas mesmas verificações da criação e pode voltar em pending_review. Link desativado não muda de destino.

bash

curl -X PATCH https://admg.si/api/v1/links/Ab3xK9q \
  -H "X-API-Key: $ADMGSI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://g.page/r/CQ.../review",
    "workspace_id": "6f1c…",
    "tag": "Balcão"
  }'

GET /links?unassigned=true lista só as plaquinhas ainda sem destino (false = só as com destino). O número da próxima plaquinha é escolhido no painel (Links → "Próxima plaquinha"; rota PATCH /account/plates, que exige login e não aceita API key). Só é aceito um número maior que todos os já emitidos. Para avaliações no Google, use o link "Pedir avaliações" do Perfil da Empresa (g.page/r/…/review) ou o de compartilhar do Maps (maps.app.goo.gl/…). O Google Meu Negócio (avaliações e métricas do perfil) também é do Business e é conectado pelo painel.

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), q (busca no code ou na URL de destino) e unassigned (true = só plaquinhas sem 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)."
  }
}
HTTPcodeQuando
400invalid_payloadCorpo ou parâmetro fora do formato (ex. source com mais de 64 chars).
400invalid_urlURL inválida, sem https://, com usuário/senha ou apontando para rede interna.
400url_blockedDestino bloqueado (Safe Browsing ou outro encurtador; maps.app.goo.gl é aceito).
401unauthorizedAPI key ausente, inválida ou revogada.
402quota_exceededLimite mensal de links do plano atingido.
403api_not_allowedO plano atual não inclui acesso à API.
403email_not_verifiedConfirme o e-mail da conta antes de criar links.
403account_suspendedConta suspensa: criação de links bloqueada.
403plan_requiredRecurso de outro plano (QR dinâmico, painel do cliente e Google são do Business).
404not_foundLink não existe ou não pertence à sua conta.
409conflictConflito de estado (ex. e-mail já usado por outra empresa da conta).
429rate_limitedMuitas requisições. Aguarde e tente de novo.
502integration_errorGoogle ou Asaas recusou ou falhou. A mensagem traz o motivo.
  • 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.