REFERÊNCIA PARA PROGRAMADORES

Documentação da API URLZ.li

Autenticação, links curtos, upload de ficheiros e fotografias, estatísticas de cliques e APIs de links pagos com exemplos prontos a usar.

01

Visão geral

Crie fluxos de links curtos, uploads, estatísticas e acesso pago com a API URLZ. Esta referência separa integrações de servidor com chave API de sessões autenticadas.

Servidor a servidor

Use a chave ativa para criar e pesquisar links num backend, automação ou ferramenta interna.

apikey=YOUR_API_KEY

Sessão da conta

Use Bearer para links da conta, uploads, estatísticas e monetização.

Authorization: Bearer …
02

Início rápido

Crie o primeiro link curto em três passos e use a referência detalhada em produção.

  1. 1
    Criar uma conta

    Abra o painel e ative um plano API.

  2. 2
    Copiar a chave API

    Guarde-a no servidor e nunca a exponha em código público.

  3. 3
    Enviar o pedido

    Envie o destino e leia result.short_url na resposta JSON.

Curl
curl -X POST "https://api.urlz.li/url/create" \
  --data-urlencode "apikey=YOUR_API_KEY" \
  --data-urlencode "fullUrl=https://example.com/private-report"
03

Autenticação

O URLZ suporta dois modos de autenticação. Escolha o adequado à integração.

A

Chave API

Para backends. Envie apikey no URL ou formulário; a chave e a subscrição devem estar ativas.

apikey=YOUR_API_KEY
B

Sessão Bearer

Para funções da conta. Obtenha um token no endpoint de login e envie-o em Authorization.

Authorization: Bearer SESSION_TOKEN
Mantenha as credenciais no servidor

Nunca publique chaves, palavras-passe ou tokens Bearer em JavaScript, logs, controlo de versões ou repositórios públicos.

04

Índice de endpoints

Escolha um endpoint para ver parâmetros e exemplos.

05

Endpoints por chave API

Rotas estáveis para criar e pesquisar links curtos.

06

Endpoints da conta

Links, uploads, cliques e eliminação.

POST/mobile/v1/auth/login.php

Abrir sessão da conta

Troca credenciais por um token Bearer.

Sem autenticação

Parâmetros

ParâmetroTipoObrigatórioPredefinição
emailemailSim—
passwordstringSim—
Pedido
curl -X POST "https://api.urlz.li/mobile/v1/auth/login.php" \
  -H "Content-Type: application/json" \
  -d '{"email":"developer@example.com","password":"YOUR_PASSWORD"}'
Resposta
{
  "token": "SESSION_TOKEN",
  "user": {
    "id": 42,
    "email": "developer@example.com",
    "apiKey": "ACCOUNT_API_KEY",
    "planActive": true
  }
}
POST/mobile/v1/shorten.php

Criar link da conta

Cria link normal ou protegido; Bearer é opcional salvo com palavra-passe.

Token Bearer opcional

Parâmetros

ParâmetroTipoObrigatórioPredefinição
urlURLSim—
passwordstring (min. 4)Não—
Pedido
curl -X POST "https://api.urlz.li/mobile/v1/shorten.php" \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/private","password":"safe-pass"}'
Resposta
{
  "shortUrl": "https://urlz.li/Ab3dE91x",
  "destination": "https://example.com/private",
  "hash": "Ab3dE91x",
  "protected": true
}
POST/mobile/v1/upload.php

Enviar ficheiro ou foto

Envia ficheiro permitido até 10 MB e devolve URL curto.

Token Bearer opcional

Parâmetros

ParâmetroTipoObrigatórioPredefinição
filemultipart fileSim—
kindphoto | documentNãodocument
passwordstring (min. 4)Não—
Pedido
curl -X POST "https://api.urlz.li/mobile/v1/upload.php" \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -F "file=@./photo.jpg" \
  -F "kind=photo"
Resposta
{
  "shortUrl": "https://urlz.li/P8kLm21q",
  "destination": "https://urlz.li/cloud/app/photo_….jpg",
  "hash": "P8kLm21q",
  "protected": false
}
GET/mobile/v1/clicks.php

Ver estatísticas de cliques

Devolve cliques, visitantes, países e acessos.

Bearer

Parâmetros

