> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Envio de Parte do Upload Blob

> Esta documentação fornece uma visão abrangente do endpoint PUT /v1/objects/chunked da API Blob da SquareCloud.

<ParamField header="Authorization" type="string" placeholder="Chave da API" required>
  A chave da API para sua conta. Você pode encontrá-la nas [configurações da conta](https://squarecloud.app/pt-br/account/security).
</ParamField>

Envio de parte envia um chunk de um upload aberto com [Início do upload](/pt-br/blob-reference/endpoint/chunked-init). O corpo são os **bytes brutos** do chunk, não multipart/form-data. Os números de parte vão de 1 a `max_parts` (205) e podem ser enviados em **qualquer ordem**; uma parte que falhou pode simplesmente ser reenviada com o mesmo número, e reenviar é seguro porque as partes são idempotentes.

Todo chunk, exceto o último, precisa ter entre **5 MB e 32 MB**; o último pode ser menor. Envie no máximo **6 partes em paralelo**: uma sétima parte em andamento retorna `TOO_MANY_CONCURRENT_CHUNKS`; nesse caso, aguarde uma terminar e reenvie essa parte. Com 6 partes em paralelo, chunks de 16 MB são um bom padrão para um navegador.

Esta rota é isenta do orçamento de API da conta (`plan.rate`), então um upload longo não esgota sua cota de API para o resto da plataforma. O limitador próprio da rota permite 60 partes a cada 10 segundos, com bloqueio de 10 segundos ao exceder isso.

<ParamField query="upload" type="string" placeholder="Upload token" required>
  O token `upload` opaco retornado pelo Início do upload.
</ParamField>

<ParamField query="part" type="number" placeholder="1..205" required>
  O número da parte, de 1 a 205. As partes podem ser enviadas em qualquer ordem.
</ParamField>

<ParamField body="body" type="binary" required>
  Os bytes brutos do chunk (`Content-Type: application/octet-stream`). **Não** é multipart/form-data.
</ParamField>

### Resposta

<ResponseField name="status" type="string">
  Indica se a chamada foi bem-sucedida. "success" se bem-sucedida, "error" caso contrário.
</ResponseField>

<ResponseField name="response" type="object">
  <Expandable title="Alternar objeto">
    <ResponseField name="part" type="number">
      O número da parte que foi armazenada.
    </ResponseField>

    <ResponseField name="size" type="number">
      O tamanho do chunk armazenado, em bytes.
    </ResponseField>

    <ResponseField name="etag" type="string">
      O ETag de armazenamento da parte. Apenas informativo: a conclusão relê a lista de partes do armazenamento, então você nunca o envia de volta.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request PUT \
    --url 'https://blob.squarecloud.app/v1/objects/chunked?upload=UPLOAD_TOKEN&part=1' \
    --header 'Authorization: SUA_API_KEY' \
    --header 'Content-Type: application/octet-stream' \
    --data-binary '@./chunk-1.bin'
  ```

  ```javascript JavaScript theme={null}
  const chunk = file.slice(0, 16 * 1024 * 1024); // primeiros 16 MB

  const params = new URLSearchParams({ upload: uploadToken, part: '1' });

  const response = await fetch(`https://blob.squarecloud.app/v1/objects/chunked?${params}`, {
    method: 'PUT',
    headers: {
      Authorization: 'SUA_API_KEY',
      'Content-Type': 'application/octet-stream',
    },
    body: chunk,
  });
  ```

  ```python Python theme={null}
  import requests

  with open('./bigfile.bin', 'rb') as f:
      chunk = f.read(16 * 1024 * 1024)

  response = requests.put(
      'https://blob.squarecloud.app/v1/objects/chunked',
      headers={'Authorization': 'SUA_API_KEY', 'Content-Type': 'application/octet-stream'},
      params={'upload': upload_token, 'part': 1},
      data=chunk,
  )
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "status": "success",
    "response": {
      "part": 1,
      "size": 16777216,
      "etag": "\"9bb58f26192e4ba00f01e2e7b136bbd8\""
    }
  }
  ```
</ResponseExample>

### Solução de problemas

<Tabs>
  <Tab title="Código 400">
    ### Relacionado ao Chunk

    <CodeGroup>
      ```json INVALID_UPLOAD_TOKEN theme={null}
      // O token de upload está ausente, malformado ou não pertence à sua conta.
      {
          "status": "error",
          "code": "INVALID_UPLOAD_TOKEN"
      }
      ```

      ```json INVALID_CHUNK_PART theme={null}
      // O número da parte deve ser um inteiro entre 1 e 205.
      {
          "status": "error",
          "code": "INVALID_CHUNK_PART"
      }
      ```

      ```json EMPTY_CHUNK theme={null}
      // O corpo do chunk estava vazio.
      {
          "status": "error",
          "code": "EMPTY_CHUNK"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Código 401">
    ### Não autorizado

    <CodeGroup>
      ```json ACCESS_DENIED theme={null}
      // A chave de API está ausente ou é inválida. Defina uma chave válida no cabeçalho Authorization.
      {
          "status": "error",
          "code": "ACCESS_DENIED"
      }
      ```

      ```json PERMISSION_DENIED theme={null}
      // A conta não possui um plano pago ativo. Enviar arquivos ao Blob Storage exige um plano pago.
      {
          "status": "error",
          "code": "PERMISSION_DENIED"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Código 404">
    ### Não encontrado

    <CodeGroup>
      ```json UPLOAD_NOT_FOUND theme={null}
      // O upload já foi concluído, cancelado ou expirou.
      {
          "status": "error",
          "code": "UPLOAD_NOT_FOUND"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Código 413">
    ### Payload grande demais

    <CodeGroup>
      ```json CHUNK_TOO_LARGE theme={null}
      // Cada chunk aceita até 32 MB.
      {
          "status": "error",
          "code": "CHUNK_TOO_LARGE"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Código 429">
    ### Limite de requisições

    <CodeGroup>
      ```json RATE_LIMITED theme={null}
      // Limite de partes atingido (60 partes por janela de 10s, bloqueio de 10s).
      {
          "status": "error",
          "code": "RATE_LIMITED"
      }
      ```

      ```json TOO_MANY_CONCURRENT_CHUNKS theme={null}
      // No máximo 6 chunks podem estar em andamento ao mesmo tempo. Aguarde um terminar e reenvie esta parte.
      {
          "status": "error",
          "code": "TOO_MANY_CONCURRENT_CHUNKS"
      }
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Código 500">
    ### Falha no upload

    <CodeGroup>
      ```json UPLOAD_FAILED theme={null}
      // Falha ao enviar o chunk. Reenvie esta parte.
      {
          "status": "error",
          "code": "UPLOAD_FAILED"
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>