A API de integração do Plid.in possibilita que você encurte url's através de sua aplicação. Para utilizar a API, você deve efetuar seu cadastro no Plid.in.
 

Chave da API

Para autenticar um usuário no plid.in, você deve fornecer a chave da API juntamente com cada requisição ao plid.in. Obtenha sua chave logando no plid.in e acessando o menu Desenvolvedor. ?key=CHAVE_DA_API_AQUI

 

Ações

Ações são transmitidas como um segmento na URL. Estas são as Ações disponíveis:

shorten - Encurta a URL
lookup - Busca o destino da URL encurtada

As ações aceitam argumentos, os quais são passados como parâmetros GET OU POST. Veja os terminais da API abaixo para mais informações sobre as ações.

 

Tipo de resposta

A API retorna em texto simples ou json. O tipo resposta pode ser definido utilizando o argumento response_type na requisição. Se este argumento não é definido, o tipo de resposta será padronizado para plain_text ou json dependendo do terminal utilizado.

Exemplo de respostas json:


{
   "action": "shorten",
   "result": "https://plid.in/exemplo"
}

{
   "action":"lookup",
   "result":{
      "long_url":"https:\/\/www.platon.com.br\/",
      "created_at":{
         "date":"2018-11-23 17:23:14.000000",
         "timezone_type":3,
         "timezone":"America\/Sao_Paulo"
      },
      "clicks":0,
      "updated_at":{
         "date":"2018-11-23 17:23:14.000000",
         "timezone_type":3,
         "timezone":"America\/Sao_Paulo"
      }
   }
}

Exemplo de resposta em texto simples:

https://plid.in/exemplo

https://www.platon.com.br/

 

Terminais da API

Todas as requisições da API começarão com a url: https://plid.in/api/v2/


https://plid.in/api/v2/action/shorten

Argumentos:

  • url: a URL a encurtar
  • custom_ending (opcional): Um final personalizado para a URL encurtada.
  • is_secret (opcional): se a url deve ser secreta ou não. O padrão é falso. Ex true ou false

Resposta: Uma representação JSON ou texto simples da URL encurtada.

Exemplo: GET https://plid.in/api/v2/action/shorten?key=CHAVE_DA_API_AQUI&url=URL_A_ENCURTAR_AQUI&custom_ending=FINAL_DA_URL_PERSONALIZADA_AQUI&is_secret=false

Reposta:

{
   "action":"shorten",
   "result":"https:\/\/plid.in\/4Jbpu"
}

O argumento url deve ser uma URL válida.

https://plid.in/api/v2/action/shorten_bulk


Somente POST

Argumentos:

  • data: Uma string contendo um objeto JSON com um array de links

Exemplificando o argumento data:
{
   "links": [
      {
         "url": "https://platon.com.br"
      },
      {
         "url": "http://construtor.platon.com.br/pt/brand/879/",
         "is_secret": true
      },
      {
         "url": "https://webmail.platon.com.br",
         "custom_ending": "mail"
      }
   ]
}

Resposta: Um objeto JSON com uma lista de links encurtados

Exemplo de resposta:
{
   "action": "shorten_bulk",
   "result": {
      "shortened_links": [
         {
            "long_url": "https://platon.com.br",
            "short_url": "https://plid.in/vjlbu"
         },
         {
            "long_url": "http://construtor.platon.com.br/pt/brand/879/",
            "short_url": "https://plid.in/x8PVz/bdd2"
         },
         {
            "long_url": "https://webmail.platon.com.br",
            "short_url": "https://plid.in/mail"
         }
      ]
   }
}


https://plid.in/api/v2/action/lookup

A ação lookup recebe um único argumento: url_ending. Esta é a url a verificar a disponibilidade. Se já exixte, a API restornará o destino da URL. Se não existe, a API retornará com o status 404(Não encontrado).

Argumentos:

  • url_ending: A parte final do link que deseja procurar. Ex: Para procurar a url plid.in/exemplo, o argumento url_ending recebe apenas exemplo
  • url_key (opcional): chave do final da URL para pesquisas de URLs secretas

Exemplo GET https://plid.in/api/v2/action/lookup?key=CHAVE_DA_API_AQUI&url_ending=FINAL_DA_URL_AQUI&response_type=json

Exemplo de resposta:

