Documentação da API

Autenticação

A autenticação usa uma chave de API enviada como Bearer token. Gere e consulte sua chave na página Ajustes (planos Pro e Business). Envie o cabeçalho Authorization em todas as requisições:

Authorization: Bearer SUA_CHAVE_API_AQUI

Trate a chave como uma senha: não a publique em repositórios nem a use em código executado no navegador.

Limites de requisição

Para manter a estabilidade, cada plano tem um limite de requisições por minuto. Ao ultrapassá-lo, a API responde 429 Too Many Requests.

Plano	Requisições por minuto	Acesso à API
Gratuito	—	Não disponível
Pro	60	Incluído
Business	300	Incluído

Criar link

POST/api/v1/links.php

Cria um link curto ou um QR Code e, opcionalmente, adiciona regras avançadas (geotargeting ou teste A/B) na mesma chamada. Se você enviar um link simples com uma long_url que já encurtou antes, a API devolve o link existente em vez de criar outro.

Cabeçalhos

Cabeçalho	Valor
`Authorization`	`Bearer SUA_CHAVE_API_AQUI`
`Content-Type`	`application/json`

Parâmetros do corpo

Campo	Tipo	Obrigatório	Descrição
`long_url`	string	Sim	URL de destino principal. Também é usada como alternativa quando nenhuma regra (geo/A/B) se aplica.
`title`	string	Não	Título interno para identificar o link no painel.
`custom_back_half`	string	Não	Apelido personalizado (ex.: `seul.ink/meu-link`). Se omitido, um código aleatório de 7 caracteres é gerado.
`is_qr`	boolean	Não	Use `true` para criar um QR Code. Padrão: `false`.
`redirect_type`	string	Não	Tipo de redirecionamento: `simple`, `geo` ou `ab_test`. Padrão: `simple`.
`destinations`	array	Condicional	Obrigatório quando `redirect_type` é `geo` ou `ab_test`. Veja abaixo.

O objeto `destinations`

`redirect_type`	Formato de cada item	Comportamento
`geo`	`{ "geo_target": "BR", "long_url": "…" }`	Visitantes do país (código de 2 letras) vão para a URL indicada.
`ab_test`	`{ "long_url": "…" }`	O tráfego é dividido entre as URLs da lista.

Exemplos

curl -X POST "https://seul.ink/api/v1/links.php" \
  -H "Authorization: Bearer SUA_CHAVE_API_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "long_url": "https://meu-ecommerce.com/produto-em-promocao-123",
    "title": "Promoção de Outono (API)",
    "custom_back_half": "promo-outono"
  }'

{
  "long_url": "https://meu-ecommerce.com/produto-em-promocao-123",
  "title": "Promoção de Outono (API)",
  "custom_back_half": "promo-outono",
  "is_qr": false,
  "redirect_type": "geo",
  "destinations": [
    { "geo_target": "BR", "long_url": "https://meu-ecommerce.com/br/promo-outono" },
    { "geo_target": "US", "long_url": "https://meu-ecommerce.com/en/fall-sale" },
    { "geo_target": "PT", "long_url": "https://meu-ecommerce.com/pt/promo-outono" }
  ]
}

const res = await fetch("https://seul.ink/api/v1/links.php", {
  method: "POST",
  headers: {
    "Authorization": "Bearer SUA_CHAVE_API_AQUI",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    long_url: "https://meu-ecommerce.com/produto-em-promocao-123",
    redirect_type: "ab_test",
    destinations: [
      { long_url: "https://meu-ecommerce.com/oferta-a" },
      { long_url: "https://meu-ecommerce.com/oferta-b" }
    ]
  })
});
const data = await res.json(); // data.short_url

Respostas

Respostas de sucesso retornam 201 Created com o link curto gerado.

201 · Link criado

{
  "status": "success",
  "message": "Link criado com sucesso!",
  "short_url": "https://seul.ink/promo-outono",
  "long_url": "https://meu-ecommerce.com/produto-em-promocao-123"
}

201 · Link já existente reaproveitado

{
  "status": "success",
  "message": "Link já encurtado! Usando o código existente.",
  "short_url": "https://seul.ink/promo-outono",
  "long_url": "https://meu-ecommerce.com/produto-em-promocao-123",
  "short_code_reused": true
}

409 · Apelido já em uso

{
  "status": "error",
  "message": "O apelido 'promo-outono' já está em uso."
}

Códigos de status

Em caso de erro, o corpo sempre traz "status": "error" e uma message explicando o motivo.

Código	Significado
201 Created	Link criado (ou link existente reaproveitado).
400 Bad Request	JSON malformado ou `long_url` ausente/inválida.
401 Unauthorized	Chave de API ausente, malformada ou inválida.
402 Payment Required	Limite de links ou QR Codes do seu plano atingido.
403 Forbidden	Seu plano (Gratuito) não tem acesso à API.
405 Method Not Allowed	Método diferente de `POST`.
409 Conflict	O apelido (`custom_back_half`) já está em uso.
429 Too Many Requests	Limite de requisições por minuto excedido.
500 Internal Server Error	Erro inesperado no servidor. Tente novamente.

Autenticação

Limites de requisição

Criar link

Cabeçalhos

Parâmetros do corpo

O objeto destinations

Exemplos

Respostas

Códigos de status

O objeto `destinations`