Documentação da API

Quem tem acesso

A API faz parte do pacote Empresa. O token pertence à conta que o subscreve, e é essa conta que responde pelo que a integração fizer. Depois de comprar o pacote, o token está em Painel → API, com exemplos já preenchidos com as suas credenciais.

Autenticação

Todos os pedidos levam o token no cabeçalho Authorization. Um pedido sem token, ou com um token de uma subscrição expirada, recebe 401.

Authorization: Bearer <token>

Em servidores onde o cabeçalho Authorization não chega ao PHP — acontece em CGI e FastCGI sem configuração adicional — pode usar-se X-API-Token em vez dele. Há ainda ?token=, que existe para experimentar no browser e não deve ser usado em produção: um token na barra de endereço fica nos registos do servidor e no cabeçalho Referer de qualquer ligação para fora.

Respostas e erros

A resposta é sempre JSON, incluindo nos erros — um cliente que recebe HTML numa falha não tem como dizer a quem o escreveu o que correu mal. Um erro tem sempre esta forma:

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

Leitura

A API vê exactamente o que a pessoa vê no painel: quem tem a conta de empresa e os gestores vêem os ficheiros de toda a equipa, os restantes vêem os seus.

Enviar ficheiros

O envio é feito por sessão, em pedaços, e não num pedido único. A razão é prática: um ficheiro de vários gigabytes não passa num pedido só — esbarra nos limites de tamanho e de tempo do PHP e de qualquer proxy pelo caminho, e quando falha aos 90% não há nada a aproveitar. Em pedaços, cada pedido é pequeno, e quem cair a meio recomeça de onde parou.

O parâmetro offset é opcional mas recomendado: indica em que byte o pedaço começa. Se não corresponder ao que o servidor já tem, o pedido é recusado com 409 e a resposta traz o valor certo — que é o que permite retomar sem enviar duas vezes o mesmo pedaço.

Aplicam-se as mesmas regras do envio pelo painel: a quota é verificada ao abrir a sessão (pelo tamanho anunciado) e outra vez ao concluir (pelo tamanho real em disco), e os tipos de ficheiro que podem ser executados pelo servidor são recusados.

Exemplo completo

Enviar um ficheiro em pedaços 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

Retomar um envio interrompido

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

# continuar a partir do byte indicado em "recebido"

Limites