{
   "action":"lookup",
   "result":{
      "long_url":"https:\/\/www.platon.com.br\/",
      "created_at":{
         "date":"2018-11-23 17:23:14.000000",
         "timezone_type":3,
         "timezone":"America\/Sao_Paulo"
      },
      "clicks":1,
      "updated_at":{
         "date":"2018-11-23 18:01:48.000000",
         "timezone_type":3,
         "timezone":"America\/Sao_Paulo"
      }
   }
}

 

https://plid.in/api/v2/data/link

Argumentos:

  • url_ending: A parte final do link que deseja procurar
  • left_bound: O início do intervalo de data. Ex: 2018-11-20 15:00:00
  • right_bound: O final do intervalo de data. Ex: 2018-11-26 18:00:00
  • stats_type: o tipo de dado a buscar
    • day: conta os cliques do link por dia entre o intervalo de data definido
    • country: contagem de cliques por país
    • referer: conatgem de cliques por cada referer.

As datas devem estar formatadas pela função PHP strtotime e devem ser analisadas pelo Carbon. Por padrão, este terminal da API somente irá permitir aos usuários buscar dados de um máximo de 365 dias

Resposta: Uma representação JSON dos dados solicitados.

Exemplo: GET https://plid.in/api/v2/data/link?stats_type=day&key=CHAVE_DA_API_AQUI&url_ending=exemplo&response_type=json&left_bound=2018-11-20%2015:00:00&right_bound=2018-11-26%2018:00:00

Resposta:

{
   "action":"data_link_day",
   "result":{
      "url_ending":"exemplo",
      "data":[
         {"x":"2018-11-23","y":1},
         {"x":"2018-11-26","y":1}
      ]
   }
}

Exemplo: GET https://plid.in/api/v2/data/link?stats_type=country&key=CHAVE_DA_API_AQUI&url_ending=exemplo&response_type=json&left_bound=2018-11-20%2015:00:00&right_bound=2018-11-26%2018:00:00

Resposta:

{
   "action":"data_link_country",
   "result":{
      "url_ending":"exemplo",
      "data":[
         {"label":"BR","clicks":5}
      ]
   }
}


Exemplo GET https://plid.in/api/v2/data/link?stats_type=referer&key=CHAVE_DA_API_AQUI&url_ending=exemplo&response_type=json&left_bound=2018-11-20%2015:00:00&right_bound=2018-11-26%2018:00:00

Resposta:

{
   "action":"data_link_referer",
   "result":{
      "url_ending":"exemplo",
      "data":[
         {"label":"Direct","clicks":6},
         {"label":"SEU_DOMINIO","clicks":1}
      ]
   }
}

Erros HTTP

A API retornará um código de erro se sua solicitação for mal formada ou outro erro ocorrer durante o processamento de sua solicitação.


HTTP 400 Bad Request

Esse código é retornado nas seguintes situações:

  • Pelo terminal shorten
    • Caso o a url personalizada (custom_ending) informada já esteja em uso, será retornado um erro 400 e a seguinte mensagem: This URL ending is already in use.
  • Por qualquer terminal
    • Sua solicitação retornará um erro 400 se estiver mal formada ou o conteúdo dos argumentos não for compatível com o tipo de dado requerido


HTTP 500 Internal Server Error

  • Por qualquer terminal
    • O servidor encontrou um erro não tratável. Isto é devido a um problema com sua configuração ou o servidor está incapaz de tratar a requisição devido algum erro.


HTTP 401 Unauthorized

  • Por qualquer terminal
    • Você está sem autorização para fazer a transação. Isto é devido a uma incompatibilidade da chave da API.
  • Pelo terminal lookup
    • Ocorre quando não foi informado uma url_key para procura de URL secreta.


HTTP 404 Not Found

  • Pelo terminal lookup
    • Ocorre quando a url procurada não foi encontrada no banco de dados.


HTTP 403 Forbidden

  • Pelo terminal shorten
    • Sua solicitação foi entendida, mas você excedeu sua cota.


Respostas de erro
Exemplo de resposta JSON


{
   "status_code":429,
   "error_code":"QUOTA_EXCEEDED",
   "error":"Quota exceeded."
}

Exemplo de resposta em texto simples:

429 Quota exceeded.

آیا این پاسخ به شما کمک کرد؟ 2 کاربر این را مفید یافتند (3 نظرات)