API Documentation

v1 - REST API Reference

Visao Geral

A API do LinkFlow permite gerenciar grupos, numeros e acessar estatisticas de cliques. Todas as requisicoes usam o prefixo abaixo e retornam JSON.

Base URL

https://linkflow.ideva.ai/api/v1

Formato de Resposta

Sucesso

{
  "success": true,
  "data": {
    "...": "..."
  },
  "meta": {
    "total": 100,
    "page": 1,
    "limit": 50
  }
}

Erro

{
  "success": false,
  "error": "Error message"
}

Autenticacao

Todas as requisicoes devem incluir o header X-API-Key com sua chave de API. Chaves sao geradas no painel em Configuracoes > API Keys.

Header de autenticacao

X-API-Key: lf_sk_abc123_your_secret_key

Permissoes

Cada chave possui permissoes granulares. Configure ao criar a chave no painel.

Escopo	Descricao
groups:read	Listar e visualizar grupos
groups:write	Criar, editar e excluir grupos
numbers:read	Listar e visualizar numeros
numbers:write	Criar, editar e excluir numeros
stats:read	Visualizar estatisticas e logs de cliques
webhooks:read	Listar e visualizar webhooks
webhooks:write	Criar, editar e excluir webhooks

Rate Limits

Limite1.000 requisicoes por hora por chave de API. Headers X-RateLimit-Limit, X-RateLimit-Remaining e Retry-After sao incluidos na resposta.

Grupos

GET/groupsgroups:read

Lista todos os grupos da empresa com estatisticas.

Exemplo

curl -X GET \
  "https://linkflow.ideva.ai/api/v1/groups" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"

Resposta (200)

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Vendas",
      "slug": "vendas",
      "is_active": true,
      "total_numbers": 5,
      "active_numbers": 3,
      "total_clicks": 1250,
      "clicks_today": 42
    }
  ]
}

POST/groupsgroups:write

Cria um novo grupo.

Request Body (JSON)

Parametro	Tipo	Obrigatorio	Descricao
name	string	Sim	Nome do grupo (max 100 chars)
slug	string	Sim	Slug unico para URL (lowercase, hifens)
description	string	Nao	Descricao (max 500 chars)
default_message	string	Nao	Mensagem padrao do WhatsApp (max 1000)
is_active	boolean	Nao	Ativo (default: true)
show_phone	boolean	Nao	Exibir telefone na pagina de redirect (default: true)

Exemplo

curl -X POST \
  "https://linkflow.ideva.ai/api/v1/groups" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"
  -H "Content-Type: application/json" \
  -d '{
  "name": "valor-name",
  "slug": "valor-slug"
}'

Resposta (201)

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Vendas",
    "slug": "vendas",
    "is_active": true,
    "created_at": "2026-01-15T10:00:00Z"
  }
}

GET/groups/:idgroups:read

Retorna detalhes de um grupo com numeros e links.

Exemplo

curl -X GET \
  "https://linkflow.ideva.ai/api/v1/groups/:id" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Vendas",
    "slug": "vendas",
    "numbers": [],
    "links": []
  }
}

PUT/groups/:idgroups:write

Atualiza um grupo existente.

Request Body (JSON)

Parametro	Tipo	Obrigatorio	Descricao
name	string	Nao	Nome do grupo (max 100 chars)
description	string	Nao	Descricao (max 500 chars)
default_message	string	Nao	Mensagem padrao do WhatsApp (max 1000)
is_active	boolean	Nao	Ativo ou inativo
show_phone	boolean	Nao	Exibir telefone na pagina de redirect (default: true)

Exemplo

curl -X PUT \
  "https://linkflow.ideva.ai/api/v1/groups/:id" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"
  -H "Content-Type: application/json" \
  -d '{}'

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Vendas Atualizado",
    "is_active": true
  }
}

DELETE/groups/:idgroups:write

Remove um grupo e seus dados associados.

Exemplo

curl -X DELETE \
  "https://linkflow.ideva.ai/api/v1/groups/:id" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "deleted": true
  }
}

Numeros

GET/numbersnumbers:read

