v1.0•REST API

Documentação da API

Integre o eh.vc com seus sistemas e automatize o gerenciamento de links encurtados.

Introdução

A API do eh.vc permite que você crie, gerencie e analise links encurtados de forma programática. Com ela, você pode integrar o poder do eh.vc diretamente em suas aplicações, sistemas de marketing e fluxos de automação.

Acesso Restrito

O acesso à API está disponível apenas para usuários dos planos Pro e Enterprise.Veja os planos.

URL Base

https://eh.vc/api

Formato das Respostas

Todas as respostas da API são retornadas em formato JSON. Respostas de sucesso incluem um camposuccess: truee os dados no campo data.

{
  "success": true,
  "data": {
    // Dados da resposta
  }
}

Autenticação

A API utiliza chaves de API (API Keys) para autenticação. Você pode criar e gerenciar suas chaves no painel de configurações da sua conta.

Gerando uma API Key

Acesse Configurações > API no seu painel
Clique em "Criar Nova Chave"
Dê um nome descritivo para a chave
Copie e guarde a chave em local seguro (ela só será exibida uma vez)

Usando a API Key

Inclua sua API Key no header Authorization de todas as requisições:

curl -X GET "https://eh.vc/api/links" \
  -H "Authorization: Bearer ehvc_sua_api_key_aqui" \
  -H "Content-Type: application/json"

Segurança

Nunca compartilhe sua API Key ou a inclua em código do lado do cliente (frontend). Se suspeitar que sua chave foi comprometida, revogue-a imediatamente.

Endpoints de Links

POST/api/links

Cria um novo link encurtado.

Parâmetros do Body

Parâmetro	Tipo	Obrigatório	Descrição
`originalUrl`	string	Sim	URL original a ser encurtada
`title`	string	Não	Título descritivo do link
`customCode`	string	Não	Código personalizado (ex: eh.vc/minha-marca)
`expiresAt`	ISO 8601	Não	Data de expiração do link
`password`	string	Não	Senha para proteger o link
`maxClicks`	number	Não	Limite máximo de cliques (1-1.000.000)

Exemplo de Requisição

curl -X POST "https://eh.vc/api/links" \
  -H "Authorization: Bearer ehvc_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "originalUrl": "https://exemplo.com/pagina-longa",
    "title": "Minha Campanha",
    "customCode": "campanha-2026",
    "expiresAt": "2026-12-31T23:59:59Z"
  }'

Exemplo de Resposta

{
  "success": true,
  "data": {
    "id": "abc123-def456-ghi789",
    "shortCode": "campanha-2026",
    "originalUrl": "https://exemplo.com/pagina-longa",
    "title": "Minha Campanha",
    "isActive": true,
    "clickCount": 0,
    "createdAt": "2026-02-15T10:30:00.000Z",
    "expiresAt": "2026-12-31T23:59:59.000Z"
  }
}

GET/api/links

Lista todos os links do usuário com paginação.

Parâmetros de Query

Parâmetro	Tipo	Padrão	Descrição
`page`	number	1	Número da página
`limit`	number	10	Itens por página (máx 100)
`search`	string	-	Busca por título, código ou URL

Exemplo de Requisição

curl -X GET "https://eh.vc/api/links?page=1&limit=10" \
  -H "Authorization: Bearer ehvc_sua_api_key"

Exemplo de Resposta

