API

Verbinden Sie Ihre Systeme mit Ihren Dateien: auflisten, hochladen und teilen über HTTP.

Wer Zugriff hat

Die API gehört zum Paket Unternehmen. Das Token gehört dem abonnierenden Konto, und dieses Konto haftet für alles, was die Integration tut. Nach dem Kauf finden Sie das Token unter Panel → API, mit Beispielen, die bereits Ihre Zugangsdaten enthalten.

Authentifizierung

Jede Anfrage trägt das Token im Authorization-Header. Eine Anfrage ohne Token oder mit einem Token aus einem abgelaufenen Abonnement erhält 401.

Authorization: Bearer <token>

Auf Servern, bei denen der Authorization-Header PHP nicht erreicht — das passiert bei CGI und FastCGI ohne zusätzliche Konfiguration —, können Sie stattdessen X-API-Token verwenden. Es gibt auch ?token=, das zum Ausprobieren im Browser gedacht ist und nicht in Produktion verwendet werden sollte: ein Token in der Adresszeile landet in den Server-Logs und im Referer-Header jedes ausgehenden Links.

Antworten und Fehler

Die Antwort ist immer JSON, auch bei Fehlern — ein Client, der im Fehlerfall HTML erhält, kann seinem Autor nicht mitteilen, was schiefgelaufen ist. Ein Fehler hat immer diese Form:

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

Lesen

Die API sieht genau das, was die Person im Panel sieht: der Inhaber des Unternehmenskontos und die Manager sehen die Dateien des gesamten Teams, alle anderen ihre eigenen.

Anfrage	Liefert
`GET /api/v1/`	Die Liste der verfügbaren Ressourcen.
`GET /api/v1/conta`	Das Konto, das Unternehmen (gekaufte und belegte Plätze) und das Kontingent — gesamt und verbraucht, in Dateien und in Bytes.
`GET /api/v1/utilizadores`	Die Personen im Unternehmen, mit ihrer jeweiligen Rolle und Dateianzahl.
`GET /api/v1/ficheiros`	Die sichtbaren Dateien. Parameter: `pagina`, `por_pagina` (max. 100) und `procurar`.
`GET /api/v1/ficheiros/{id}`	Eine Datei, mit ihrer Größe auf der Festplatte und einem versandfertigen Freigabelink.

Dateien hochladen

Der Upload läuft als Sitzung in Teilen, nicht als eine einzelne Anfrage. Der Grund ist praktisch: eine Datei von mehreren Gigabyte passt nicht in eine Anfrage — sie stößt an die Größen- und Zeitgrenzen von PHP und jedes Proxys auf dem Weg, und wenn sie bei 90 % scheitert, ist nichts zu retten. In Teilen ist jede Anfrage klein, und wer abbricht, macht dort weiter, wo er aufgehört hat.

Anfrage	Liefert
`POST /api/v1/uploads`	Öffnet die Sitzung. Felder: `nome` und `tamanho` (in Bytes). Liefert die `upload_id`.
`POST /api/v1/uploads/{id}`	Sendet einen Teil, im Feld `pedaco` oder im Anfragekörper. Liefert, wie viele Bytes angekommen sind.
`POST /api/v1/uploads/{id}/concluir`	Schließt die Sitzung, registriert die Datei und liefert sie mit dem Freigabelink zurück.
`GET /api/v1/uploads/{id}`	Wie viele Bytes angekommen sind. Hierüber wird ein unterbrochener Upload fortgesetzt.
`DELETE /api/v1/uploads/{id}`	Bricht den Upload ab und löscht das bereits Gesendete.

Der Parameter offset ist optional, aber empfohlen: er gibt an, bei welchem Byte der Teil beginnt. Stimmt er nicht mit dem überein, was der Server bereits hat, wird die Anfrage mit 409 abgelehnt und die Antwort enthält den richtigen Wert — was das Fortsetzen ermöglicht, ohne denselben Teil zweimal zu senden.

Es gelten dieselben Regeln wie beim Upload über das Panel: das Kontingent wird beim Öffnen der Sitzung geprüft (gegen die angegebene Größe) und erneut beim Abschluss (gegen die tatsächliche Größe auf der Festplatte), und Dateitypen, die der Server ausführen könnte, werden abgelehnt.

Vollständiges Beispiel

Eine Datei in 8-MB-Teilen hochladen:

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

Einen unterbrochenen Upload fortsetzen

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

# ab dem in "recebido" angegebenen Byte fortfahren

Grenzwerte

Maximale Größe je Teil	64 MB
Lebensdauer einer nicht abgeschlossenen Sitzung	24 Stunden
Dateien pro Seite in der Liste	100
Größe jeder Datei	Begrenzt durch das Kontingent Ihres Pakets.

Mein Token abrufen

Sprache

API-Dokumentation

API