Lista todos os numeros WhatsApp. Filtre por grupo com group_id.

Query Parameters

Parametro	Tipo	Obrigatorio	Descricao
group_id	UUID	Nao	Filtrar por grupo especifico

Exemplo

curl -X GET \
  "https://linkflow.ideva.ai/api/v1/numbers" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"

Resposta (200)

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "phone": "5511999999999",
      "name": "Joao",
      "group_id": "uuid",
      "is_active": true,
      "click_count": 320
    }
  ]
}

POST/numbersnumbers:write

Adiciona um novo numero WhatsApp a um grupo.

Request Body (JSON)

Parametro	Tipo	Obrigatorio	Descricao
phone	string	Sim	Numero WhatsApp (8-20 digitos)
group_id	UUID	Sim	ID do grupo (deve pertencer a empresa)
name	string	Nao	Nome do atendente (max 100)
slug	string	Nao	Slug unico para acesso direto
custom_message	string	Nao	Mensagem personalizada (max 1000)
is_active	boolean	Nao	Ativo (default: true)

Exemplo

curl -X POST \
  "https://linkflow.ideva.ai/api/v1/numbers" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"
  -H "Content-Type: application/json" \
  -d '{
  "phone": "valor-phone",
  "group_id": "uuid-aqui"
}'

Resposta (201)

{
  "success": true,
  "data": {
    "id": "uuid",
    "phone": "5511999999999",
    "name": "Joao",
    "group_id": "uuid",
    "is_active": true
  }
}

GET/numbers/:idnumbers:read

Retorna detalhes de um numero especifico.

Exemplo

curl -X GET \
  "https://linkflow.ideva.ai/api/v1/numbers/:id" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "phone": "5511999999999",
    "name": "Joao",
    "click_count": 320
  }
}

PUT/numbers/:idnumbers:write

Atualiza um numero existente.

Request Body (JSON)

Parametro	Tipo	Obrigatorio	Descricao
phone	string	Nao	Numero WhatsApp (8-20 digitos)
name	string	Nao	Nome do atendente (max 100)
slug	string	Nao	Slug unico para acesso direto
custom_message	string	Nao	Mensagem personalizada (max 1000)
is_active	boolean	Nao	Ativo ou inativo

Exemplo

curl -X PUT \
  "https://linkflow.ideva.ai/api/v1/numbers/:id" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"
  -H "Content-Type: application/json" \
  -d '{}'

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "phone": "5511999999999",
    "name": "Joao Atualizado"
  }
}

DELETE/numbers/:idnumbers:write

Remove um numero.

Exemplo

curl -X DELETE \
  "https://linkflow.ideva.ai/api/v1/numbers/:id" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "deleted": true
  }
}

Estatisticas

GET/statsstats:read

Retorna estatisticas agregadas: cliques totais, distribuicao por dispositivo, ranking de grupos e cliques diarios.

Query Parameters

Parametro	Tipo	Obrigatorio	Descricao
start_date	ISO date	Nao	Inicio do periodo (default: 30 dias atras)
end_date	ISO date	Nao	Fim do periodo (default: hoje)

Exemplo

curl -X GET \
  "https://linkflow.ideva.ai/api/v1/stats" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"

Resposta (200)

{
  "success": true,
  "data": {
    "total_clicks": 5420,
    "period": {
      "start": "2026-01-01",
      "end": "2026-01-31"
    },
    "daily_clicks": [
      {
        "date": "2026-01-01",
        "clicks": 180
      }
    ],
    "device_distribution": [
      {
        "device_type": "mobile",
        "count": 3200,
        "percentage": 59
      }
    ],
    "group_ranking": [
      {
        "group_id": "uuid",
        "group_name": "Vendas",
        "clicks": 2100
      }
    ]
  }
}

GET/stats/clicksstats:read

Retorna log detalhado de cliques com paginacao. Inclui dispositivo, navegador, localizacao e UTM.

Query Parameters

Parametro	Tipo	Obrigatorio	Descricao
page	number	Nao	Pagina (default: 1)
limit	number	Nao	Itens por pagina (default: 50, max: 100)
group_id	UUID	Nao	Filtrar por grupo
start_date	ISO date	Nao	Inicio do periodo
end_date	ISO date	Nao	Fim do periodo

