Documentación de la API

Quién tiene acceso

La API forma parte del paquete Empresa. El token pertenece a la cuenta que lo contrata, y es esa cuenta la que responde por lo que haga la integración. Tras comprar el paquete, el token está en Panel → API, con ejemplos ya rellenados con sus credenciales.

Autenticación

Todas las peticiones llevan el token en la cabecera Authorization. Una petición sin token, o con un token de una suscripción caducada, recibe 401.

Authorization: Bearer <token>

En servidores donde la cabecera Authorization no llega a PHP — ocurre con CGI y FastCGI sin configuración adicional — puede usarse X-API-Token en su lugar. También existe ?token=, pensado para probar en el navegador y que no debe usarse en producción: un token en la barra de direcciones acaba en los registros del servidor y en la cabecera Referer de cualquier enlace saliente.

Respuestas y errores

La respuesta es siempre JSON, también en los errores — un cliente que recibe HTML ante un fallo no tiene forma de decirle a quien lo escribió qué salió mal. Un error tiene siempre esta forma:

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

Lectura

La API ve exactamente lo que la persona ve en el panel: el titular de la cuenta de empresa y los gestores ven los archivos de todo el equipo, el resto ve los suyos.

Subir archivos

El envío se hace por sesión, en trozos, y no en una única petición. La razón es práctica: un archivo de varios gigabytes no cabe en una sola petición — choca con los límites de tamaño y de tiempo de PHP y de cualquier proxy por el camino, y cuando falla al 90% no queda nada aprovechable. Por trozos, cada petición es pequeña, y quien se cae a medias retoma donde quedó.

El parámetro offset es opcional pero recomendable: indica en qué byte empieza el trozo. Si no coincide con lo que el servidor ya tiene, la petición se rechaza con 409 y la respuesta trae el valor correcto — que es lo que permite reanudar sin enviar dos veces el mismo trozo.

Se aplican las mismas reglas que al subir desde el panel: la cuota se comprueba al abrir la sesión (con el tamaño declarado) y otra vez al concluir (con el tamaño real en disco), y se rechazan los tipos de archivo que el servidor podría ejecutar.

Ejemplo completo

Subir un archivo en trozos de 8 MB:

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

Reanudar un envío interrumpido

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

# continuar desde el byte indicado en "recebido"

Límites