ParâmetroTipoObrigatórioPredefinição
linkIdintegerSim—
limitinteger (1–100)Não100
offsetintegerNão0
Pedido
curl "https://api.urlz.li/mobile/v1/clicks.php?linkId=1204&limit=25" \
  -H "Authorization: Bearer SESSION_TOKEN"
Resposta
{
  "link": { "id": 1204, "shortUrl": "https://urlz.li/7b3c2e5a" },
  "summary": {
    "totalClicks": 18,
    "uniqueVisitors": 14,
    "clicksLast24Hours": 2,
    "clicksLast7Days": 9
  },
  "countries": [{ "country": "France", "countryCode": "FR", "clicks": 8 }],
  "items": []
}
07

URLZ Chat & Request

Add private conversations, collect requested documents, schedule reminders and track submissions.

POST/mobile/v1/collaboration/configure.php

Enable URLZ Chat or URLZ Request

Attach a private conversation and/or a document request to an existing account link. A Bearer session token or API key is accepted.

Bearer or API key

Parâmetros

ParâmetroTipoObrigatórioPredefinição
hashstringSim—
chat.enabledbooleanNãofalse
request.enabledbooleanNãofalse
request.titlestringNão—
request.itemsstring[]Não[]
request.recipientsemail[]Não[]
request.deadlineISO datetimeNão—
request.paymentRequiredbooleanNãofalse
Pedido
curl -X POST "https://api.urlz.li/mobile/v1/collaboration/configure.php" \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"hash":"7b3c2e5a","chat":{"enabled":true},"request":{"enabled":true,"title":"Accounting documents","items":["Invoices","Bank statement"]}}'
Resposta
{"featureId":14,"hash":"7b3c2e5a","chatEnabled":true,"requestEnabled":true}
GET/mobile/v1/collaboration/chats.php

List link conversations

Return chat-enabled links and message totals. Add id to retrieve messages.

Bearer

Parâmetros

ParâmetroTipoObrigatórioPredefinição
idintegerNão—
afterintegerNão0
Pedido
curl "https://api.urlz.li/mobile/v1/collaboration/chats.php?id=14" \
  -H "Authorization: Bearer SESSION_TOKEN"
Resposta
{"items":[{"id":14,"hash":"7b3c2e5a","messageCount":3,"messages":[]}]}
GET/mobile/v1/collaboration/requests.php

Track document requests

List requests, expected items, recipients, submissions and secure files. Add id for full detail.

Bearer

Parâmetros

ParâmetroTipoObrigatórioPredefinição
idintegerNão—
Pedido
curl "https://api.urlz.li/mobile/v1/collaboration/requests.php?id=14" \
  -H "Authorization: Bearer SESSION_TOKEN"
Resposta
{"items":[{"id":14,"title":"Accounting documents","recipients":1,"submissions":1,"files":2}]}
08

Erros e códigos HTTP

Os endpoints modernos devolvem message; os de chave API usam error. Use sempre o estado HTTP.

{ "message": "A valid link is required." }{ "error": "Invalid API key" }
200
Sucesso

Pedido concluído.

201
Criado

Link ou ficheiro criado.

400
Pedido inválido

JSON ou sintaxe inválidos.

401
Autenticação necessária

Token ausente ou expirado.

403
Proibido

Chave, plano ou conta sem acesso.

404
Não encontrado

O recurso não existe.

409
Conflito

Estado incompatível.

422
Validação falhou

Campos ausentes ou inválidos.

429
Demasiados pedidos

Abrande e tente gradualmente.

500/503
Servidor indisponível

Tente mais tarde de forma idempotente.

09

Segurança e limites

Aplique estas regras em produção.

  • Utilize apenas HTTPS.
  • Mantenha as chaves API privadas e renove-as regularmente.
  • Valide e codifique os parâmetros introduzidos pelos utilizadores.
  • Utilize paginação nas listas e registos.
  • Máximo recomendado: 10 pedidos por segundo e por chave.
Precisa de ajuda?

Envie o endpoint, estado HTTP e um pedido sem credenciais.

URLZ PARA iPHONE

A nova versão para iOS está quase disponível

A atualização da aplicação URLZ para iPhone está a ser finalizada e chegará à App Store nos próximos dias. Obrigado pela sua paciência.