Exemplo

curl -X GET \
  "https://linkflow.ideva.ai/api/v1/stats/clicks" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"

Resposta (200)

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "device_type": "mobile",
      "browser": "Chrome",
      "os": "Android",
      "country": "Brazil",
      "city": "Sao Paulo",
      "created_at": "2026-01-15T14:30:00Z"
    }
  ],
  "meta": {
    "total": 5420,
    "page": 1,
    "limit": 50
  }
}

Webhooks

GET/webhookswebhooks:read

Lista todos os webhooks configurados.

Exemplo

curl -X GET \
  "https://linkflow.ideva.ai/api/v1/webhooks" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"

Resposta (200)

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "url": "https://example.com/hook",
      "events": [
        "click.created"
      ],
      "is_active": true,
      "created_at": "2026-01-15T10:00:00Z"
    }
  ]
}

POST/webhookswebhooks:write

Cria um novo webhook. Payloads sao assinados com HMAC-SHA256.

Request Body (JSON)

Parametro	Tipo	Obrigatorio	Descricao
url	string	Sim	URL de destino (HTTPS recomendado)
events	string[]	Sim	Eventos para escutar (ex: ["click.created"])
secret	string	Nao	Secret para assinatura HMAC-SHA256 (gerado automaticamente se nao informado)
is_active	boolean	Nao	Ativo (default: true)

Exemplo

curl -X POST \
  "https://linkflow.ideva.ai/api/v1/webhooks" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"
  -H "Content-Type: application/json" \
  -d '{
  "url": "valor-url",
  "events": "valor-events"
}'

Resposta (201)

{
  "success": true,
  "data": {
    "id": "uuid",
    "url": "https://example.com/hook",
    "events": [
      "click.created"
    ],
    "is_active": true
  }
}

GET/webhooks/:idwebhooks:read

Retorna detalhes do webhook com entregas recentes.

Exemplo

curl -X GET \
  "https://linkflow.ideva.ai/api/v1/webhooks/:id" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "url": "https://example.com/hook",
    "events": [
      "click.created"
    ],
    "is_active": true,
    "recent_deliveries": [
      {
        "id": "uuid",
        "status": "success",
        "status_code": 200,
        "delivered_at": "2026-01-15T14:30:00Z"
      }
    ]
  }
}

PUT/webhooks/:idwebhooks:write

Atualiza um webhook existente.

Request Body (JSON)

Parametro	Tipo	Obrigatorio	Descricao
url	string	Nao	URL de destino (HTTPS recomendado)
events	string[]	Nao	Eventos para escutar (ex: ["click.created"])
secret	string	Nao	Secret para assinatura HMAC-SHA256 (gerado automaticamente se nao informado)
is_active	boolean	Nao	Ativo ou inativo

Exemplo

curl -X PUT \
  "https://linkflow.ideva.ai/api/v1/webhooks/:id" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"
  -H "Content-Type: application/json" \
  -d '{}'

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "url": "https://example.com/hook",
    "is_active": true
  }
}

DELETE/webhooks/:idwebhooks:write

Remove um webhook.

Exemplo

curl -X DELETE \
  "https://linkflow.ideva.ai/api/v1/webhooks/:id" \
  -H "X-API-Key: lf_sk_abc123_your_secret_key"

Resposta (200)

{
  "success": true,
  "data": {
    "id": "uuid",
    "deleted": true
  }
}

Codigos de Erro

A API usa codigos HTTP padrao. Respostas de erro incluem o campo error com detalhes.

Codigo	Significado
200	OK - Requisicao bem sucedida
201	Created - Recurso criado com sucesso
400	Bad Request - Dados invalidos ou ausentes
401	Unauthorized - API Key ausente ou invalida
403	Forbidden - Permissao insuficiente ou limite do plano
404	Not Found - Recurso nao encontrado
409	Conflict - Slug ou recurso ja existe
429	Too Many Requests - Rate limit excedido
500	Internal Server Error - Erro interno