SDKs oficiales para JavaScript, Python y Go

Elige tu SDK

Todos los SDKs son de código abierto y están disponibles en GitHub. No tienen ninguna dependencia en tiempo de ejecución y devuelven los datos tal como los entrega la API, incluidos los nombres de los campos.

JavaScript

@squarecloud/api v6. Aplicaciones, bases de datos, workspaces, deploys, red, tiempo real, snapshots e IA, en Node.js, Deno, Bun y entornos edge.

Python

squarecloud-api v5. La misma cobertura, con un cliente síncrono y otro asíncrono, usando solo la biblioteca estándar.

Go

sdk-api-go v3. La misma cobertura, con context en cada llamada y un único tipo de error.

Blob Storage (JavaScript)

@squarecloud/blob v4. Subidas de hasta 10 GiB, objetos privados, enlaces, comparticiones, reglas y el gateway S3, en Node.js y en el navegador.

De un vistazo

SDK	Paquete	Versión	Entorno de ejecución	Instalación
JavaScript	`@squarecloud/api`	6.0.0	Node.js 22+, Deno, Bun, edge	`npm install @squarecloud/api`
Python	`squarecloud-api` (importa `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+ y navegadores	`npm install @squarecloud/blob`

Inicio rápido

Haz tu primera llamada en pocos minutos. Cada programa de abajo imprime el nombre de tu cuenta y cuántas aplicaciones puede ver tu clave de API.

Crea una clave de API

Crea una clave en la configuración de seguridad de tu cuenta. Trátala como una contraseña: mantenla fuera de tu código fuente.

Define la variable de entorno SQUARECLOUD_API_KEY

Los ejemplos leen la clave de SQUARECLOUD_API_KEY. Defínela en la terminal donde los ejecutes:

macOS / Linux
Windows (PowerShell)

export SQUARECLOUD_API_KEY="your-api-key"

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

Instala el SDK y haz tu primera llamada

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 .

Comprueba la salida

El programa imprime el nombre de tu cuenta y el número de aplicaciones que la clave puede ver:

Hi Jane, you have 3 apps

Un error 401 ACCESS_DENIED significa que la clave es incorrecta, fue revocada o expiró. Si la variable no está definida, el programa se detiene antes de enviar nada.

Qué cubre cada SDK

Los SDKs de JavaScript, Python y Go cubren toda la API de Square Cloud: las mismas 67 operaciones, además de la descarga de archivos de snapshot. Comparten la misma estructura de páginas, los mismos ejemplos y el mismo comportamiento:

una única clase de error, con el estado HTTP y el código de error de la API;
un timeout de 30 segundos, y de al menos 120 segundos para las llamadas que el servidor mantiene abiertas;
reintentos solo para los fallos que es seguro repetir, nunca para un 429;
ids <appId>-<workspaceId> para actuar sobre aplicaciones compartidas a través de un workspace.

El SDK de Blob Storage cubre la API de Blob y el gateway S3. Es un paquete independiente, con su propio cliente, credenciales y códigos de error.

Referencias de errores

Cada página de errores de un SDK cubre su clase de error, sus reintentos y sus límites de tasa. Los códigos de error en sí vienen de la API: la referencia de errores de la API enumera todos, y la referencia de errores de la API de Blob enumera los códigos de Blob Storage.

SDK	Errores, reintentos y límites de tasa
JavaScript	`SquareCloudAPIError`
Python	`SquareCloudAPIError`
Go	`*APIError`
Blob Storage	`SquareCloudBlobError`

Actualización

Cada una de las versiones de los SDKs de la API indicadas arriba es una reescritura. Consulta las guías de migración: JavaScript v5 → v6, Python v4 → v5, Go v2 → v3 y Blob v3 → v4. Square Cloud sigue mejorando sus SDKs y añadiendo nuevos lenguajes. Si falta el tuyo, avísanos.

Próximos pasos

Introducción a la API

Llama a la API REST directamente, con curl.

Inicio rápido de la CLI

Haz deploy y gestiona aplicaciones desde la terminal.

Inicio rápido de la API de Blob

Sube un archivo a Blob Storage con curl.

​Elige tu SDK

JavaScript

Python

Go

Blob Storage (JavaScript)

​De un vistazo

​Inicio rápido

​Qué cubre cada SDK

​Referencias de errores

​Actualización

​Próximos pasos