{
  "success": true,
  "data": {
    "links": [
      {
        "id": "abc123",
        "shortCode": "campanha-2026",
        "originalUrl": "https://exemplo.com",
        "title": "Minha Campanha",
        "isActive": true,
        "clickCount": 150,
        "createdAt": "2026-02-15T10:30:00.000Z",
        "expiresAt": null
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

GET/api/links/:id

Obtém detalhes de um link específico.

Exemplo de Requisição

curl -X GET "https://eh.vc/api/links/abc123-def456" \
  -H "Authorization: Bearer ehvc_sua_api_key"

PUT/api/links/:id

Atualiza um link existente.

Parâmetros do Body

Parâmetro	Tipo	Descrição
`title`	string	Novo título do link
`isActive`	boolean	Ativar ou desativar o link
`expiresAt`	ISO 8601 \| null	Nova data de expiração
`maxClicks`	number \| null	Novo limite de cliques

Exemplo de Requisição

curl -X PUT "https://eh.vc/api/links/abc123-def456" \
  -H "Authorization: Bearer ehvc_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Campanha Atualizada",
    "isActive": true
  }'

DELETE/api/links/:id

Remove um link permanentemente.

Exemplo de Requisição

curl -X DELETE "https://eh.vc/api/links/abc123-def456" \
  -H "Authorization: Bearer ehvc_sua_api_key"

Exemplo de Resposta

{
  "success": true,
  "message": "Link deletado com sucesso"
}

Endpoints de Estatísticas

GET/api/analytics

Obtém estatísticas agregadas dos seus links.

Parâmetros de Query

Parâmetro	Tipo	Padrão	Descrição
`period`	string	7d	Período: 7d, 30d, 90d, all
`linkId`	string	-	ID do link (opcional, filtra por link)

Exemplo de Requisição

curl -X GET "https://eh.vc/api/analytics?period=30d" \
  -H "Authorization: Bearer ehvc_sua_api_key"

Exemplo de Resposta

{
  "success": true,
  "data": {
    "overview": {
      "totalLinks": 25,
      "activeLinks": 20,
      "totalClicks": 1500,
      "uniqueClicks": 1200,
      "avgClicksPerLink": 60
    },
    "charts": {
      "clicksByDay": [
        { "date": "2026-02-01", "clicks": 50 },
        { "date": "2026-02-02", "clicks": 75 }
      ],
      "clicksByCountry": [
        { "name": "Brazil", "value": 1200 },
        { "name": "Portugal", "value": 150 }
      ],
      "clicksByDevice": [
        { "name": "mobile", "value": 900 },
        { "name": "desktop", "value": 500 }
      ],
      "clicksByBrowser": [
        { "name": "Chrome", "value": 800 },
        { "name": "Safari", "value": 400 }
      ]
    },
    "topLinks": [
      {
        "id": "abc123",
        "shortCode": "campanha",
        "title": "Campanha Principal",
        "clickCount": 500
      }
    ],
    "meta": {
      "period": "30d",
      "startDate": "2026-01-16T00:00:00.000Z",
      "endDate": "2026-02-15T23:59:59.000Z"
    }
  }
}

Limites de Taxa

Para garantir a estabilidade do serviço, aplicamos limites de taxa nas requisições da API.

Plano	Requisições/minuto	Requisições/dia
Pro	100	10.000
Enterprise	500	Ilimitado

Cabeçalhos de Limite de Taxa

Cada resposta inclui cabeçalhos indicando seu uso atual:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1708012800

Limite Excedido

Quando o limite é excedido, a API retorna status 429 Too Many Requests. Aguarde até o próximo período para continuar.

Códigos de Erro

A API utiliza códigos HTTP padrão para indicar o sucesso ou falha das requisições.

Código	Significado	Descrição
`200`	OK	Requisição bem-sucedida
`201`	Created	Recurso criado com sucesso
`400`	Bad Request	Parâmetros inválidos ou ausentes
`401`	Unauthorized	API Key inválida ou ausente
`403`	Forbidden	Sem permissão para o recurso ou plano insuficiente
`404`	Not Found	Recurso não encontrado
`409`	Conflict	Conflito (ex: código já em uso)
`429`	Too Many Requests	Limite de requisições excedido
`500`	Internal Error	Erro interno do servidor

Formato de Erro

Respostas de erro incluem uma mensagem descritiva:

{
  "success": false,
  "error": "Autenticação necessária"
}

Precisa de Ajuda?

Nossa equipe está disponível para ajudar com integração e dúvidas técnicas.