SDKs oficiais para JavaScript, Python e Go

Escolha seu SDK

Todos os SDKs são open source e estão disponíveis no 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.

JavaScript

@squarecloud/api v6. Aplicações, bancos de dados, workspaces, deploys, rede, tempo real, snapshots e IA, no Node.js, Deno, Bun e edge runtimes.

Python

squarecloud-api v5. A mesma cobertura, com um cliente síncrono e um assíncrono, usando apenas a biblioteca padrão.

Go

sdk-api-go v3. A mesma cobertura, com context em todas as chamadas e um único tipo de erro.

Blob Storage (JavaScript)

@squarecloud/blob v4. Uploads de até 10 GiB, objetos privados, links, compartilhamentos, regras e o gateway S3, no Node.js e no navegador.

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.

Crie uma chave de API

Crie uma chave nas configurações de segurança da sua conta. Trate-a como uma senha: mantenha-a fora do seu código-fonte.

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:

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

$env:SQUARECLOUD_API_KEY = "your-api-key"

Instale o SDK e faça sua primeira chamada

JavaScript
Python
Go

npm install @squarecloud/api

index.mjs

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`);

node index.mjs

pip install squarecloud-api

main.py

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")

python main.py

go mod init example.com/hello
go get github.com/squarecloudofc/sdk-api-go/v3

main.go

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))
}

go run .

Confira a saída

O programa imprime o nome da sua conta e o número de aplicações que a chave pode ver:

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.

O que cada SDK cobre

Os SDKs de JavaScript, Python e Go cobrem toda a API da Square Cloud: 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 e o gateway S3. É 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 lista todos eles, e a referência de erros da API do Blob lista os códigos do Blob Storage.

SDK	Erros, novas tentativas e rate limits
JavaScript	`SquareCloudAPIError`
Python	`SquareCloudAPIError`
Go	`*APIError`
Blob Storage	`SquareCloudBlobError`

Atualizando

Cada versão dos SDKs da API acima é uma reescrita. Veja os guias de migração: JavaScript v5 → v6, Python v4 → v5, Go v2 → v3 e Blob v3 → v4. A Square Cloud continua melhorando seus SDKs e adicionando novas linguagens. Se a sua não estiver aqui, nos avise.

Próximos passos

Introdução à API

Chame a API REST diretamente, com curl.

Início rápido da CLI

Faça deploy e gerencie aplicações pelo terminal.

Guia rápido da API do Blob

Envie um arquivo para o Blob Storage com curl.

​Escolha seu SDK

JavaScript

Python

Go

Blob Storage (JavaScript)

​Visão geral

​Início rápido

​O que cada SDK cobre

​Referências de erros

​Atualizando

​Próximos passos