API de Encurtamento de Links do Linkly
Crie, atualize e gerencie links programaticamente usando a API de Encurtamento de Links do Linkly.
Relacionado: Analytics API | Webhooks
Antes de começar
O Linkly gera solicitações de API na interface para você copiar e colar em seus aplicativos.
Isso funciona para criação de links e atualização de links.
Economize tempo e deixe que fazemos o trabalho pesado:
- 1Veja abaixo as solicitações da API de criação de links.
- 2Copie as solicitações integralmente. Você pode verificar se funcionam para você.
- 3Peça ao ChatGPT ou equivalente para adaptar essas solicitações em código-fonte para seu aplicativo. Não há necessidade de gastar tempo em uma integração complexa. Nossa API é totalmente consumível por máquinas.
Especificação OpenAPI 3.0
Você pode gerar solicitações de API diretamente da interface do usuário do Linkly.
Construtor de API de Encurtamento de Links do Linkly
A API de encurtamento de links do Linkly constrói solicitações de API automaticamente com base no conteúdo do formulário. Você pode colar o texto fornecido aqui em qualquer LLM para gerar automaticamente código para seu aplicativo.
A API do Linkly é documentada usando o padrão OpenAPI, que vai além do que é fornecido abaixo. Os mesmos endpoints também estão disponíveis como uma coleção Postman com um clique.
Visualizar Especificação OpenAPI
Autorização
Você precisará de:
- Sua Chave de API
- ID do Workspace
Você pode obter esses detalhes dentro do Linkly.
- 1Faça login no Linkly.
- 2Clique em Configurações.
- 3Clique em Chaves de API.
Criando ou atualizando um link
Para criar um link, tudo o que você precisa fazer é enviar uma solicitação POST para:
https://app.linklyhq.com/api/v1/link
com os seguintes campos no corpo.
O tipo de codificação é x-www-form-urlencoded ou application/json.
Se você estiver enviando o campo Rules, você deve usar application/json.
Recomendamos que você use JSON com a especificação Open API.
| Rótulo | Chave | Tipo | Notas |
|---|---|---|---|
| Chave de API da Conta | api_key | String | Obrigatório |
| ID do Workspace | workspace_id | Integer | Obrigatório |
| ID do Link | id | Integer | Obrigatório se atualizar link existente |
| Destino | url | String | Obrigatório |
| Apelido | name | String | |
| Notas | note | String | |
| Metadados | metadata | Object | Seus próprios dados de chave-valor, como IDs do seu sistema. Veja metadados |
| Tags de retargeting (região head) | head_tags | String | Para pixels de retargeting |
| Tags de retargeting (região body) | body_tags | String | Para pixels de retargeting |
| Encaminhar Parâmetros | forward_params | Boolean | |
| Ocultar Referenciador | hide_referrer | Boolean | Envia referrer-policy: no-referrer para que o destino não veja o Linkly no cabeçalho referer |
| Mascaramento | cloaking | Boolean | Mascara a URL de destino atrás de um frame |
| Bloquear Bots | block_bots | Boolean | Bloqueia bots/crawlers conhecidos |
| Pular Rastreamento de Crawler Social | skip_social_crawler_tracking | Boolean | Quando block_bots está ativado, ainda permite que crawlers sociais passem para que as visualizações OG funcionem |
| Análise Pública | public_analytics | Boolean | Ativa a página pública /abc123.stats para este link |
| Senha | password | String | Os visitantes devem digitar essa senha antes do redirecionamento |
| Status de Publicação | enabled | Boolean | |
| Fonte UTM | utm_source | String | Para rastreamento UTM |
| Meio UTM | utm_medium | String | Para rastreamento UTM |
| Campanha UTM | utm_campaign | String | Para rastreamento UTM |
| Termo UTM | utm_term | String | Para rastreamento UTM |
| Conteúdo UTM | utm_content | String | Para rastreamento UTM |
| Domínio Personalizado | domain | String | Obrigatório se slug for fornecido. Veja domínios personalizados |
| Sufixo de Domínio Personalizado | slug | String | Se domain for fornecido e slug for nulo, será gerado automaticamente |
| Título Open Graph | og_title | String | Para visualizações de mídia social |
| Descrição Open Graph | og_description | String | Para visualizações de mídia social |
| URL de Imagem Open Graph | og_image | String | Para visualizações de mídia social |
| ID do Meta Pixel | fb_pixel_id | String | Para Meta Pixel |
| ID do TikTok Pixel | tiktok_pixel_id | String | |
| ID do Google Analytics 4 | ga4_tag_id | String | |
| Contêiner do Google Tag Manager | gtm_id | String | |
| Palavras Linkify | linkify_words | String | Frases separadas por quebra de linha que devem ser encurtadas automaticamente nas landing pages |
| Substituições | replacements | String | Regras de substituição de texto aplicadas à página de destino |
| Data/Hora de Expiração | expiry_datetime | String de Data/Hora ISO8601 | Para links com expiração |
| Destino de Expiração | expiry_destination | String (URL) | Para links com expiração. Deve começar com http. |
| Cliques de Expiração | expiry_clicks | Integer | Expirar o link após essa quantidade de cliques |
| Webhooks | webhooks | Array de strings | URLs de webhook por link. Veja webhooks. |
| Notificar IDs de Usuários | notify_user_ids | Array de integers | IDs de usuários do workspace a notificar em cada clique |
| Estilos de Código QR | qr_styles | Objeto JSON | Para estilo de código QR. Chaves: fgColor, bgColor, qrStyle, eyeStyle, eyeColorInner, eyeColorOuter, logoImage, logoWidth, logoHeight, logoPadding, logoStyle, quietZone |
| Regras | rules | Array JSON | Para rotadores, redirecionamentos geo e redirecionamentos de dispositivo |
Exemplo de solicitação usando curl
O código abaixo ilustra como fazer uma solicitação de API para criar um link.
curl -X POST https://app.linklyhq.com/api/v1/link
-H 'cache-control: no-cache'
-d 'api_key=your_secret_key&workspace_id=1&url=http%3A%2F%2Fwww.wikijob.co.uk&name=Test%20Link'
Uma resposta bem-sucedida retornará um objeto JSON representando o link, junto com um id de link.
{
"id": 9512,
"url": "https://www.wikijob.co.uk",
"name": "Test Link",
"note": null,
"metadata": {},
"head_tags": null,
"body_tags": null,
"linkify_words": null,
"replacements": null,
"enabled": true,
"cloaking": false,
"forward_params": false,
"hide_referrer": false,
"block_bots": false,
"skip_social_crawler_tracking": false,
"public_analytics": false,
"password": null,
"domain": null,
"slug": null,
"utm_source": null,
"utm_medium": null,
"utm_campaign": null,
"utm_term": null,
"utm_content": null,
"og_title": null,
"og_description": null,
"og_image": null,
"fb_pixel_id": null,
"tiktok_pixel_id": null,
"ga4_tag_id": null,
"gtm_id": null,
"full_url": "https://l.linklyhq.com/l/2TQ",
"rules": [],
"expiry_datetime": null,
"expiry_destination": null,
"expiry_clicks": null,
"qr_styles": null,
"webhooks": [],
"notify_user_ids": [],
"workspace_id": 1448,
"deleted": false
}
Atualizando um link
Para atualizar um link, envie a mesma solicitação que você usaria para criar um link, mas inclua o campo id para o link que deseja atualizar, bem como as alterações.
Anexando seus próprios dados a um link (metadados)
Use metadata para armazenar seus próprios identificadores em um link, como um ID de pedido, um ID de contato de CRM ou uma referência de campanha de seu próprio sistema. É um conjunto de pares chave-valor, e ele volta sempre que você busca o link e em cada carga útil do webhook (eventos de clique e link), para que você possa corresponder um clique ao registro ao qual pertence.
Envie-o em um corpo de solicitação JSON, como um objeto:
curl -X POST https://app.linklyhq.com/api/v1/link
-H 'Content-Type: application/json'
-d '{"api_key": "your_secret_key", "workspace_id": 1, "url": "https://example.com", "metadata": {"order_id": "A-10293", "crm_contact_id": "3f2b8c1e-9a47-4d0e-b6a5-1c2d3e4f5a6b"}}'
O link na resposta inclui "metadata": {"order_id": "A-10293", "crm_contact_id": "3f2b8c1e-9a47-4d0e-b6a5-1c2d3e4f5a6b"}.
Como funciona:
- As atualizações são mescladas. Quando você atualiza um link, as chaves que você envia são adicionadas aos metadados existentes do link, e as chaves que você não menciona são deixadas em paz. Para remover uma chave, defina-a como
null(por exemplo{"metadata": {"order_id": null}}). - Os valores são strings. Números e booleanos são armazenados como texto, então
42volta como"42". Objetos aninhados e arrays não são permitidos. - Limites. Até 20 chaves por link, chaves até 40 caracteres e valores até 500 caracteres, o suficiente para um UUID.
- Privado para você. Os metadados nunca são mostrados às pessoas que clicam no link, não são usados para construir o redirecionamento e não são adicionados à URL de destino.
- No aplicativo. Você também pode visualizar e editar metadados nas configurações de Automação de um link, em Metadados.
Metadados, notas e parâmetros UTM
Metadados, o campo note e parâmetros UTM todos descrevem um link, mas fazem trabalhos diferentes:
- Metadados são dados estruturados de chave-valor para seus próprios sistemas. Eles são retornados pela API e enviados em webhooks, para que o software possa lê-los.
- Nota é um único campo de texto livre para uma pessoa ler no aplicativo.
- Parâmetros UTM são adicionados à URL de destino, para que a página para a qual você envia visitantes e sua análise possam vê-los. Os metadados nunca são. Para passar um valor para a página de destino, use um parâmetro UTM, ou ative Encaminhar Parâmetros para que parâmetros de consulta no link curto sejam passados adiante.
Metadados e análise
Os metadados não estão incluídos na análise de cliques ou exportações de cliques, e você não pode agrupar ou filtrar cliques, ou pesquisar links, por metadados. Para vincular cliques aos seus próprios registros, use o id do link. Ele aparece em cargas úteis de webhook, em análise discriminada por link e em respostas de link. Procure seu registro a partir do id do link no seu lado, ou busque o link para ler seus metadados.
Criando rotadores via API
Para criar um rotador, envie um campo chamado rules como um array JSON, junto com a carga útil do link acima. Você deve usar application/json para enviar arrays JSON.
Por exemplo:
[
{"what": "rotator", "url": "https://www.microsoft.com", "percentage": "50"},
{"what": "rotator", "url": "https://www.apple.com", "percentage": "50"}
]
Criando redirecionamentos geo via API
Para redirecionar por país, envie um campo chamado rules como um array JSON, junto com a carga útil do link acima. Você deve usar codificação application/json para enviar arrays JSON.
Por exemplo:
[
{"what": "country", "url": "https://www.microsoft.com", "matches": "UK"},
{"what": "country", "url": "https://www.apple.com", "matches": "US"}
]
O país é o código de país ISO 3166 alfa-2.
Criando redirecionamentos de dispositivo via API
Para redirecionar por dispositivo, envie um campo chamado rules como um array JSON, junto com a carga útil do link acima.
Por exemplo:
[
{"what": "platform", "url": "https://www.google.com", "matches": "windows"},
{"what": "platform", "url": "https://www.apple.com", "matches": "ios"}
]
Onde o campo matches é um de:
- ios
- android
- windows
- linux
- mac
Criando ou atualizando múltiplos links em uma solicitação
O Linkly suporta a criação/alteração de até 1000 links por solicitação.
Para fazer isso, envie sua chave de API como parte da solicitação da seguinte forma:
https://app.linklyhq.com/api/v1/links?api_key=XXXXXXXXXXX
Em seguida, use o mesmo schema acima para os casos de link individual, mas envolva as solicitações de link em um array, da forma:
[{link}, {link}]
Aqui está uma solicitação completa que atualizará dois links:
wget --no-check-certificate \
--method POST \
--timeout=0 \
--header 'Content-Type: application/json' \
--body-data '[
{
"workspace_id": "WORKSPACE_ID",
"url": "https://nature.com",
"name": "Test",
"id": LINK_ID
},
{
"workspace_id": "WORKSPACE_ID",
"url": "https://science.com",
"id": LINK_ID
}
]' \
'https://app.linklyhq.com/api/v1/links?api_key=API_KEY'
Isso funciona para ações de criação e atualização.
Esteja ciente de que pode levar até 60 segundos para uma solicitação grande. Se as solicitações levarem mais tempo do que isso, elas falharão, e você deve considerar dividir sua carga de trabalho em chunks menores.
Limites de taxa
A API de encurtamento de links é limitada a 20 solicitações/segundo. Até 200 solicitações por segundo estão disponíveis mediante solicitação. Você pode fazer upload de até 1000 links em uma única solicitação.
Relacionado
- Analytics API - Exporte dados de cliques e relatórios de tráfego
- Webhooks - Notificações de clique em tempo real
- Integração Zapier - Integrações sem código
Disponibilidade do plano
Incluído em todos os planos
Rastreie 500 cliques mensais com todos os recursos incluídos.