RÉFÉRENCE DÉVELOPPEUR

Documentation de l’API URLZ.li

Authentification, liens courts, envoi de fichiers et photos, statistiques de clics et API de liens payants, avec des exemples prêts à utiliser.

01

Présentation

Créez des parcours de liens courts, d’envoi de fichiers, de statistiques et d’accès payant avec l’API URLZ. Cette référence sépare les intégrations serveur par clé API des sessions de compte authentifiées.

Serveur à serveur

Utilisez votre clé API active pour créer et rechercher des liens depuis un backend, une automatisation ou un outil interne.

apikey=YOUR_API_KEY

Session de compte

Utilisez une session Bearer pour les liens du compte, les fichiers, les statistiques et la monétisation.

Authorization: Bearer …
02

Démarrage rapide

Créez votre premier lien court en trois étapes, puis utilisez la référence détaillée pour la production.

  1. 1
    Créer un compte

    Ouvrez la dashboard et activez un abonnement API.

  2. 2
    Copier votre clé API

    Conservez-la sur votre serveur et ne l’exposez jamais dans du code public.

  3. 3
    Envoyer la requête

    Envoyez la destination puis lisez result.short_url dans la réponse 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

Authentification

URLZ accepte deux modes d’authentification. Choisissez celui qui correspond à votre intégration.

A

Clé API

Pour les intégrations backend. Envoyez apikey dans la chaîne de requête ou le corps du formulaire. La clé et l’abonnement doivent être actifs.

apikey=YOUR_API_KEY
B

Session Bearer

Pour les fonctions du compte. Obtenez un jeton via la route de connexion et transmettez-le dans l’en-tête Authorization.

Authorization: Bearer SESSION_TOKEN
Conservez les identifiants côté serveur

Ne publiez jamais une clé API, un mot de passe ou un jeton Bearer dans du JavaScript, des journaux mobiles, Git ou un dépôt public.

04

Index des routes

Choisissez une route pour accéder directement à ses paramètres et à ses exemples de requête et de réponse.

05

Routes par clé API

Routes serveur à serveur stables pour créer et rechercher des liens courts.

06

Routes du compte

Liens du compte, fichiers, statistiques de clics et suppression.

POST/mobile/v1/auth/login.php

Ouvrir une session de compte

Échange les identifiants du compte contre un jeton de session Bearer.

Aucune authentification

Paramètres

ParamètreTypeObligatoirePar défaut
emailemailOui—
passwordstringOui—
Requête
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"}'
Réponse
{
  "token": "SESSION_TOKEN",
  "user": {
    "id": 42,
    "email": "developer@example.com",
    "apiKey": "ACCOUNT_API_KEY",
    "planActive": true
  }
}
POST/mobile/v1/shorten.php

Créer un lien lié au compte

Crée un lien normal ou protégé par mot de passe. Le jeton Bearer est facultatif sauf si un mot de passe est utilisé.

Jeton Bearer facultatif

Paramètres

ParamètreTypeObligatoirePar défaut
urlURLOui—
passwordstring (min. 4)Non—
Requête
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"}'
Réponse
{
  "shortUrl": "https://urlz.li/Ab3dE91x",
  "destination": "https://example.com/private",
  "hash": "Ab3dE91x",
  "protected": true
}
POST/mobile/v1/upload.php

Importer un fichier ou une photo

Importe un fichier autorisé de 10 Mo maximum et renvoie une URL courte.

Jeton Bearer facultatif

Paramètres

ParamètreTypeObligatoirePar défaut
filemultipart fileOui—
kindphoto | documentNondocument
passwordstring (min. 4)Non—
Requête
curl -X POST "https://api.urlz.li/mobile/v1/upload.php" \
  -H "Authorization: Bearer SESSION_TOKEN" \
  -F "file=@./photo.jpg" \
  -F "kind=photo"
Réponse
{
  "shortUrl": "https://urlz.li/P8kLm21q",
  "destination": "https://urlz.li/cloud/app/photo_….jpg",
  "hash": "P8kLm21q",
  "protected": false
}
GET/mobile/v1/clicks.php

Consulter les statistiques de clics

Renvoie les clics, les visiteurs uniques, les principaux pays et les accès paginés.

Bearer

Paramètres

ParamètreTypeObligatoirePar défaut
linkIdintegerOui—
limitinteger (1–100)Non100
offsetintegerNon0
Requête
curl "https://api.urlz.li/mobile/v1/clicks.php?linkId=1204&limit=25" \
  -H "Authorization: Bearer SESSION_TOKEN"
Réponse
{
  "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

Paramètres

ParamètreTypeObligatoirePar défaut
hashstringOui—
chat.enabledbooleanNonfalse
request.enabledbooleanNonfalse
request.titlestringNon—
request.itemsstring[]Non[]
request.recipientsemail[]Non[]
request.deadlineISO datetimeNon—
request.paymentRequiredbooleanNonfalse
Requête
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"]}}'
Réponse
{"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

Paramètres

ParamètreTypeObligatoirePar défaut
idintegerNon—
afterintegerNon0
Requête
curl "https://api.urlz.li/mobile/v1/collaboration/chats.php?id=14" \
  -H "Authorization: Bearer SESSION_TOKEN"
Réponse
{"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

Paramètres

ParamètreTypeObligatoirePar défaut
idintegerNon—
Requête
curl "https://api.urlz.li/mobile/v1/collaboration/requests.php?id=14" \
  -H "Authorization: Bearer SESSION_TOKEN"
Réponse
{"items":[{"id":14,"title":"Accounting documents","recipients":1,"submissions":1,"files":2}]}
08

Erreurs et codes HTTP

Les routes modernes renvoient un objet JSON avec message. Les routes par clé API utilisent error. Basez toujours votre logique sur le statut HTTP et non sur le texte du message.

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

La requête s’est terminée correctement.

201
Créé

Le lien ou le fichier a été créé.

400
Requête invalide

JSON incorrect ou syntaxe de requête invalide.

401
Authentification requise

Le jeton Bearer est absent ou expiré.

403
Accès interdit

La clé API, l’abonnement ou le compte ne permet pas cette action.

404
Introuvable

Le lien ou la ressource n’existe pas.

409
Conflit

L’état demandé entre en conflit avec une ressource existante.

422
Validation échouée

Un ou plusieurs champs sont absents ou invalides.

429
Trop de requêtes

Ralentissez puis réessayez avec un délai progressif.

500/503
Serveur indisponible

Réessayez plus tard en gardant la requête idempotente.

09

Sécurité et limites

Appliquez ces règles à toute intégration en production.

  • Utilisez uniquement HTTPS.
  • Gardez vos clés API privées et renouvelez-les régulièrement.
  • Validez et encodez les paramètres fournis par les utilisateurs.
  • Utilisez la pagination pour les listes et journaux.
  • Maximum recommandé : 10 requêtes par seconde et par clé.
Besoin d’aide pour une intégration ?

Envoyez la route, le statut HTTP et un exemple de requête nettoyé. Ne transmettez jamais vos identifiants.

URLZ POUR iPHONE

La nouvelle version iOS arrive bientôt

La mise à jour de l’application URLZ pour iPhone est en cours de finalisation et arrivera sur l’App Store dans les prochains jours. Merci pour votre patience.