Panoramica
Crea link brevi, upload, statistiche e accessi a pagamento con l’API URLZ. La guida separa le integrazioni server con chiave API dalle sessioni account autenticate.
Server-to-server
Usa la chiave attiva da backend, automazioni o strumenti interni.
apikey=YOUR_API_KEYSessione account
Usa Bearer per link, upload, statistiche e monetizzazione.
Authorization: Bearer …Avvio rapido
Crea il primo link in tre passaggi, poi usa la guida completa.
- 1Crea un account
Apri la dashboard e attiva un piano API.
- 2Copia la chiave API
Conservala sul server, mai nel codice pubblico.
- 3Invia la richiesta
Invia la destinazione e leggi result.short_url dalla risposta 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"])
Autenticazione
URLZ supporta due modalità di autenticazione. Scegli quella adatta.
Chiave API
Per backend. Invia apikey nell’URL o nel form; chiave e abbonamento devono essere attivi.
apikey=YOUR_API_KEYSessione Bearer
Per le funzioni account. Ottieni il token dal login e invialo in Authorization.
Authorization: Bearer SESSION_TOKENNon pubblicare chiavi, password o token in JavaScript, log, controllo versione o repository pubblici.
Indice endpoint
Scegli un endpoint per parametri ed esempi.
/url/createCrea un link breve
GET/url/listElenca e filtra link
POST/mobile/v1/auth/login.phpApri sessione account
POST/mobile/v1/shorten.phpCrea link account
POST/mobile/v1/upload.phpCarica file o foto
GET/mobile/v1/links.phpElenca link account
GET/mobile/v1/clicks.phpLeggi statistiche clic
DELETE/mobile/v1/delete-link.phpElimina 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.phpCrea o converti link a pagamento
POST/mobile/v1/monetization/upload.phpCrea file o foto a pagamento
GET/mobile/v1/monetization/links.phpElenca link a pagamento
GET/mobile/v1/monetization/transactions.phpElenca vendite
Endpoint con chiave API
Rotte stabili per creare e cercare link brevi.
/url/createCrea un link breve
Crea URL breve con chiave attiva.
apikeyParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
apikey | string | Sì | — |
fullUrl | URL | Sì | — |
encrypt | string | No | "" |
password | string | No | "" |
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/listElenca e filtra link
Restituisce link con filtri e paginazione.
apikeyParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
apikey | string | Sì | — |
limit | integer (1–1000) | No | 100 |
offset | integer | No | 0 |
order | asc | desc | No | desc |
date | YYYY-MM-DD | No | — |
from_date | YYYY-MM-DD | No | — |
to_date | YYYY-MM-DD | No | — |
url_destination | string | No | — |
hash | string | No | — |
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"
}
]
}
}
Endpoint account
Link, upload, clic ed eliminazione.
/mobile/v1/auth/login.phpApri sessione account
Scambia credenziali con token Bearer.
Nessuna autenticazioneParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
email | Sì | — | |
password | string | Sì | — |
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.phpCrea link account
Crea link normale o protetto; Bearer è opzionale salvo password.
Token Bearer facoltativoParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
url | URL | Sì | — |
password | string (min. 4) | No | — |
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.phpCarica file o foto
Carica file consentito fino a 10 MB.
Token Bearer facoltativoParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
file | multipart file | Sì | — |
kind | photo | document | No | document |
password | string (min. 4) | No | — |
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.phpElenca link account
Elenca link, clic, protezione e monetizzazione.
BearerParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
limit | integer (1–100) | No | 100 |
offset | integer | No | 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.phpLeggi statistiche clic
Restituisce clic, visitatori, paesi e accessi.
BearerParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
linkId | integer | Sì | — |
limit | integer (1–100) | No | 100 |
offset | integer | No | 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.phpElimina link
Elimina solo link dell’account autenticato.
BearerParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
hash | string | Sì | — |
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 keyParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
hash | string | Sì | — |
chat.enabled | boolean | No | false |
request.enabled | boolean | No | false |
request.title | string | No | — |
request.items | string[] | No | [] |
request.recipients | email[] | No | [] |
request.deadline | ISO datetime | No | — |
request.paymentRequired | boolean | No | 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.
BearerParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
id | integer | No | — |
after | integer | No | 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.
BearerParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
id | integer | No | — |
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}]}
Endpoint link a pagamento
Crea accessi a pagamento e consulta le vendite.
/mobile/v1/monetization/links.phpCrea o converti link a pagamento
Crea URL a pagamento o converte link esistente.
BearerParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
destination | URL | No | — |
existingLinkId | integer | No | — |
title | string (max. 180) | Sì | — |
description | string (max. 3000) | No | — |
price | decimal | Sì | — |
currency | EUR | USD | Sì | USD |
accessPolicy | permanent | timed | limited | No | permanent |
accessDurationHours | integer (1–8760) | No | 24 |
maxAccesses | integer (1–1000) | No | 1 |
locale | ISO 639-1 | No | 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.phpCrea file o foto a pagamento
Salva file privato e crea link a pagamento, massimo 50 MB.
BearerParametri
| Parametro | Tipo | Obbligatorio | Predefinito |
|---|---|---|---|
file | multipart file | Sì | — |
kind | photo | file | No | file |
title | string (max. 180) | Sì | — |
description | string (max. 3000) | No | — |
price | decimal | Sì | — |
currency | EUR | USD | Sì | USD |
accessPolicy | permanent | timed | limited | No | permanent |
locale | ISO 639-1 | No | 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.phpElenca link a pagamento
Restituisce link, vendite, lordo, netto e stato.
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.phpElenca vendite
Restituisce ordini, commissioni, netto e date di rilascio.
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"
}
]
}
Errori e codici HTTP
Gli endpoint moderni restituiscono message; quelli con chiave API usano error. Usa sempre lo stato HTTP.
{ "message": "A valid link is required." }{ "error": "Invalid API key" }Richiesta completata.
Link o file creato.
JSON o sintassi non validi.
Token assente o scaduto.
Chiave, piano o account non autorizzato.
Risorsa inesistente.
Stato in conflitto.
Campi mancanti o non validi.
Rallenta e riprova.
Riprova più tardi in modo idempotente.
Sicurezza e limiti
Applica queste regole in produzione.
- Utilizza solo HTTPS.
- Mantieni private le chiavi API e rinnovale regolarmente.
- Valida e codifica i parametri forniti dagli utenti.
- Usa la paginazione per elenchi e registri.
- Massimo consigliato: 10 richieste al secondo per chiave.
Invia endpoint, stato HTTP ed esempio ripulito senza credenziali.
