Primeiros passos

Prefere o terminal? A CLI visor faz estes passos com visor auth login e visor tx add.

Crie um token

Abra Configurações > Apps Conectados no Visor e encontre o card API pessoal.

Dê ao token um nome fácil de reconhecer, como Planilha de gastos.
Escolha o que o token pode fazer. Escolha Leitura e registro de transações, porque este guia registra um gasto.
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.
Selecione Criar token e copie o valor que começa com visor_pat_.

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.

Guarde o token numa variável de ambiente

export VISOR_TOKEN="visor_pat_..."

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

Liste seus espaços

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:

{
  "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.

Encontre uma conta e uma categoria

Troque SPACE_ID por um id do passo anterior:

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.

Registre um gasto

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:

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

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.

Confira no Visor

Abra Transações 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.
Encontre categorias e tags em Espaços e dados de referência.
Entenda como funcionam a autenticação e os escopos.
Trate erros e limites de requisição no seu cliente.

Comece aqui

Essencial

Próximos passos

​Próximos passos

Próximos passos