Documentação da API v1

Integre o poder da criação e gerenciamento de links da Seul.ink diretamente no seu fluxo de trabalho.

Autenticação

A autenticação é feita através de uma Chave de API (Bearer Token). Você pode gerar e ver sua chave de API pessoal na sua página de Ajustes (disponível para planos Pro e Business).

Todas as requisições à API devem incluir o `Authorization` header, substituindo SUA_CHAVE_API pela sua chave.

Authorization: Bearer SUA_CHAVE_API_AQUI

Limites de Requisição (Rate Limiting)

Para garantir a estabilidade para todos os usuários, aplicamos um limite de requisições por minuto com base no seu plano:

• Plano Pro: 60 requisições / minuto
• Plano Business: 300 requisições / minuto
• Plano Free: Acesso à API não disponível.

Se você exceder esse limite, receberá uma resposta com status 429 Too Many Requests.

Endpoints

POST /api/v1/links.php

Cria um novo link encurtado, QR Code ou adiciona regras avançadas (Geo-Targeting ou Teste A/B) em uma única chamada.

Headers

Header	Valor
Authorization	Bearer SUA_CHAVE_API_AQUI
Content-Type	application/json

Corpo da Requisição (JSON)

Envie um objeto JSON no corpo da sua requisição POST.

{
  "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"
    }
  ]
}

Parâmetros do Corpo

Campo	Tipo	Obrigatório?	Descrição
long_url	string	Sim	A URL de destino principal. Usada como "fallback" se nenhuma regra (Geo/A/B) for atendida.
title	string	Não	Um título interno para você identificar o link no painel.
custom_back_half	string	Não	O "apelido" customizado do link. (ex: seul.ink/meu-link). Se omitido, um código aleatório será gerado.
is_qr	boolean	Não	Defina como true se este link for um QR Code. (Padrão: false).
redirect_type	string	Não	Tipo de redirecionamento. Valores: simple, geo, ab_test. (Padrão: simple).
destinations	array	Não	Obrigatório se redirect_type for geo ou ab_test. Veja abaixo.

O Objeto `destinations`

Para redirect_type: "geo", envie um array de objetos com geo_target (código do país de 2 letras, ex: "BR") e long_url.

Para redirect_type: "ab_test", envie um array de objetos apenas com long_url. O tráfego será dividido entre eles.

Respostas

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

// Resposta 409 Conflict (Apelido já em uso)
{
  "status": "error",
  "message": "O apelido 'promo-outono' já está em uso."
}

Outros Códigos de Status

• 400 Bad Request - JSON malformatado ou campo long_url ausente.
• 401 Unauthorized - Sua Chave de API está inválida ou ausente.
• 402 Payment Required - Você atingiu o limite de links/QR Codes do seu plano atual.
• 403 Forbidden - Seu plano (Free) não tem acesso à API.
• 405 Method Not Allowed - Você tentou usar um método diferente de POST.
• 429 Too Many Requests - Você excedeu seu limite de requisições por minuto.