# RPG Connecta — data input, output and agent workflow

Public playground: https://www.rpgcapital.com.br/developers/data
Synthetic JSON: https://www.rpgcapital.com.br/developers/data/sample?scenario=complete
OpenAPI: https://www.rpgcapital.com.br/developers/connecta-openapi.json

## What is available
The published financial resources are accounts/balances and account transactions. Coverage depends on the institution, the consent and the latest completed collection. A requested or documented history window does not prove all that history was received. Up to 12 months may be available from the banking source; Connecta currently returns the stored snapshot, not a guaranteed 12-month backfill. Sync reads available source data; it does not guarantee a fresh bank collection.

## Input → Connecta output
The example input is a simplified synthetic banking-connector response, not a complete source contract. The server maps source fields into a compact Connecta response.

| Source field | Connecta field | Rule |
| --- | --- | --- |
| account.id | account.id | Stable source record identifier; not a workspace connection ID |
| account.name / marketingName | name | Account label; fallback only when missing |
| account.type / subtype | type / subtype | Preserve bank vs credit distinction; a card balance is not available cash |
| account.balance | balance_minor | Scale decimal major units by the currency exponent (BRL × 100); safe integer or null; excess precision rounds half away from zero |
| account.balanceAvailable | balance_available | false makes balance_minor null; unavailable never means zero |
| account.balanceUpdatedAt | balance_updated_at | Source observation time, distinct from snapshot fetch time |
| currencyCode | currency | ISO currency code; unknown is null, never assume BRL |
| transaction.id | id | Use with workspace/connection scope for deduplication |
| selected account.id | account_id | Preserve the transaction/account relationship |
| amount and type | amount_minor / direction | DEBIT is negative; CREDIT is positive, even when source magnitude is positive |
| transaction.status | status | Preserve PENDING vs POSTED; pending is not settled cash |
| date / description | date / description | Preserve reported date/time; null date stays unknown |
| category | category | May be string, object or null; absence is not zero activity |

Example: source {"amount":173.90,"type":"DEBIT","currencyCode":"BRL"} becomes {"amount_minor":-17390,"direction":"debit","currency":"BRL"}.

## Response envelope
GET /api/connecta/v1/connections/{id}/accounts and /transactions return data, pagination and meta. Follow pagination.next_offset until null. An empty page can mean pending authorization or no collected records: inspect connection state. meta.partial=true means the snapshot is incomplete, even when pagination has ended. Pagination completeness and collection completeness are different.

Use meta.synthetic, meta.environment, meta.status and meta.last_synced_at before showing data. last_synced_at records when Connecta fetched the snapshot; balance_updated_at reports when the source observed a balance. Do not label either as real-time. Null monetary values must display as unavailable, not zero.

The older public demo-1 endpoint at /developers/sandbox/data uses nonnegative amount_minor plus direction. That legacy illustrative fixture has a different envelope; do not mix its sign convention with the signed v1 transaction contract.

## Derived summaries
The public playground computes an illustrative per-currency summary from its synthetic normalized transactions. This is not a separate production summary endpoint. It excludes pending and unavailable amounts. Load every page before summarizing a real snapshot. Keep currencies separate. Inflow is not automatically sales or revenue; outflow is not automatically operating expense. Transfers between owned accounts can appear on both sides. Net observed flow is not accounting profit. Do not include credit-card balances in available-cash totals.

## Agent workflow
1. Read this guide, OpenAPI and the synthetic sample without signing in.
2. For a persistent workspace, let the human sign in with Google and create a sandbox credential. Keep secrets server-side.
3. Create a simulator connection or use the existing one, inspect its state, read accounts and paginate transactions. Exercise pending, expired, unavailable and partial states.
4. Operational MCP uses a separate scoped rpg_mcp_ token. Public discovery MCP has no bank-data access.
5. In a supported browser, the console exposes connecta_console_navigate, connecta_console_state and connecta_console_read. Private reads use the current session. Tools do not create credentials, activate production or bypass bank consent. Browser support is optional; normal buttons and REST/MCP remain available.
6. Production requires explicit activation and human Open Finance consent. Never automatically open or preview one-use authorization URLs.

## Commercial terms
Synthetic sandbox R$ 0. Production R$ 9.99 per connection. Setup R$ 0. Monthly minimum R$ 0. Pay as you go.