Documentation de l'API

Qui y a accès

L'API fait partie de la formule Entreprise. Le jeton appartient au compte qui y souscrit, et c'est ce compte qui répond de ce que fait l'intégration. Après l'achat, le jeton se trouve dans Panneau → API, avec des exemples déjà remplis avec vos identifiants.

Authentification

Chaque requête transporte le jeton dans l'en-tête Authorization. Une requête sans jeton, ou avec un jeton d'un abonnement expiré, reçoit 401.

Authorization: Bearer <token>

Sur les serveurs où l'en-tête Authorization n'atteint pas PHP — ce qui arrive en CGI et FastCGI sans configuration supplémentaire —, vous pouvez utiliser X-API-Token à la place. Il existe aussi ?token=, prévu pour essayer depuis un navigateur et à ne pas utiliser en production : un jeton dans la barre d'adresse se retrouve dans les journaux du serveur et dans l'en-tête Referer de tout lien sortant.

Réponses et erreurs

La réponse est toujours du JSON, erreurs comprises — un client qui reçoit du HTML en cas d'échec n'a aucun moyen d'indiquer à son auteur ce qui a échoué. Une erreur a toujours cette forme :

{
  "erro": {
    "codigo": "token_invalido",
    "mensagem": "Token inválido ou sem subscrição activa."
  }
}

Lecture

L'API voit exactement ce que la personne voit dans le panneau : le titulaire du compte entreprise et les gestionnaires voient les fichiers de toute l'équipe, les autres voient les leurs.

Envoyer des fichiers

L'envoi se fait par session, en morceaux, et non en une seule requête. La raison est pratique : un fichier de plusieurs gigaoctets ne tient pas dans une requête — il se heurte aux limites de taille et de durée de PHP et de tout proxy sur le chemin, et lorsqu'il échoue à 90 %, il n'y a rien à récupérer. Par morceaux, chaque requête est petite, et celui qui décroche reprend là où il s'était arrêté.

Le paramètre offset est facultatif mais recommandé : il indique à quel octet commence le morceau. S'il ne correspond pas à ce que le serveur possède déjà, la requête est refusée avec 409 et la réponse contient la bonne valeur — ce qui permet de reprendre sans envoyer deux fois le même morceau.

Les mêmes règles que pour l'envoi depuis le panneau s'appliquent : le quota est vérifié à l'ouverture de la session (sur la taille annoncée) puis à nouveau à la clôture (sur la taille réelle sur le disque), et les types de fichiers que le serveur pourrait exécuter sont refusés.

Exemple complet

Envoyer un fichier par morceaux de 8 Mo :

TOKEN=<token>
BASE=https://www.youstorecloud.com/api/v1/
FICHEIRO=video.mp4
TAMANHO=$(stat -c%s "$FICHEIRO")

# 1. abrir a sessao
UPLOAD=$(curl -s -H "Authorization: Bearer $TOKEN" \
  -X POST "$BASE"uploads \
  -F "nome=$FICHEIRO" -F "tamanho=$TAMANHO" \
  | sed -n 's/.*"upload_id":"\([0-9a-f]*\)".*/\1/p')

# 2. enviar em pedacos de 8 MB, a partir do byte 0
split -b 8M "$FICHEIRO" parte_
OFFSET=0
for PARTE in parte_*; do
  curl -s -H "Authorization: Bearer $TOKEN" \
    -X POST "$BASE"uploads/"$UPLOAD"?offset=$OFFSET \
    -F "pedaco=@$PARTE"
  OFFSET=$((OFFSET + $(stat -c%s "$PARTE")))
done

# 3. fechar — devolve o ficheiro e o link de partilha
curl -s -H "Authorization: Bearer $TOKEN" \
  -X POST "$BASE"uploads/"$UPLOAD"/concluir

Reprendre un envoi interrompu

curl -s -H "Authorization: Bearer $TOKEN" "$BASE"uploads/"$UPLOAD"
# {"upload_id":"...","nome":"video.mp4","tamanho":5000000,"recebido":3200000,"falta":1800000}

# continuer à partir de l'octet indiqué dans "recebido"

Limites