Transações

Toda operação de transação age sobre um espaço: /v1/spaces/{space_id}/transactions. Uma transação fora desse espaço recebe 404 NOT_FOUND, igual a uma que não existe.

O objeto da transação

Campo	Significado
`amount`	Valor absoluto como texto decimal, como `"42.90"`, em `currency_code`
`type`	`debit` para dinheiro que sai, `credit` para dinheiro que entra
`currency_code`	A moeda da conta, como `BRL`
`source`	`manual` para uma transação que você registrou, `connected` para uma que o banco enviou, `apple_pay` para uma que o atalho do Apple Pay importou
`status`	`pending` ou `posted`. Uma transação manual com data futura é `pending`.
`ignored`	`true` quando a transação não entra nos totais
`category_id`, `tag_ids`	IDs de Espaços e dados de referência
`transacted_at`, `created_at`, `updated_at`	Horários RFC 3339 em UTC

Leia amount com um tipo decimal, não com ponto flutuante, para não perder nenhum centavo.

Liste e exporte seu histórico

GET /v1/spaces/{space_id}/transactions devolve uma página, das mais novas para as mais antigas. A ordem é fixa: transacted_at decrescente, depois id.

Parâmetro	Efeito
`from_date`, `to_date`	Dias a incluir, `AAAA-MM-DD`, no horário de Brasília. Sem `to_date`, a lista termina hoje.
`account_id`, `category_id`, `tag_id`	Só transações dessa conta, categoria ou tag
`type`	`debit` ou `credit`
`ignored`	`true` para só as ignoradas, `false` para só as que contam. Sem ele, vêm as duas.
`search`	Texto na descrição, no nome do estabelecimento ou nas notas
`limit`	Transações por página, de 1 a 100. O padrão é 50.
`after`	O `next_cursor` da página anterior

Cada resposta traz next_cursor. Envie esse valor em after para ler a próxima página, com os mesmos filtros. Na última página, next_cursor é null. O cursor é opaco: não monte nem altere esse valor.

Uma transação com data futura só aparece quando to_date inclui a data dela.

Este script exporta um ano de histórico para um arquivo JSON Lines. Ele precisa de curl e jq:

#!/usr/bin/env bash
set -euo pipefail

url="https://api.visorfinance.app/v1/spaces/$SPACE_ID/transactions"
query="from_date=2026-01-01&to_date=2026-12-31&limit=100"
cursor=""

: > transactions.jsonl

while :; do
  page=$(curl --silent --fail-with-body \
    --header "Authorization: Bearer $VISOR_TOKEN" \
    "$url?$query${cursor:+&after=$cursor}")

  echo "$page" | jq --compact-output '.data[]' >> transactions.jsonl
  cursor=$(echo "$page" | jq --raw-output '.next_cursor // empty')
  [ -z "$cursor" ] && break
done

Com a CLI visor, a mesma exportação cabe em uma linha: visor tx list --from 2026-01-01 --to 2026-12-31 --all --json | jq --compact-output '.data[]' > transactions.jsonl

Cada página conta no limite de requisições de 60 por minuto, então páginas de 100 exportam 6.000 transações por minuto. Uma transação que chega enquanto você percorre a lista não muda as linhas que você ainda não leu. Se uma sincronização adicionar uma transação mais antiga atrás da sua posição, leia aquele período de novo.

Veja uma transação

GET /v1/spaces/{space_id}/transactions/{transaction_id} devolve uma transação.

Registre uma transação

POST /v1/spaces/{space_id}/transactions registra uma transação manual. Ela exige o escopo pfm:transactions:write e o header Idempotency-Key.

Campo	Obrigatório	Observações
`account_id`	Sim	Uma conta do espaço. A transação usa a moeda dela.
`category_id`	Sim	Uma categoria do espaço
`description`	Sim	De 1 a 255 caracteres
`amount`	Sim	Texto decimal positivo com até 2 casas decimais, como `"42.90"`
`type`	Sim	`debit` ou `credit`
`transacted_at`	Sim	Horário RFC 3339 com fuso, como `2026-10-01T08:30:00-03:00`
`merchant_name`	Não	Até 255 caracteres
`notes`	Não	Até 500 caracteres
`ignored`	Não	`true` para deixar a transação fora dos totais
`tag_ids`	Não	Até 20 tags do espaço

