> ## 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.

# SDKs oficiais para JavaScript, Python e Go

> SDKs oficiais da Square Cloud para JavaScript, Python e Go, além do SDK do Blob Storage: escolha um, instale, defina sua chave de API e faça a primeira chamada.

## Escolha seu SDK

Todos os SDKs são open source e estão disponíveis no [GitHub](https://go.squarecloud.app/github). Eles têm **zero dependências em tempo de execução** e retornam os próprios dados da API, incluindo os nomes dos campos.

<CardGroup cols={2}>
  <Card title="JavaScript" icon={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path fill="#2563eb" d="M224 508c-6.7 0-13.5-1.8-19.4-5.2l-61.7-36.5c-9.2-5.2-4.7-7-1.7-8 12.3-4.3 14.8-5.2 27.9-12.7 1.4-.8 3.2-.5 4.6.4l47.4 28.1c1.7 1 4.1 1 5.7 0l184.7-106.6c1.7-1 2.8-3 2.8-5V149.3c0-2.1-1.1-4-2.9-5.1L226.8 37.7c-1.7-1-4-1-5.7 0L36.6 144.3c-1.8 1-2.9 3-2.9 5.1v213.1c0 2 1.1 4 2.9 4.9l50.6 29.2c27.5 13.7 44.3-2.4 44.3-18.7V167.5c0-3 2.4-5.3 5.4-5.3h23.4c2.9 0 5.4 2.3 5.4 5.3V378c0 36.6-20 57.6-54.7 57.6-10.7 0-19.1 0-42.5-11.6l-48.4-27.9C8.1 389.2.7 376.3.7 362.4V149.3c0-13.8 7.4-26.8 19.4-33.7L204.6 9c11.7-6.6 27.2-6.6 38.8 0l184.7 106.7c12 6.9 19.4 19.8 19.4 33.7v213.1c0 13.8-7.4 26.7-19.4 33.7L243.4 502.8c-5.9 3.4-12.6 5.2-19.4 5.2zm149.1-210.1c0-39.9-27-50.5-83.7-58-57.4-7.6-63.2-11.5-63.2-24.9 0-11.1 4.9-25.9 47.4-25.9 37.9 0 51.9 8.2 57.7 33.8.5 2.4 2.7 4.2 5.2 4.2h24c1.5 0 2.9-.6 3.9-1.7s1.5-2.6 1.4-4.1c-3.7-44.1-33-64.6-92.2-64.6-52.7 0-84.1 22.2-84.1 59.5 0 40.4 31.3 51.6 81.8 56.6 60.5 5.9 65.2 14.8 65.2 26.7 0 20.6-16.6 29.4-55.5 29.4-48.9 0-59.6-12.3-63.2-36.6-.4-2.6-2.6-4.5-5.3-4.5h-23.9c-3 0-5.3 2.4-5.3 5.3 0 31.1 16.9 68.2 97.8 68.2 58.4-.1 92-23.2 92-63.4z"/></svg>} href="/pt-br/sdks/js/client">
    `@squarecloud/api` v6. Aplicações, bancos de dados, workspaces, deploys, rede, tempo real, snapshots e IA, no Node.js, Deno, Bun e edge runtimes.
  </Card>

  <Card title="Python" icon={<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><path fill="#2563eb" d="M439.8 200.5c-7.7-30.9-22.3-54.2-53.4-54.2h-40.1v47.4c0 36.8-31.2 67.8-66.8 67.8H172.7c-29.2 0-53.4 25-53.4 54.3v101.8c0 29 25.2 46 53.4 54.3 33.8 9.9 66.3 11.7 106.8 0 26.9-7.8 53.4-23.5 53.4-54.3v-40.7H226.2v-13.6h160.2c31.1 0 42.6-21.7 53.4-54.2 11.2-33.5 10.7-65.7 0-108.6zM286.2 404c11.1 0 20.1 9.1 20.1 20.3 0 11.3-9 20.4-20.1 20.4-11 0-20.1-9.2-20.1-20.4.1-11.3 9.1-20.3 20.1-20.3zM167.8 248.1h106.8c29.7 0 53.4-24.5 53.4-54.3V91.9c0-29-24.4-50.7-53.4-55.6-35.8-5.9-74.7-5.6-106.8.1-45.2 8-53.4 24.7-53.4 55.6v40.7h106.9v13.6h-147c-31.1 0-58.3 18.7-66.8 54.2-9.8 40.7-10.2 66.1 0 108.6 7.6 31.6 25.7 54.2 56.8 54.2H101v-48.8c0-35.3 30.5-66.4 66.8-66.4zm-6.7-142.6c-11.1 0-20.1-9.1-20.1-20.3.1-11.3 9-20.4 20.1-20.4 11 0 20.1 9.2 20.1 20.4s-9 20.3-20.1 20.3z"/></svg>} href="/pt-br/sdks/py/client">
    `squarecloud-api` v5. A mesma cobertura, com um cliente síncrono e um assíncrono, usando apenas a biblioteca padrão.
  </Card>

  <Card title="Go" icon="golang" href="/pt-br/sdks/go/client">
    `sdk-api-go` v3. A mesma cobertura, com `context` em todas as chamadas e um único tipo de erro.
  </Card>

  <Card title="Blob Storage (JavaScript)" icon="box-archive" href="/pt-br/sdks/blob/client">
    `@squarecloud/blob` v4. Uploads de até 10 GiB, objetos privados, links, compartilhamentos, regras e o gateway S3, no Node.js e no navegador.
  </Card>
</CardGroup>

## Visão geral

| SDK | Pacote | Versão | Runtime | Instalação |
| - | - | - | - | - |
| JavaScript | `@squarecloud/api` | 6.0.0 | Node.js 22+, Deno, Bun, edge | `npm install @squarecloud/api` |
| Python | `squarecloud-api` (import `squarecloud`) | 5.0.0 | Python 3.11+ | `pip install squarecloud-api` |
| Go | `github.com/squarecloudofc/sdk-api-go/v3` | 3.0.0 | Go 1.22+ | `go get github.com/squarecloudofc/sdk-api-go/v3` |
| Blob Storage | `@squarecloud/blob` | 4.0.0 | Node.js 20+ e navegadores | `npm install @squarecloud/blob` |

## Início rápido

Faça sua primeira chamada em poucos minutos. Cada programa abaixo imprime o nome da sua conta e quantas aplicações a sua chave de API pode ver.

<Steps>
  <Step title="Crie uma chave de API">
    Crie uma chave nas [configurações de segurança da sua conta](https://squarecloud.app/pt-br/account/security). Trate-a como uma senha: mantenha-a fora do seu código-fonte.
  </Step>

  <Step title="Defina a variável de ambiente SQUARECLOUD_API_KEY">
    Os exemplos leem a chave de `SQUARECLOUD_API_KEY`. Defina-a no terminal em que você vai executá-los:

    <Tabs>
      <Tab title="macOS / Linux">
        ```bash theme={"system"}
        export SQUARECLOUD_API_KEY="your-api-key"
        ```
      </Tab>

      <Tab title="Windows (PowerShell)">
        ```powershell theme={"system"}
        $env:SQUARECLOUD_API_KEY = "your-api-key"
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Instale o SDK e faça sua primeira chamada">
    <Tabs>
      <Tab title="JavaScript">
        ```bash theme={"system"}
        npm install @squarecloud/api
        ```

        ```javascript index.mjs theme={"system"}
        import { SquareCloudAPI } from "@squarecloud/api";

        const api = new SquareCloudAPI(process.env.SQUARECLOUD_API_KEY);
        const { user, applications } = await api.account.me();

        console.log(`Hi ${user.name}, you have ${applications.length} apps`);
        ```

        ```bash theme={"system"}
        node index.mjs
        ```
      </Tab>

      <Tab title="Python">
        ```bash theme={"system"}
        pip install squarecloud-api
        ```

        ```python main.py theme={"system"}
        import os

        from squarecloud import SquareCloud

        with SquareCloud(os.environ["SQUARECLOUD_API_KEY"]) as client:
            me = client.account.me()
            print(f"Hi {me['user']['name']}, you have {len(me['applications'])} apps")
        ```

        ```bash theme={"system"}
        python main.py
        ```
      </Tab>

      <Tab title="Go">
        ```bash theme={"system"}
        go mod init example.com/hello
        go get github.com/squarecloudofc/sdk-api-go/v3
        ```

        ```go main.go theme={"system"}
        package main

        import (
        	"context"
        	"fmt"
        	"log"
        	"os"

        	"github.com/squarecloudofc/sdk-api-go/v3"
        )

        func main() {
        	c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))

        	me, err := c.Account.Me(context.Background())
        	if err != nil {
        		log.Fatal(err)
        	}
        	fmt.Printf("Hi %s, you have %d apps\n", me.User.Name, len(me.Applications))
        }
        ```

        ```bash theme={"system"}
        go run .
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Confira a saída">
    O programa imprime o nome da sua conta e o número de aplicações que a chave pode ver:

    ```text theme={"system"}
    Hi Jane, you have 3 apps
    ```

    Um erro 401 `ACCESS_DENIED` significa que a chave está errada, foi revogada ou expirou. Se a variável não estiver definida, o programa para antes de enviar qualquer coisa.
  </Step>
