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

# SDK Go: início rápido e cliente

> Instale o SDK Go (sdk-api-go v3), crie um cliente com sua chave de API e siga as convenções: context, ids, aplicações de workspace, datas e timeouts.

<Info>
  Esta página documenta o **`github.com/squarecloudofc/sdk-api-go/v3`** (v3.0.0), uma reescrita do SDK. Vindo da v2? Leia o [guia de migração v2 → v3](/pt-br/sdks/go/migrating_to_v3).
</Info>

## Requisitos

* **Go 1.22** ou superior.
* Uma chave de API (veja [Chave de API e escopos](#chave-de-api-e-escopos)).

O módulo **não tem dependências** além da biblioteca padrão do Go e é licenciado sob **MIT** (a v2 era AGPL-3.0). O nome do seu pacote é `squarecloud`.

## Instalação

```bash theme={"system"}
go get github.com/squarecloudofc/sdk-api-go/v3
```

```go theme={"system"}
import "github.com/squarecloudofc/sdk-api-go/v3" // package squarecloud
```

## Chave de API e escopos

Crie uma chave em [squarecloud.app/account/security](https://squarecloud.app/pt-br/account/security). O SDK a envia como está no header `Authorization` (sem o prefixo `Bearer`).

Uma chave pode ser limitada a **escopos** (`apps:read`, `apps:deploy`, `apps:control`, `ai:chat`, ...) e a aplicações ou bancos de dados específicos:

* Uma chamada fora desses limites retorna um [`*APIError`](/pt-br/sdks/go/errors) com 403 `MISSING_SCOPE` ou `RESOURCE_NOT_ALLOWED`.
* Métodos de listagem (`Account.Me`, `Apps.StatusAll`, ...) retornam apenas os recursos que a chave pode ver.
* Uma chave desconhecida, revogada ou expirada resulta em 401 `ACCESS_DENIED`.

<Warning>
  Mantenha a chave fora do seu código-fonte e dos binários que você distribui. Leia-a do ambiente ou de um cofre de segredos.
</Warning>

Os exemplos leem a chave da variável de ambiente `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>

## Criando o cliente

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

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

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

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

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

Salve-o como `main.go` em um módulo (`go mod init example.com/hello` e depois o `go get` acima) e execute `go run .`. Ele 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
```

`squarecloud.New(apiKey, opts...)` retorna um `*Client` e **nunca um erro**. Um `*Client` é seguro para uso concorrente: crie-o uma vez e compartilhe-o entre goroutines.

Como `New` não pode falhar, uma chave vazia ou composta apenas de espaços não é rejeitada ali. Em vez disso, toda chamada, exceto `Service.Status`, falha localmente com `INVALID_API_KEY` (status `0`) antes de qualquer requisição. Esse código existe apenas no SDK Go.

### Opções

Passe as opções para `New` depois da chave:

```go theme={"system"}
c := squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"),
	squarecloud.WithBaseURL(squarecloud.DefaultBaseURL), // "https://api.squarecloud.app/v2" (default)
	squarecloud.WithTimeout(30*time.Second),
	squarecloud.WithMaxRetries(2),
	squarecloud.WithUserAgent("my-bot/1.0"),
	squarecloud.WithHTTPClient(&http.Client{ // proxy, tracing, tests
		Transport: &http.Transport{Proxy: http.ProxyFromEnvironment},
	}),
)
```

| Opção | Padrão | Descrição |
| - | - | - |
| `WithBaseURL(u)` | `https://api.squarecloud.app/v2` | URL base da API. Uma `/` final é removida. Também exportada como `DefaultBaseURL`. |
| `WithTimeout(d)` | `30*time.Second` | Prazo padrão de uma chamada cujo `ctx` não tem nenhum. Ele cobre a chamada inteira, novas tentativas incluídas. Veja [Timeouts](#timeouts). |
| `WithMaxRetries(n)` | `2` | Novas tentativas apenas de falhas seguras (até 3 tentativas). Um valor negativo conta como `0`. Veja [Novas tentativas](/pt-br/sdks/go/errors#novas-tentativas). |
| `WithUserAgent(ua)` | `squarecloud-sdk-go/<version>` | Substitui todo o header `User-Agent`. |
| `WithHTTPClient(hc)` | `&http.Client{}` | Um `*http.Client` personalizado para proxies, tracing ou testes. `nil` mantém o padrão. |

<Warning>
  Não defina `Timeout` no `*http.Client` que você passa para `WithHTTPClient`. Esse timeout também cobre a leitura do corpo, então cortaria os streams de [tempo real](/pt-br/sdks/go/realtime) e os downloads de snapshots. Use contexts, `WithTimeout` e os timeouts do `http.Transport` em vez disso.
</Warning>

O SDK nunca gera logs. Para rastrear requisições, envolva o `http.RoundTripper` do cliente que você passa para `WithHTTPClient`.

<Warning>
  A chave de API é armazenada em um campo não exportado do cliente. O `fmt` imprime campos não exportados, então não imprima o cliente com `%v` ou `%+v`.
</Warning>

## Executando os exemplos

Os trechos das páginas do SDK Go são fragmentos. Cada um roda sozinho dentro deste programa, que declara o `ctx`, o `c` e o `appID` que eles usam:

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

import (
	"context"
	"os"

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

var (
	ctx   = context.Background()
	c     = squarecloud.New(os.Getenv("SQUARECLOUD_API_KEY"))
	appID = "abc123def456abc123def456" // one of your apps: see Account below
)

func main() {
	// Paste one snippet here, then run goimports.
}
```

Cole **um trecho de cada vez** em `main` e execute `goimports -w .` para adicionar os imports de que ele precisa (`fmt`, `log`, `time`, ...). Instale-o com `go install golang.org/x/tools/cmd/goimports@latest`, ou deixe a extensão Go do seu editor (gopls) adicionar os imports ao salvar. As páginas que precisam de outros ids, como o de um banco de dados ou de um workspace, começam com a própria versão deste programa.

## Módulos

| Campo | Cobre | Página |
| - | - | - |
| `c.Account` | `Me`, `Snapshots(ctx, scope)` | [Conta](#conta) e [Snapshots](/pt-br/sdks/go/snapshots) |
| `c.Service` | `Status` | [Status da plataforma](#status-da-plataforma) |
| `c.Apps` | Obter, excluir, status, ciclo de vida, logs, métricas, domínios, load balancers | [Gerenciando aplicações](/pt-br/sdks/go/managing_application) |
| `c.Apps.Create` / `Commit` | Uploads | [Commit e upload](/pt-br/sdks/go/commit_and_upload) |
| `c.Apps.Files` | Gerenciador de arquivos | [Gerenciando arquivos](/pt-br/sdks/go/managing_files) |
| `c.Apps.Envs` | Variáveis de ambiente | [Variáveis de ambiente](/pt-br/sdks/go/environment_variables) |
| `c.Apps.Deploys` | Deploys via webhook e GitHub App | [Deploys](/pt-br/sdks/go/deploys) |
| `c.Apps.Network` | Analytics, logs, DNS, domínio personalizado, cache | [Rede](/pt-br/sdks/go/network) |
| `c.Apps.Realtime` | Logs e status ao vivo | [Tempo real](/pt-br/sdks/go/realtime) |
| `c.Apps.Snapshots` / `c.Databases.Snapshots` / `c.DownloadSnapshot` | Backups | [Snapshots](/pt-br/sdks/go/snapshots) |
| `c.Databases` | Bancos de dados gerenciados | [Bancos de dados](/pt-br/sdks/go/databases) |
| `c.Workspaces` | Workspaces, membros e aplicações compartilhadas | [Workspaces](/pt-br/sdks/go/workspaces) |
| `c.AI` | `Chat` | [IA](/pt-br/sdks/go/ai) |

Além de `New` e das opções `With*`, o pacote exporta as constantes `DefaultBaseURL` e `Version`, o tipo [`APIError`](/pt-br/sdks/go/errors) com uma constante `Code*` por código de erro, constantes tipadas para entradas enumeradas (`DatabaseRedis`, `GroupView`, `ResetPassword`, `SnapshotScopeDatabases`, ...) e uma struct por formato da API, que você pode usar no seu próprio código:

```go theme={"system"}
func appNames(apps []squarecloud.AppSummary) []string {
	names := make([]string, 0, len(apps))
	for _, app := range apps {
		names = append(names, app.Name)
	}
	return names
}
```

## Convenções

### Context e ids primeiro, dados tipados de volta

Todo método recebe um `context.Context` primeiro e o id do recurso em seguida, e retorna **structs simples** (sem métodos, sem cache). As tags `json` são os nomes de campos da própria API (`created_at`, `version_id`, `lastModified`, `joinedAt`, `netIO`, ...), então a [referência da API](/pt-br/api-reference/authentication) se aplica diretamente: `CreatedAt` é `created_at`, `VersionID` é `version_id`. Campos que a API adicionar depois são ignorados, então nunca quebram a decodificação.

* Mutações retornam apenas um `error`, a menos que a API retorne dados (`Envs.*`, `Deploys.SetWebhook`, `Deploys.LinkGithubApp`, `Databases.ResetCredentials` e os métodos `Create`).
* Um resultado string é `""` quando a API não envia nada.
* Campos que a API pode enviar como `null` são **ponteiros**: verifique se são `nil` antes de usá-los.
* Contadores e tamanhos em bytes são `int64`.
* Listas vêm completas em uma única chamada: não há paginação.

```go theme={"system"}
app, err := c.Apps.Get(ctx, appID)
if err != nil {
	log.Fatal(err)
}
if app.Domain != nil { // *string: nil for apps without a web domain
	fmt.Println("https://" + *app.Domain)
}
```

Os grupos de recursos são campos simples de struct, então você pode guardar method values:

```go theme={"system"}
restart, logs := c.Apps.Restart, c.Apps.Logs

if err := restart(ctx, appID); err != nil {
	log.Fatal(err)
}
out, err := logs(ctx, appID)
if err != nil {
	log.Fatal(err)
}
fmt.Println(out)
```

### Aplicações de workspace

Todo `appID` também aceita a forma composta `<appId>-<workspaceId>` para atuar sobre uma aplicação compartilhada com você por meio de um [workspace](/pt-br/sdks/go/workspaces). `Workspaces.Get` e `Workspaces.List` retornam ids brutos; você mesmo monta o id composto:

```go theme={"system"}
workspaceID := "0123456789abcdef0123456789abcdef"

if err := c.Apps.Restart(ctx, appID+"-"+workspaceID); err != nil {
	log.Fatal(err)
}
```

### Ids são codificados

Ids no caminho da URL são codificados com percent-encoding. Um id vazio, `.` ou `..` chegaria a uma rota diferente, então ele falha localmente com `INVALID_ID` (status `0`) antes que qualquer coisa seja enviada. As rotas de workspace enviam seus ids no corpo: nelas, o `INVALID_ID` (400) vem do servidor.

### Datas

Os argumentos `start` e `end` (veja [Rede](/pt-br/sdks/go/network)) são valores `time.Time`, enviados como RFC 3339 em UTC (segundos inteiros). Nas respostas, as strings ISO 8601 da API são decodificadas para `time.Time`, e os campos que a API envia como milissegundos Unix permanecem números (`Plan.Duration` e `Uptime` como `*int64`, `FileEntry.LastModified` como `*float64`): converta-os com `time.UnixMilli`.

## Timeouts

| Chamada | Prazo padrão |
| - | - |
| Todas as outras chamadas | `WithTimeout` (30 s) |
| Chamadas que o servidor mantém abertas: `Start`/`Stop`/`Restart` de aplicações, `Start`/`Stop` de bancos de dados, `Databases.Create`, `Create`/`Restore` de snapshots, `AI.Chat` | Pelo menos **2 minutos** (um `WithTimeout` maior prevalece) |
| Uploads (`Apps.Create`, `Apps.Commit`), `Files.Write` acima de 1 MiB, `DownloadSnapshot` | Nenhum: cancele o `ctx` |
| `Apps.Realtime` | Apenas até os headers da resposta chegarem |

* O prazo padrão se aplica **apenas quando o `ctx` não tem prazo**. Um prazo no `ctx` sempre prevalece, seja menor ou maior que o padrão, mínimos incluídos.
* Um único prazo cobre a **chamada inteira**: todas as tentativas e as esperas entre as [novas tentativas](/pt-br/sdks/go/errors#novas-tentativas).
* `WithTimeout(0)` (ou qualquer `d <= 0`) desativa **todos** os prazos padrão, incluindo os mínimos de 2 minutos.

Todo método recebe um `ctx`, então você pode limitar ou cancelar qualquer chamada:

```go theme={"system"}
ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
defer cancel()

f, err := os.Open("build.zip")
if err != nil {
	log.Fatal(err)
}
defer f.Close()

if err := c.Apps.Commit(ctx, appID, f, "", ""); err != nil {
	log.Fatal(err)
}
```

Uma chamada cujo `ctx` expira retorna um `*APIError` com `TIMEOUT`, e uma cujo `ctx` é cancelado retorna `NETWORK_ERROR`, ambos com status `0`. Eles fazem unwrap para o erro do context, então `errors.Is(err, context.DeadlineExceeded)` e `errors.Is(err, context.Canceled)` funcionam. Um loop de [tempo real](/pt-br/sdks/go/realtime) retorna, em vez disso, o `ctx.Err()` puro.

## Conta

`c.Account.Me(ctx)` retorna o usuário autenticado, além das aplicações e bancos de dados que a chave pode ver.

```go theme={"system"}
me, err := c.Account.Me(ctx)
if err != nil {
	log.Fatal(err)
}

user := me.User
fmt.Println(user.ID, user.Name, user.Email, user.Plan.Name)
fmt.Println(user.Plan.Memory.Limit, user.Plan.Memory.Available, user.Plan.Memory.Used) // MB
if user.Plan.Duration != nil {
	fmt.Println("expires", time.UnixMilli(*user.Plan.Duration))
} else {
	fmt.Println("never expires")
}
```

| Campo | Descrição |
| - | - |
| `User` (`user`) | `ID`, `Name`, `Email`, `Locale`, `CreatedAt` e `Plan` (`Name`, `Memory`, `Duration`: o Unix ms em que o plano **expira**, `nil` se nunca expirar) |
| `Applications` (`applications`) | `[]AppSummary`: `ID`, `Name`, `Description` (`desc`), `RAM`, `Lang`, `Domain` (`*string`), `Custom` (`*string`), `Cluster`, `CreatedAt` |
| `Databases` (`databases`) | `[]DatabaseSummary`: `ID`, `Name`, `RAM`, `Type`, `Cluster`, `CreatedAt` |

`c.Account.Snapshots(ctx, scope)` lista todos os snapshots da conta: veja [Snapshots](/pt-br/sdks/go/snapshots#snapshots-da-conta).

## Status da plataforma

`c.Service.Status(ctx)` retorna o status público da plataforma. A rota não exige chave, e este é o único método que também funciona em um cliente criado com uma chave vazia.

```go theme={"system"}
status, err := c.Service.Status(ctx)
if err != nil {
	log.Fatal(err)
}

fmt.Println(status.Status) // "online" | "degraded" | "unknown"
fmt.Println(status.Message)

for name, service := range status.Services {
	fmt.Println(name, service.Status) // "operational" | "degraded" | "outage" | "maintenance" | "unknown"
}
```

`unknown` significa que a própria verificação não pôde ser executada: não é evidência de uma indisponibilidade.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Gerenciando aplicações" icon="server" href="/pt-br/sdks/go/managing_application">
    Status, ciclo de vida, logs e métricas.
  </Card>

  <Card title="Erros" icon="triangle-exclamation" href="/pt-br/sdks/go/errors">
    Classe de erro, novas tentativas e rate limits.
  </Card>

  <Card title="Introdução à API" icon="code" href="/pt-br/api-reference/introduction">
    URL base, autenticação e uma primeira requisição.
  </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>
</CardGroup>


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