# Início rápido

Entre na sandbox, crie uma chave de teste restrita, liste os clientes de exemplo e receba o primeiro evento assinado no seu servidor local.


## O que vai construir

Uma integração mínima que corre na sandbox da sua empresa de água: uma chave de teste com uma única permissão, um pedido que devolve os clientes de exemplo e um servidor local que recebe eventos assinados através da CLI `gotactl`. Tudo acontece num espaço de testes separado, por isso nenhum passo altera os dados reais da empresa.

## Pré-requisitos

- Uma conta com sandbox. Quando o plano inclui ambientes de teste, o registo cria uma sandbox com dados de exemplo e dá-lhe o papel de proprietário nela. No painel, entre nela pelo menu da conta, em **Mudar para sandbox**.
- A CLI `gotactl` instalada e `curl`, Node.js, Python ou Go no seu computador.
- A permissão `developer:write` na sandbox, para criar a chave. A chave, por sua vez, só precisa de `business:customers:read`, a permissão da operação `listCustomers`.
- Um servidor local que responda `200` em `http://localhost:3000/hook`, para o passo 3.

## 1. Criar uma chave de teste restrita

Inicie sessão na CLI directamente no contexto da sandbox (o ID aparece em `gotactl contexts list`) e crie a chave. Ao indicar uma permissão, a chave fica restrita; na sandbox, o modo é sempre teste.

```bash
gotactl auth login --context mbr_2pQ6vRb2HkT9wF4nJ7cX1sL3yGm
gotactl api-keys create --name inicio-rapido --mode test \
  --scope business:customers:read --out key.txt
export API_KEY="$(cat key.txt)"
```

Prefere o painel? Abra **Programadores** e o separador **Chaves de API**, carregue em **Nova chave**, preencha o **Nome**, escolha **Restrita: à sua escolha** em **Tipo** e **Teste** em **Modo**, marque `business:customers:read` e carregue em **Criar chave**. A chave completa só aparece uma vez, logo depois de criada.

✓ Checkpoint: a CLI mostra o `id` da chave (começa por `key_`), o `prefix` e o `mode` `test`, e o ficheiro `key.txt` guarda uma chave que começa por `sk_rtest_`.

## 2. Fazer o primeiro pedido

Envie a chave no cabeçalho `Authorization: Bearer`. O parâmetro `limit` aceita de 1 a 100.

```bash
curl -sS "$BUSINESS_API/customers?limit=5" \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch("$BUSINESS_API/customers?limit=5", {
  headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const page = await res.json();
```

```python
import os, requests

res = requests.get(
    "$BUSINESS_API/customers?limit=5",
    headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
page = res.json()
```

```go
req, _ := http.NewRequest("GET", "$BUSINESS_API/customers?limit=5", nil)
req.Header.Set("Authorization", "Bearer "+os.Getenv("API_KEY"))
resp, err := http.DefaultClient.Do(req)
```

A resposta, encurtada a um cliente:

```json
{
  "data": [
    {
      "id": "cus_2pQ7xKfR9mW3nT8vB4yL6cJ1dHs",
      "tenant_id": "ten_2pQ8aNcV5tY2kM7wE3rU9gZ4bXf",
      "customer_type": "individual",
      "category": "residential",
      "display_name": "Ana Macuácua",
      "phone": "+258841234567",
      "status": "active",
      "created_at": "2026-11-02T09:14:07Z",
      "updated_at": "2026-11-02T09:14:07Z"
    }
  ],
  "has_more": true,
  "next_cursor": "Y3VzXzJwUTlmTGhTM2pENnFBMXpDOHZONW1LN2VSdHwxNzkzNjExOTA0NTEyMDAwMDAw"
}
```

✓ Checkpoint: o estado é `200`, `data` é uma lista de clientes com `id` a começar por `cus_` e `has_more` diz se há mais páginas; nesse caso, peça a seguinte com `after` igual a `next_cursor`.

## 3. Receber o primeiro evento no servidor local

A CLI lê os eventos da sandbox e reenvia cada um para o seu servidor, assinado com os cabeçalhos `webhook-id`, `webhook-timestamp` e `webhook-signature`. O segredo de assinatura, que começa por `whsec_`, aparece no arranque.

```bash
gotactl webhooks listen --forward-to http://localhost:3000/hook
```

Noutro terminal, provoque um evento verdadeiro: a CLI cria e emite uma factura de teste e regista um pagamento do mesmo valor, o que deixa a factura paga.

```bash
gotactl events trigger invoice.paid
```

✓ Checkpoint: o terminal de `webhooks listen` imprime uma linha como `2026-11-19T10:42:05Z  --> invoice.paid [wev_2pQ9fLhS3jD6qA1zC8vN5mK7eRt]  <-- 200 OK (12ms)`, com o estado que o seu servidor devolveu.

## Testar

No painel, abra **Programadores** e o separador **Eventos**: o `invoice.paid` está na lista, com o conteúdo completo no detalhe. O pedido do passo 2 aparece em **Registos**, identificado pelo prefixo da chave. Pela linha de comandos, `gotactl customers list --limit 5` devolve a mesma página.

## Próximos passos

- [Verificar a assinatura de cada webhook](/docs/webhooks/verify)
- [Que permissões dar a cada chave restrita](/docs/getting-started/restricted-keys)
- [O que a sandbox inclui e como simular pagamentos](/docs/getting-started/sandbox)
- [Importar os seus clientes pela API](/docs/guides/import-customers)