</Steps>

## O que cada SDK cobre

Os SDKs de **JavaScript**, **Python** e **Go** cobrem toda a [API da Square Cloud](/pt-br/api-reference/authentication): as mesmas 67 operações, além do download de arquivos de snapshot. Eles compartilham a mesma estrutura de páginas, os mesmos exemplos e o mesmo comportamento:

* uma única classe de erro, com o status HTTP e o código de erro da API;
* um timeout de 30 segundos, e de pelo menos 120 segundos para chamadas que o servidor mantém abertas;
* novas tentativas apenas para falhas que podem ser repetidas com segurança, nunca para um `429`;
* ids `<appId>-<workspaceId>` para atuar sobre aplicações compartilhadas por meio de um workspace.

O SDK de **Blob Storage** cobre a [API de Blob](/pt-br/blob-reference/authentication) e o [gateway S3](/pt-br/blob-reference/s3-compatibility). É um pacote separado, com seu próprio cliente, credenciais e códigos de erro.

## Referências de erros

Cada página de erros dos SDKs cobre a classe de erro, as novas tentativas e os rate limits. Os códigos de erro em si vêm da API: a [referência de erros da API](/pt-br/api-reference/errors) lista todos eles, e a [referência de erros da API do Blob](/pt-br/blob-reference/errors) lista os códigos do Blob Storage.

