Quick start

This guide gets you from zero to your first successful API call in a couple of minutes. You’ll learn how to authenticate, call the API, handle pagination, and understand dates/timezones. For deeper details, see Authentication & Limits, Common Params, and the individual endpoint pages.

1) Prerequisites

An API key (you receive it during onboarding).

curl (preinstalled on macOS/Linux; available on Windows via WSL or Git Bash).

Base URL (v1): https://api.fintatica.com.br/v1

2) Authenticate and call your first endpoint

We’ll query the Funds collection with a minimal request. Authentication uses a Bearer token in the Authorization header.

Set your API key (recommended practice)

Make your first request

Expected response (placeholder — replace with a real example later):

{
  "success": true,
  "data": [ /* ... fund objects ... */ ]
}

If you prefer different page sizes, adjust per_page. For large sync jobs, paginate rather than asking for huge pages.

3) Pagination (offset model)

Fintatica uses page/per_page pagination.

Request page N with: ?page=N&per_page=K

Start with small per_page (e.g., 50–200) and increase only if needed.

Keep fetching page = page + 1 until you’ve read all records (see total, or stop when a page returns fewer items than per_page).

For endpoint-specific pagination details or response fields, see that endpoint’s doc page.

4) Dates & timezones

Date parameters (when applicable) use YYYYMMDD.
Example: ?from=20250101&to=20250331

Timestamps in responses are UTC unless the endpoint explicitly states Brazil Time; each endpoint page clarifies this.

Tip: Align your comparisons by frequency (daily vs weekly vs monthly) and timezone; many “data mismatches” are actually cadence/zone mismatches.

5) Handling errors (shape & example)

Errors return a consistent JSON shape:

{
  "success": false,
  "message": "Unauthorized",
  "code": "unauthorized",
  "error_data": {}
}

401 Unauthorized: Check your Bearer token and header spelling.

4xx: Fix the request (params, types, required fields).

5xx: Temporary problem on our side—retry with backoff.
(See Error Codes for specifics and common recovery tips.)

Rate-limit headers exist and are documented in Authentication & Limits.

6) Production tips most people miss

Store API keys in env vars, never hard-code or ship them to a public frontend.

Paginate & cache: For bulk reads, pull in pages and cache results. Some sources publish revisions/backfills; plan to refresh historical slices periodically.

Version pinning: You’re on /v1. When a new major version arrives, we’ll announce it in the Changelog with a deprecation window.

Monitor status: Bookmark the status page for live availability and incident history — https://status.fintatica.com.br

7) What to read next

Authentication & Limits — token usage, limits, and headers

Common Params — filtering, sorting, and more pagination examples

Endpoint pages — schemas, cadence, caveats, and examples for each dataset

Once you’re comfortable with the above, head to a dataset page (e.g., Funds) and start integrating it into your pipeline.

1) Prerequisites#

2) Authenticate and call your first endpoint#

Set your API key (recommended practice)#

Make your first request#

3) Pagination (offset model)#

4) Dates & timezones#

5) Handling errors (shape & example)#

6) Production tips most people miss#

7) What to read next#