Contas e Transações

Acesso às contas bancárias e transações financeiras obtidas via Open Finance.

Endpoints

Método	Endpoint	Descrição	Permissão
GET	/api/v1/items/:itemId/accounts	Listar contas do item	OPENFINANCE_READ
GET	/api/v1/accounts/:id	Obter conta por ID	OPENFINANCE_READ
GET	/api/v1/accounts/:accountId/transactions	Listar transações	OPENFINANCE_READ
GET	/api/v1/transactions/:id	Obter transação por ID	OPENFINANCE_READ

---

Listar Contas de um Item

GET /api/v1/items/:itemId/accounts

Lista todas as contas bancárias associadas a um item (conexão).

Query Parameters

Parâmetro	Tipo	Descrição
filterAccountType	string	Filtrar por tipo: CHECKING, SAVINGS, CREDIT_CARD, INVESTMENT, LOAN
pageNumber	integer	Número da página
pageSize	integer	Itens por página

cURL

curl 'https://open-finance.stg.catalisa.app/api/v1/items/550e8400-e29b-41d4-a716-446655440001/accounts' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const itemId = '550e8400-e29b-41d4-a716-446655440001';

const response = await fetch(`https://open-finance.stg.catalisa.app/api/v1/items/${itemId}/accounts`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data } = await response.json();
data.forEach(account => {
  console.log(`${account.attributes.name} (${account.attributes.accountType}): R$ ${account.attributes.balance}`);
});

Response (200 OK)

{
  "data": [
    {
      "type": "openfinance-account",
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "attributes": {
        "name": "Conta Corrente",
        "accountType": "CHECKING",
        "balance": 5432.10,
        "currencyCode": "BRL",
        "number": "12345-6",
        "bankName": "Banco do Brasil",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    },
    {
      "type": "openfinance-account",
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "attributes": {
        "name": "Poupança",
        "accountType": "SAVINGS",
        "balance": 15000.00,
        "currencyCode": "BRL",
        "number": "12345-7",
        "bankName": "Banco do Brasil",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "meta": {
    "totalItems": 2,
    "totalPages": 1,
    "currentPage": 1,
    "itemsPerPage": 20
  }
}

---

Listar Transações de uma Conta

GET /api/v1/accounts/:accountId/transactions

Lista as transações financeiras de uma conta específica.

Query Parameters

Parâmetro	Tipo	Descrição
filterStartDate	datetime	Data inicial (ISO 8601)
filterEndDate	datetime	Data final (ISO 8601)
filterCategory	string	Filtrar por categoria
pageNumber	integer	Número da página
pageSize	integer	Itens por página (padrão: 50)

cURL

curl 'https://open-finance.stg.catalisa.app/api/v1/accounts/550e8400-e29b-41d4-a716-446655440010/transactions?filterStartDate=2024-01-01T00:00:00Z&filterEndDate=2024-01-31T23:59:59Z' \
  -H 'Authorization: Bearer SEU_TOKEN'

JavaScript

const accountId = '550e8400-e29b-41d4-a716-446655440010';
const params = new URLSearchParams({
  filterStartDate: '2024-01-01T00:00:00Z',
  filterEndDate: '2024-01-31T23:59:59Z',
});

const response = await fetch(
  `https://open-finance.stg.catalisa.app/api/v1/accounts/${accountId}/transactions?${params}`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);

const { data, meta } = await response.json();
console.log(`Total de transações: ${meta.totalItems}`);
data.forEach(tx => {
  const sinal = tx.attributes.type === 'CREDIT' ? '+' : '-';
  console.log(`${sinal} R$ ${tx.attributes.amount} - ${tx.attributes.description}`);
});

Response (200 OK)

{
  "data": [
    {
      "type": "openfinance-transaction",
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "attributes": {
        "description": "PIX Recebido - João Silva",
        "amount": 1500.00,
        "type": "CREDIT",
        "date": "2024-01-15T14:30:00Z",
        "category": "TRANSFERS",
        "currencyCode": "BRL",
        "createdAt": "2024-01-15T14:30:00Z"
      }
    },
    {
      "type": "openfinance-transaction",
      "id": "550e8400-e29b-41d4-a716-446655440021",
      "attributes": {
        "description": "Supermercado ABC",
        "amount": 245.90,
        "type": "DEBIT",
        "date": "2024-01-15T10:15:00Z",
        "category": "FOOD",
        "currencyCode": "BRL",
        "createdAt": "2024-01-15T10:15:00Z"
      }
    }
  ],
  "meta": {
    "totalItems": 150,
    "totalPages": 3,
    "currentPage": 1,
    "itemsPerPage": 50
  }
}

---

Erros Comuns

Código	Erro	Descrição
404	NOT_FOUND	Conta ou transação não encontrada
404	NOT_FOUND	Item não encontrado (ao listar contas)