> ## 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.

# Transações

> Exporte seu histórico, registre transações e edite ou exclua 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](https://docs.visorfinance.app/pt-BR/reference-data.md) |
| `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`](https://docs.visorfinance.app/api-reference/transactions/list-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.

> [!NOTE]
>
> 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`:

```bash theme={null}
#!/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
```

> [!TIP]
>
> Com a [CLI `visor`](https://docs.visorfinance.app/pt-BR/cli), 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](https://docs.visorfinance.app/pt-BR/rate-limits.md) 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}`](https://docs.visorfinance.app/api-reference/transactions/get-a-transaction) devolve uma transação.

## Registre uma transação

[`POST /v1/spaces/{space_id}/transactions`](https://docs.visorfinance.app/api-reference/transactions/create-a-transaction) 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](https://docs.visorfinance.app/pt-BR/quickstart.md).

## Registre transações em lote

[`POST /v1/spaces/{space_id}/transactions/batch`](https://docs.visorfinance.app/api-reference/transactions/create-transactions-in-a-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`.

```json theme={null}
{
  "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](https://docs.visorfinance.app/pt-BR/rate-limits.md).

## Edite uma transação

[`PATCH /v1/spaces/{space_id}/transactions/{transaction_id}`](https://docs.visorfinance.app/api-reference/transactions/edit-a-transaction) 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.

```bash theme={null}
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}`](https://docs.visorfinance.app/api-reference/transactions/delete-a-transaction) 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`.


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