RIFERIMENTO PER SVILUPPATORI

Documentazione API URLZ.li

Autenticazione, link brevi, upload di file e foto, statistiche dei clic e API per link a pagamento con esempi pronti all’uso.

01

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_KEY

Sessione account

Usa Bearer per link, upload, statistiche e monetizzazione.

Authorization: Bearer …
02

Avvio rapido

Crea il primo link in tre passaggi, poi usa la guida completa.

  1. 1
    Crea un account

    Apri la dashboard e attiva un piano API.

  2. 2
    Copia la chiave API

    Conservala sul server, mai nel codice pubblico.

  3. 3
    Invia la richiesta

    Invia la destinazione e leggi result.short_url dalla risposta 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

Autenticazione

URLZ supporta due modalità di autenticazione. Scegli quella adatta.

A

Chiave API

Per backend. Invia apikey nell’URL o nel form; chiave e abbonamento devono essere attivi.

apikey=YOUR_API_KEY
B

Sessione Bearer

Per le funzioni account. Ottieni il token dal login e invialo in Authorization.

Authorization: Bearer SESSION_TOKEN
Mantieni le credenziali sul server

Non pubblicare chiavi, password o token in JavaScript, log, controllo versione o repository pubblici.

04

Indice endpoint

Scegli un endpoint per parametri ed esempi.

05

Endpoint con chiave API

Rotte stabili per creare e cercare link brevi.

06

Endpoint account

Link, upload, clic ed eliminazione.

POST/mobile/v1/auth/login.php

Apri sessione account

Scambia credenziali con token Bearer.

Nessuna autenticazione

Parametri

ParametroTipoObbligatorioPredefinito
emailemailSì—
passwordstringSì—
Richiesta
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"}'
Risposta
{
  "token": "SESSION_TOKEN",
  "user": {
    "id": 42,
    "email": "developer@example.com",
    "apiKey": "ACCOUNT_API_KEY",
    "planActive": true
  }
}
POST/mobile/v1/shorten.php

Crea link account

Crea link normale o protetto; Bearer è opzionale salvo password.

Token Bearer facoltativo

Parametri

ParametroTipoObbligatorioPredefinito
urlURLSì—
passwordstring (min. 4)No—
Richiesta
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"}'
Risposta
{
  "shortUrl": "https://urlz.li/Ab3dE91x",
  "destination": "https://example.com/private",
  "hash": "Ab3dE91x",
  "protected": true
}
POST/mobile/v1/upload.php

Carica file o foto

Carica file consentito fino a 10 MB.

Token Bearer facoltativo

Parametri

ParametroTipoObbligatorioPredefinito
filemultipart fileSì—
kindphoto | documentNodocument
passwordstring (min. 4)No—
Richiesta
curl -X POST "https://api.urlz.li/mobile/v1/upload.php" \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -F "file=@./photo.jpg" \
  -F "kind=photo"
Risposta
{
  "shortUrl": "https://urlz.li/P8kLm21q",
  "destination": "https://urlz.li/cloud/app/photo_….jpg",
  "hash": "P8kLm21q",
  "protected": false
}
GET/mobile/v1/clicks.php

Leggi statistiche clic

Restituisce clic, visitatori, paesi e accessi.

Bearer

Parametri

ParametroTipoObbligatorioPredefinito
linkIdintegerSì—
limitinteger (1–100)No100
offsetintegerNo0
Richiesta
curl "https://api.urlz.li/mobile/v1/clicks.php?linkId=1204&limit=25" \
  -H "Authorization: Bearer SESSION_TOKEN"
Risposta
{
  "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

Parametri

ParametroTipoObbligatorioPredefinito
hashstringSì—
chat.enabledbooleanNofalse
request.enabledbooleanNofalse
request.titlestringNo—
request.itemsstring[]No[]
request.recipientsemail[]No[]
request.deadlineISO datetimeNo—
request.paymentRequiredbooleanNofalse
Richiesta
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"]}}'
Risposta
{"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

Parametri

ParametroTipoObbligatorioPredefinito
idintegerNo—
afterintegerNo0
Richiesta
curl "https://api.urlz.li/mobile/v1/collaboration/chats.php?id=14" \
  -H "Authorization: Bearer SESSION_TOKEN"
Risposta
{"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

Parametri

ParametroTipoObbligatorioPredefinito
idintegerNo—
Richiesta
curl "https://api.urlz.li/mobile/v1/collaboration/requests.php?id=14" \
  -H "Authorization: Bearer SESSION_TOKEN"
Risposta
{"items":[{"id":14,"title":"Accounting documents","recipients":1,"submissions":1,"files":2}]}
08

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" }
200
Successo

Richiesta completata.

201
Creato

Link o file creato.

400
Richiesta non valida

JSON o sintassi non validi.

401
Autenticazione richiesta

Token assente o scaduto.

403
Vietato

Chiave, piano o account non autorizzato.

404
Non trovato

Risorsa inesistente.

409
Conflitto

Stato in conflitto.

422
Validazione fallita

Campi mancanti o non validi.

429
Troppe richieste

Rallenta e riprova.

500/503
Server non disponibile

Riprova più tardi in modo idempotente.

09

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.
Serve aiuto?

Invia endpoint, stato HTTP ed esempio ripulito senza credenziali.

URLZ PER iPHONE

La nuova versione iOS è quasi pronta

L’aggiornamento dell’app URLZ per iPhone è in fase di completamento e arriverà sull’App Store nei prossimi giorni. Grazie per la pazienza.