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:

  1. 1
    Veja abaixo as solicitações da API de criação de links.
  2. 2
    Copie as solicitações integralmente. Você pode verificar se funcionam para você.
  3. 3
    Peç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

Executar no Postman

Autorização

Você precisará de:

  • Sua Chave de API
  • ID do Workspace

Você pode obter esses detalhes dentro do Linkly.

  1. 1
    Faça login no Linkly.
  2. 2
    Clique em Configurações.
  3. 3
    Clique em Chaves de API.

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ótuloChaveTipoNotas
Chave de API da Contaapi_keyStringObrigatório
ID do Workspaceworkspace_idIntegerObrigatório
ID do LinkidIntegerObrigatório se atualizar link existente
DestinourlStringObrigatório
ApelidonameString
NotasnoteString
MetadadosmetadataObjectSeus próprios dados de chave-valor, como IDs do seu sistema. Veja metadados
Tags de retargeting (região head)head_tagsStringPara pixels de retargeting
Tags de retargeting (região body)body_tagsStringPara pixels de retargeting
Encaminhar Parâmetrosforward_paramsBoolean
Ocultar Referenciadorhide_referrerBooleanEnvia referrer-policy: no-referrer para que o destino não veja o Linkly no cabeçalho referer
MascaramentocloakingBooleanMascara a URL de destino atrás de um frame
Bloquear Botsblock_botsBooleanBloqueia bots/crawlers conhecidos
Pular Rastreamento de Crawler Socialskip_social_crawler_trackingBooleanQuando block_bots está ativado, ainda permite que crawlers sociais passem para que as visualizações OG funcionem
Análise Públicapublic_analyticsBooleanAtiva a página pública /abc123.stats para este link
SenhapasswordStringOs visitantes devem digitar essa senha antes do redirecionamento
Status de PublicaçãoenabledBoolean
Fonte UTMutm_sourceStringPara rastreamento UTM
Meio UTMutm_mediumStringPara rastreamento UTM
Campanha UTMutm_campaignStringPara rastreamento UTM
Termo UTMutm_termStringPara rastreamento UTM
Conteúdo UTMutm_contentStringPara rastreamento UTM
Domínio PersonalizadodomainStringObrigatório se slug for fornecido. Veja domínios personalizados
Sufixo de Domínio PersonalizadoslugStringSe domain for fornecido e slug for nulo, será gerado automaticamente
Título Open Graphog_titleStringPara visualizações de mídia social
Descrição Open Graphog_descriptionStringPara visualizações de mídia social
URL de Imagem Open Graphog_imageStringPara visualizações de mídia social
ID do Meta Pixelfb_pixel_idStringPara Meta Pixel
ID do TikTok Pixeltiktok_pixel_idString
ID do Google Analytics 4ga4_tag_idString
Contêiner do Google Tag Managergtm_idString
Palavras Linkifylinkify_wordsStringFrases separadas por quebra de linha que devem ser encurtadas automaticamente nas landing pages
SubstituiçõesreplacementsStringRegras de substituição de texto aplicadas à página de destino
Data/Hora de Expiraçãoexpiry_datetimeString de Data/Hora ISO8601Para links com expiração
Destino de Expiraçãoexpiry_destinationString (URL)Para links com expiração. Deve começar com http.
Cliques de Expiraçãoexpiry_clicksIntegerExpirar o link após essa quantidade de cliques
WebhookswebhooksArray de stringsURLs de webhook por link. Veja webhooks.
Notificar IDs de Usuáriosnotify_user_idsArray de integersIDs de usuários do workspace a notificar em cada clique
Estilos de Código QRqr_stylesObjeto JSONPara estilo de código QR. Chaves: fgColor, bgColor, qrStyle, eyeStyle, eyeColorInner, eyeColorOuter, logoImage, logoWidth, logoHeight, logoPadding, logoStyle, quietZone
RegrasrulesArray JSONPara 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
}

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.

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 42 volta 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

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

Disponibilidade do plano

Incluído em todos os planos

Comparar planos →

Rastreie 500 cliques mensais com todos os recursos incluídos.