| SDK | Erros, novas tentativas e rate limits |
| - | - |
| JavaScript | [`SquareCloudAPIError`](/pt-br/sdks/js/errors) |
| Python | [`SquareCloudAPIError`](/pt-br/sdks/py/errors) |
| Go | [`*APIError`](/pt-br/sdks/go/errors) |
| Blob Storage | [`SquareCloudBlobError`](/pt-br/sdks/blob/errors) |

## Atualizando

Cada versão dos SDKs da API acima é uma reescrita. Veja os guias de migração: [JavaScript v5 → v6](/pt-br/sdks/js/migrating_to_v6), [Python v4 → v5](/pt-br/sdks/py/migrating_to_v5), [Go v2 → v3](/pt-br/sdks/go/migrating_to_v3) e [Blob v3 → v4](/pt-br/sdks/blob/migrating_to_v4).

A Square Cloud continua melhorando seus SDKs e adicionando novas linguagens. Se a sua não estiver aqui, [nos avise](https://go.squarecloud.app/github).

## Próximos passos

<CardGroup cols={3}>
  <Card title="Introdução à API" icon="code" href="/pt-br/api-reference/introduction">
    Chame a API REST diretamente, com curl.
  </Card>

  <Card title="Início rápido da CLI" icon="terminal" href="/pt-br/cli-reference/quickstart">
    Faça deploy e gerencie aplicações pelo terminal.
  </Card>

  <Card title="Guia rápido da API do Blob" icon="box-archive" href="/pt-br/blob-reference/quickstart">
    Envie um arquivo para o Blob Storage com curl.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.