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
gotactlinstalada ecurl, Node.js, Python ou Go no seu computador. - A permissão
developer:writena sandbox, para criar a chave. A chave, por sua vez, só precisa debusiness:customers:read, a permissão da operaçãolistCustomers. - Um servidor local que responda
200emhttp://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.
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.
2. Fazer o primeiro pedido#
Envie a chave no cabeçalho Authorization: Bearer. O parâmetro limit aceita de 1 a 100.
curl -sS "$BUSINESS_API/customers?limit=5" \
-H "Authorization: Bearer $API_KEY"
const res = await fetch("$BUSINESS_API/customers?limit=5", {
headers: { Authorization: `Bearer ${process.env.API_KEY}` },
});
const page = await res.json();
import os, requests
res = requests.get(
"$BUSINESS_API/customers?limit=5",
headers={"Authorization": f"Bearer {os.environ['API_KEY']}"},
)
page = res.json()
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:
{
"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"
}
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.
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.
gotactl events trigger invoice.paid
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.