> ## Documentation Index
> Fetch the complete documentation index at: https://docs.visorfinance.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Primeiros passos

> Registre seu primeiro gasto a partir de um script em poucos minutos.

> [!TIP]
>
> Prefere o terminal? A [CLI `visor`](https://docs.visorfinance.app/pt-BR/cli) faz estes passos com `visor auth login` e `visor tx add`.

**1. Crie um token**

Abra [Configurações > Apps Conectados](https://dashboard.visorfinance.app/settings/connected_apps) no Visor e encontre o card **API pessoal**.

1. Dê ao token um nome fácil de reconhecer, como `Planilha de gastos`.
2. Escolha o que o token pode fazer. Escolha **Leitura e registro de transações**, porque este guia registra um gasto.
3. Escolha por quanto tempo ele vale: 30, 90 (padrão) ou 365 dias. **Nunca expira** também existe, mas um token com validade é mais seguro.
4. Selecione **Criar token** e copie o valor que começa com `visor_pat_`.

> [!WARNING]
>
> O Visor mostra o token uma única vez. Guarde-o num gerenciador de senhas ou num cofre de segredos. Se você perder o token, revogue-o e crie outro.

**2. Guarde o token numa variável de ambiente**

```bash theme={null}
export VISOR_TOKEN="visor_pat_..."
```

Deixe o token fora do código, de URLs e de logs.

**3. Liste seus espaços**

```bash theme={null}
curl https://api.visorfinance.app/v1/spaces \
  --header "Authorization: Bearer $VISOR_TOKEN" \
  --header "Accept: application/json"
```

A resposta traz cada espaço que você criou ou para o qual foi convidado:

```json theme={null}
{
  "data": [
    {
      "id": "6f1c2a9e-1d7b-4c55-9a3e-2b8f0c4d5e61",
      "name": "Pessoal",
      "type": "personal",
      "default": true,
      "role": "owner"
    }
  ]
}
```

Use o `id` de um espaço nas próximas requisições desse espaço.

**4. Encontre uma conta e uma categoria**

Troque `SPACE_ID` por um `id` do passo anterior:

```bash theme={null}
curl https://api.visorfinance.app/v1/spaces/SPACE_ID/accounts \
  --header "Authorization: Bearer $VISOR_TOKEN"

curl https://api.visorfinance.app/v1/spaces/SPACE_ID/categories \
  --header "Authorization: Bearer $VISOR_TOKEN"
```

Copie o `id` da conta que pagou o gasto e o `id` da categoria dele. Uma categoria do sistema tem uma `key` que não muda, como `category.food_and_drinks`, então um script pode encontrá-la pela chave. Veja [Espaços e dados de referência](https://docs.visorfinance.app/pt-BR/reference-data.md).

**5. Registre um gasto**

```bash theme={null}
curl https://api.visorfinance.app/v1/spaces/SPACE_ID/transactions \
  --request POST \
  --header "Authorization: Bearer $VISOR_TOKEN" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: 2026-10-01-padaria" \
  --data '{
    "account_id": "ACCOUNT_ID",
    "category_id": "CATEGORY_ID",
    "description": "Padaria",
    "amount": "42.90",
    "type": "debit",
    "transacted_at": "2026-10-01T08:30:00-03:00"
  }'
```

A resposta é `201 Created`, com a transação nova. O valor vem como texto decimal, e a transação usa a moeda da conta:

```json theme={null}
{
  "data": {
    "id": "9c1e4b2a-7d3f-4e8a-b6c5-1a2b3c4d5e6f",
    "account_id": "ACCOUNT_ID",
    "category_id": "CATEGORY_ID",
    "tag_ids": [],
    "amount": "42.90",
    "type": "debit",
    "currency_code": "BRL",
    "source": "manual",
    "status": "posted",
    "ignored": false,
    "description": "Padaria",
    "merchant_name": null,
    "notes": null,
    "transacted_at": "2026-10-01T11:30:00Z",
    "created_at": "2026-10-01T11:31:02Z",
    "updated_at": "2026-10-01T11:31:02Z"
  }
}
```

**6. Repita com segurança**

Envie a mesma requisição de novo, com a mesma `Idempotency-Key`. O Visor não registra um segundo gasto: ele devolve o gasto que já tem, com o header `idempotent-replayed: true`. Assim seu script pode repetir uma requisição que deu timeout sem criar duplicatas. Veja [Idempotência](https://docs.visorfinance.app/pt-BR/idempotency.md).

**7. Confira no Visor**

Abra [Transações](https://dashboard.visorfinance.app/transactions) no Visor. O gasto está na conta e no espaço que você escolheu.

## Próximos passos

* Exporte seu histórico e edite transações em [Transações](https://docs.visorfinance.app/pt-BR/transactions.md).
* Encontre categorias e tags em [Espaços e dados de referência](https://docs.visorfinance.app/pt-BR/reference-data.md).
* Entenda como funcionam a [autenticação e os escopos](https://docs.visorfinance.app/pt-BR/authentication.md).
* Trate [erros](https://docs.visorfinance.app/pt-BR/errors.md) e [limites de requisição](https://docs.visorfinance.app/pt-BR/rate-limits.md) no seu cliente.


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