PT EN

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.

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"

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

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

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#