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_KEYSessão da conta
Use Bearer para links da conta, uploads, estatísticas e monetização.
Authorization: Bearer …Início rápido
Crie o primeiro link curto em três passos e use a referência detalhada em produção.
- 1Criar uma conta
Abra o painel e ative um plano API.
- 2Copiar a chave API
Guarde-a no servidor e nunca a exponha em código público.
- 3Enviar o pedido
Envie o destino e leia result.short_url na resposta JSON.
curl -X POST "https://api.urlz.li/url/create" \
--data-urlencode "apikey=YOUR_API_KEY" \
--data-urlencode "fullUrl=https://example.com/private-report"
// Server-side JavaScript (Node.js)
const body = new URLSearchParams({
apikey: 'YOUR_API_KEY',
fullUrl: 'https://example.com/private-report'
});
const response = await fetch('https://api.urlz.li/url/create', {
method: 'POST',
body
});
const data = await response.json();
console.log(data.result.short_url);
$request = curl_init('https://api.urlz.li/url/create');
curl_setopt_array($request, [
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query([
'apikey' => 'YOUR_API_KEY',
'fullUrl' => 'https://example.com/private-report',
]),
CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($request), true, 512, JSON_THROW_ON_ERROR);
echo $data['result']['short_url'];
import requests
response = requests.post(
"https://api.urlz.li/url/create",
data={
"apikey": "YOUR_API_KEY",
"fullUrl": "https://example.com/private-report",
},
timeout=15,
)
response.raise_for_status()
print(response.json()["result"]["short_url"])
Autenticação
O URLZ suporta dois modos de autenticação. Escolha o adequado à integração.
Chave API
Para backends. Envie apikey no URL ou formulário; a chave e a subscrição devem estar ativas.
apikey=YOUR_API_KEYSessão Bearer
Para funções da conta. Obtenha um token no endpoint de login e envie-o em Authorization.
Authorization: Bearer SESSION_TOKENNunca publique chaves, palavras-passe ou tokens Bearer em JavaScript, logs, controlo de versões ou repositórios públicos.
Índice de endpoints
Escolha um endpoint para ver parâmetros e exemplos.
/url/createCriar um link curto
GET/url/listListar e filtrar links
POST/mobile/v1/auth/login.phpAbrir sessão da conta
POST/mobile/v1/shorten.phpCriar link da conta
POST/mobile/v1/upload.phpEnviar ficheiro ou foto
GET/mobile/v1/links.phpListar links da conta
GET/mobile/v1/clicks.phpVer estatísticas de cliques
DELETE/mobile/v1/delete-link.phpEliminar um link
POST/mobile/v1/collaboration/configure.phpEnable URLZ Chat or URLZ Request
GET/mobile/v1/collaboration/chats.phpList link conversations
GET/mobile/v1/collaboration/requests.phpTrack document requests
POST/mobile/v1/monetization/links.phpCriar ou converter link pago
POST/mobile/v1/monetization/upload.phpCriar ficheiro ou foto paga
GET/mobile/v1/monetization/links.phpListar links pagos
GET/mobile/v1/monetization/transactions.phpListar vendas de links pagos
Endpoints por chave API
Rotas estáveis para criar e pesquisar links curtos.
/url/createCriar um link curto
Cria um URL curto com uma chave ativa.
apikeyParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
apikey | string | Sim | — |
fullUrl | URL | Sim | — |
encrypt | string | Não | "" |
password | string | Não | "" |
curl -X POST "https://api.urlz.li/url/create" \
--data-urlencode "apikey=YOUR_API_KEY" \
--data-urlencode "fullUrl=https://example.com/report.pdf"
{
"result": {
"short_url": "https://urlz.li/7b3c2e5a",
"hash": "7b3c2e5a",
"date": "2026-11-02",
"time": "14:32:10"
}
}
/url/listListar e filtrar links
Devolve links com filtros e paginação.
apikeyParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
apikey | string | Sim | — |
limit | integer (1–1000) | Não | 100 |
offset | integer | Não | 0 |
order | asc | desc | Não | desc |
date | YYYY-MM-DD | Não | — |
from_date | YYYY-MM-DD | Não | — |
to_date | YYYY-MM-DD | Não | — |
url_destination | string | Não | — |
hash | string | Não | — |
curl -G "https://api.urlz.li/url/list" \
--data-urlencode "apikey=YOUR_API_KEY" \
--data-urlencode "limit=25" \
--data-urlencode "order=desc"
{
"result": {
"filters": { "limit": 25, "offset": 0, "order": "desc" },
"total": 42,
"count": 25,
"items": [
{
"id": 1204,
"date": "2026-11-02",
"time": "14:32:10",
"destination": "https://example.com/report.pdf",
"hash": "7b3c2e5a",
"hash_retour": "https://urlz.li/7b3c2e5a"
}
]
}
}
Endpoints da conta
Links, uploads, cliques e eliminação.
/mobile/v1/auth/login.phpAbrir sessão da conta
Troca credenciais por um token Bearer.
Sem autenticaçãoParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
email | Sim | — | |
password | string | Sim | — |
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"}'
{
"token": "SESSION_TOKEN",
"user": {
"id": 42,
"email": "developer@example.com",
"apiKey": "ACCOUNT_API_KEY",
"planActive": true
}
}
/mobile/v1/shorten.phpCriar link da conta
Cria link normal ou protegido; Bearer é opcional salvo com palavra-passe.
Token Bearer opcionalParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
url | URL | Sim | — |
password | string (min. 4) | Não | — |
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"}'
{
"shortUrl": "https://urlz.li/Ab3dE91x",
"destination": "https://example.com/private",
"hash": "Ab3dE91x",
"protected": true
}
/mobile/v1/upload.phpEnviar ficheiro ou foto
Envia ficheiro permitido até 10 MB e devolve URL curto.
Token Bearer opcionalParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
file | multipart file | Sim | — |
kind | photo | document | Não | document |
password | string (min. 4) | Não | — |
curl -X POST "https://api.urlz.li/mobile/v1/upload.php" \
-H "Authorization: Bearer SESSION_TOKEN" \
-F "file=@./photo.jpg" \
-F "kind=photo"
{
"shortUrl": "https://urlz.li/P8kLm21q",
"destination": "https://urlz.li/cloud/app/photo_….jpg",
"hash": "P8kLm21q",
"protected": false
}
/mobile/v1/links.phpListar links da conta
Lista links, cliques, proteção e monetização.
BearerParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
limit | integer (1–100) | Não | 100 |
offset | integer | Não | 0 |
curl "https://api.urlz.li/mobile/v1/links.php?limit=25&offset=0" \
-H "Authorization: Bearer SESSION_TOKEN"
{
"items": [
{
"id": 1204,
"shortUrl": "https://urlz.li/7b3c2e5a",
"destination": "https://example.com/report.pdf",
"protected": false,
"monetized": true,
"clicks": 18
}
],
"total": 42,
"summary": { "totalLinks": 42, "totalClicks": 304, "clicksLast7Days": 28 }
}
/mobile/v1/clicks.phpVer estatísticas de cliques
Devolve cliques, visitantes, países e acessos.
BearerParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
linkId | integer | Sim | — |
limit | integer (1–100) | Não | 100 |
offset | integer | Não | 0 |
curl "https://api.urlz.li/mobile/v1/clicks.php?linkId=1204&limit=25" \
-H "Authorization: Bearer SESSION_TOKEN"
{
"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": []
}
/mobile/v1/delete-link.phpEliminar um link
Elimina apenas um link da conta autenticada.
BearerParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
hash | string | Sim | — |
curl -X DELETE "https://api.urlz.li/mobile/v1/delete-link.php" \
-H "Authorization: Bearer SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"hash":"7b3c2e5a"}'
{
"ok": true,
"message": "Link deleted."
}
URLZ Chat & Request
Add private conversations, collect requested documents, schedule reminders and track submissions.
/mobile/v1/collaboration/configure.phpEnable 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 keyParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
hash | string | Sim | — |
chat.enabled | boolean | Não | false |
request.enabled | boolean | Não | false |
request.title | string | Não | — |
request.items | string[] | Não | [] |
request.recipients | email[] | Não | [] |
request.deadline | ISO datetime | Não | — |
request.paymentRequired | boolean | Não | false |
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"]}}'
{"featureId":14,"hash":"7b3c2e5a","chatEnabled":true,"requestEnabled":true}
/mobile/v1/collaboration/chats.phpList link conversations
Return chat-enabled links and message totals. Add id to retrieve messages.
BearerParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
id | integer | Não | — |
after | integer | Não | 0 |
curl "https://api.urlz.li/mobile/v1/collaboration/chats.php?id=14" \
-H "Authorization: Bearer SESSION_TOKEN"
{"items":[{"id":14,"hash":"7b3c2e5a","messageCount":3,"messages":[]}]}
/mobile/v1/collaboration/requests.phpTrack document requests
List requests, expected items, recipients, submissions and secure files. Add id for full detail.
BearerParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
id | integer | Não | — |
curl "https://api.urlz.li/mobile/v1/collaboration/requests.php?id=14" \
-H "Authorization: Bearer SESSION_TOKEN"
{"items":[{"id":14,"title":"Accounting documents","recipients":1,"submissions":1,"files":2}]}
Endpoints de links pagos
Crie acesso pago e consulte vendas da conta autenticada.
/mobile/v1/monetization/links.phpCriar ou converter link pago
Cria URL paga ou converte link existente.
BearerParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
destination | URL | Não | — |
existingLinkId | integer | Não | — |
title | string (max. 180) | Sim | — |
description | string (max. 3000) | Não | — |
price | decimal | Sim | — |
currency | EUR | USD | Sim | USD |
accessPolicy | permanent | timed | limited | Não | permanent |
accessDurationHours | integer (1–8760) | Não | 24 |
maxAccesses | integer (1–1000) | Não | 1 |
locale | ISO 639-1 | Não | en |
curl -X POST "https://api.urlz.li/mobile/v1/monetization/links.php" \
-H "Authorization: Bearer SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"destination":"https://example.com/private-course",
"title":"Private course access",
"description":"One-time access to the course.",
"price":"9.90",
"currency":"EUR",
"accessPolicy":"permanent",
"locale":"en"
}'
{
"id": 91,
"hash": "cd3ed9a4",
"shortUrl": "https://urlz.li/cd3ed9a4",
"paywallUrl": "https://urlz.li/en/pay/cd3ed9a4/",
"converted": false
}
/mobile/v1/monetization/upload.phpCriar ficheiro ou foto paga
Guarda ficheiro privado e cria link pago, até 50 MB.
BearerParâmetros
| Parâmetro | Tipo | Obrigatório | Predefinição |
|---|---|---|---|
file | multipart file | Sim | — |
kind | photo | file | Não | file |
title | string (max. 180) | Sim | — |
description | string (max. 3000) | Não | — |
price | decimal | Sim | — |
currency | EUR | USD | Sim | USD |
accessPolicy | permanent | timed | limited | Não | permanent |
locale | ISO 639-1 | Não | en |
curl -X POST "https://api.urlz.li/mobile/v1/monetization/upload.php" \
-H "Authorization: Bearer SESSION_TOKEN" \
-F "file=@./premium-photo.jpg" \
-F "kind=photo" \
-F "title=Premium event photo" \
-F "price=4.90" \
-F "currency=EUR"
{
"id": 92,
"hash": "e71f8a20",
"shortUrl": "https://urlz.li/e71f8a20",
"paywallUrl": "https://urlz.li/en/pay/e71f8a20/"
}
/mobile/v1/monetization/links.phpListar links pagos
Devolve links pagos, vendas, bruto, líquido e estado.
Bearercurl "https://api.urlz.li/mobile/v1/monetization/links.php" \
-H "Authorization: Bearer SESSION_TOKEN"
{
"items": [
{
"id": 91,
"shortUrl": "https://urlz.li/cd3ed9a4",
"kind": "url",
"priceMinor": 990,
"currency": "EUR",
"status": "active",
"sales": 4,
"grossMinor": 3960,
"netMinor": 3374
}
]
}
/mobile/v1/monetization/transactions.phpListar vendas de links pagos
Devolve pedidos, taxas, líquido e datas de libertação.
Bearercurl "https://api.urlz.li/mobile/v1/monetization/transactions.php" \
-H "Authorization: Bearer SESSION_TOKEN"
{
"items": [
{
"orderNumber": "LNK-20261102-8F3C21",
"grossMinor": 990,
"platformFeeMinor": 69,
"processorFeeMinor": 45,
"netMinor": 876,
"currency": "EUR",
"status": "paid",
"fundsAvailableAt": "2026-11-16 14:32:10",
"fundsStatus": "held"
}
]
}
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" }Pedido concluído.
Link ou ficheiro criado.
JSON ou sintaxe inválidos.
Token ausente ou expirado.
Chave, plano ou conta sem acesso.
O recurso não existe.
Estado incompatível.
Campos ausentes ou inválidos.
Abrande e tente gradualmente.
Tente mais tarde de forma idempotente.
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.
Envie o endpoint, estado HTTP e um pedido sem credenciais.