Registre gastos numa conta manual. Uma conta conectada já recebe todas as transações do banco, então um registro manual nela pode contar duas vezes. Um campo fora desta tabela recebe 400 BAD_REQUEST. Um valor inválido ou um ID de outro espaço recebe 422 VALIDATION_FAILED, e o Visor não registra nada. O guia de primeiros passos tem um exemplo completo.

Registre transações em lote

POST /v1/spaces/{space_id}/transactions/batch registra de 1 a 100 transações. Ela exige o escopo pfm:transactions:write. Envie um objeto com uma lista transactions. Cada linha aceita os campos da criação individual e exige seu próprio idempotency_key. A chave aceita de 1 a 128 letras, dígitos ou - _ . :, como o header da criação individual. O lote não exige o header Idempotency-Key.

{
  "transactions": [
    {
      "account_id": "ACCOUNT_ID",
      "category_id": "CATEGORY_ID",
      "description": "Padaria",
      "amount": "42.90",
      "type": "debit",
      "transacted_at": "2026-10-01T08:30:00-03:00",
      "idempotency_key": "import-row-1"
    }
  ]
}

Um lote válido devolve 200 OK. A lista data traz um resultado por linha, na mesma ordem da entrada:

Campo	Significado
`index`	Posição na lista de entrada, começando em zero
`status`	`created`, `replayed` ou `failed`
`transaction`	O objeto da transação criada ou já registrada; `null` quando a linha falha
`error`	`null` em caso de sucesso; um objeto com `code`, `message` e `details` em caso de falha

Cada linha é salva de forma independente. Uma falha não desfaz os sucessos nem impede as próximas linhas. Um valor inválido devolve VALIDATION_FAILED com details.errors; uma linha malformada traz seu próprio erro. O objeto do lote deve conter apenas transactions, com 1 a 100 linhas. Um objeto malformado, uma lista vazia ou mais de 100 linhas devolve 400 BAD_REQUEST antes de registrar qualquer transação. Para tentar de novo, mantenha a chave original de cada linha. A mesma conta e chave compartilham o registro de idempotência da criação individual, então a nova tentativa devolve replayed sem criar outra transação. Mudar o valor, tipo, descrição, data ou categoria devolve IDEMPOTENCY_CONFLICT naquela linha. A mesma chave pode criar outra transação em outra conta. Cada lote conta como uma requisição no limite do token.

Edite uma transação

PATCH /v1/spaces/{space_id}/transactions/{transaction_id} muda só os campos do corpo. Ela exige o escopo pfm:transactions:write.

Campo	Transação manual	Transação conectada ou do Apple Pay
`category_id`, `notes`, `ignored`, `tag_ids`	Sim	Sim
`description`, `amount`, `type`, `transacted_at`	Sim	Não: `409 IMMUTABLE_PROVIDER_FIELD`

tag_ids substitui todas as tags. Uma lista vazia remove todas. Sem tag_ids, as tags continuam.
Um texto vazio em notes remove as notas. null não é aceito.
A edição é atômica. Se um valor for inválido, nada muda.
A conta de uma transação não muda.

curl https://api.visorfinance.app/v1/spaces/SPACE_ID/transactions/TRANSACTION_ID \
  --request PATCH \
  --header "Authorization: Bearer $VISOR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"category_id": "CATEGORY_ID", "tag_ids": ["TAG_ID"]}'

Exclua uma transação

DELETE /v1/spaces/{space_id}/transactions/{transaction_id} devolve 204 No Content. Ela exige o escopo pfm:transactions:write.

O Visor apaga uma transação manual e desfaz o efeito dela no saldo da conta.
O Visor oculta uma transação conectada, para que a próxima sincronização do banco não a traga de volta.
Uma transação da qual outro registro depende, como uma parcela paga, recebe 409 TRANSACTION_CONFLICT.

Comece aqui

Essencial

O objeto da transação

Liste e exporte seu histórico

Veja uma transação

Registre uma transação

Registre transações em lote

Edite uma transação

Exclua uma transação

​O objeto da transação

​Liste e exporte seu histórico

​Veja uma transação

​Registre uma transação

​Registre transações em lote

​Edite uma transação

​Exclua uma transação

O objeto da transação

Liste e exporte seu histórico

Veja uma transação

Registre uma transação

Registre transações em lote

Edite uma transação

Exclua uma transação