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/v11. Início rápido
- Assine um plano com API (Starter, Pro ou Business) e confirme seu e-mail.
- No painel, abra Chaves de API e gere uma chave. 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 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
200com a existente, sem alterá-la. Assim todas as plaquinhas do mesmo cliente ficam juntas. - Repetir o
external_idtambé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/summaryOs 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
| Campo | Tipo | Descrição |
|---|---|---|
| url | string | Obrigatório, exceto no plano Business (sem url = plaquinha sem destino). 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
{
"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)."
}
}| 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; maps.app.goo.gl é aceito). |
| 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. |
| 403 | plan_required | Recurso de outro plano (QR dinâmico, painel do cliente e Google são do Business). |
| 404 | not_found | Link não existe ou não pertence à sua conta. |
| 409 | conflict | Conflito de estado (ex. e-mail já usado por outra empresa da conta). |
| 429 | rate_limited | Muitas requisições. Aguarde e tente de novo. |
| 502 | integration_error | Google 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: truepara 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.