Quickstart

Set up your environment and make your first API call in 5 minutes

Overview

This guide takes you from zero to a working API call in a few minutes. When you are done, you will have:

Credentials for the Sandbox environment
A working setup to send requests
A successful test call

All examples use the Sandbox environment. For Production access, see Environments.

Step 1: Get your credentials

Conta Simples API credentials are managed in Conta Simples Internet Banking. Sandbox and Production credentials are available in the same place.

Open the credentials page

ib.contasimples.com/integracoes/api/credenciais

Copy your credentials

The panel shows two values per environment:

API key — application identifier
API secret — authentication secret

Store them safely

Use a secret manager (Vault, AWS Secrets Manager, etc.). Never commit to Git or log them.

Cannot see credentials? The page depends on your user profile and Internet Banking permissions. If you cannot view or manage them, ask the Conta Simples owner at your company.

If credentials are exposed, revoke them immediately in Internet Banking. If you need help, contact support.

Step 2: Get an access token

With your credentials, authenticate to receive an access token.

# BASIC_BASE64 = base64("YOUR_API_KEY:YOUR_API_SECRET")
curl --location 'https://api-sandbox.contasimples.com/oauth/v1/access-token' \
  --header "Authorization: Basic ${BASIC_BASE64}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "User-Agent: {your-app-name}/{version}" \
  --data "grant_type=client_credentials"

Placeholders

Placeholder	Description
`{YOUR_API_KEY}`	API key from Internet Banking
`{YOUR_API_SECRET}`	API secret from Internet Banking

Expected response

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 1800
}

Use the access_token on all following calls. It expires after expires_in seconds (usually 30 minutes).

Refresh the token automatically before it expires to avoid 401 errors in long runs.

Step 3: Query the card statement

With a valid token, call the card transaction statement with GET /statements/v1/credit-card:

curl -X GET "https://api-sandbox.contasimples.com/statements/v1/credit-card?startDate=2025-01-01&endDate=2025-01-31&limit=10" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -H "User-Agent: {your-app-name}/{version}"

Replace {TOKEN} with the access_token from Step 2.

Query parameters

Field	Type	Required	Description
`startDate`	string	Yes	Start date (`YYYY-MM-DD`), e.g. `2025-01-01`
`endDate`	string	Yes	End date (`YYYY-MM-DD`), e.g. `2025-01-31`
`limit`	integer	Yes	Page size (5 to 100)
`nextPageStartKey`	string	No	Pagination cursor (see below)

The maximum range between startDate and endDate is 62 days.

Sample response

{
  "transactions": [
    {
      "id": "txn_8f7e6d5c4b3a2190",
      "operation": "CASH_OUT",
      "transactionDate": "2025-01-15T14:30:00.000Z",
      "status": "PROCESSED",
      "type": "PURCHASE",
      "merchant": "UBER *TRIP",
      "amountBrl": 45.9,
      "exchangeRateUsd": 0,
      "isCanceled": false,
      "isConciled": true,
      "installment": 1,
      "card": {
        "id": "card_a1b2c3d4e5f6",
        "maskedNumber": "**** **** **** 1234",
        "responsibleName": "John Smith",
        "responsibleEmail": "john.smith@company.com",
        "type": "VIRTUAL"
      },
      "category": {
        "id": "cat_transport",
        "name": "Transport"
      },
      "costCenter": {
        "id": "cc_sales",
        "name": "Sales"
      },
      "attachments": []
    }
  ],
  "nextPageStartKey": "eyJsYXN0SWQiOiJ0eG5fOGY3ZTZkNWM0YjNhMjE5MCJ9"
}

If you get 200 OK with transactions, your integration is working.

Full endpoint details

Complete API documentation.

Data dictionary

Field-by-field reference.

The User-Agent header is required on every API call, including POST /oauth/v1/access-token and authenticated Bearer requests. It must clearly identify your app and version for support, diagnostics, and operations.

Format

Use {your-app-name}/{version}, e.g. acme-integra/1.4.0 or acme-backoffice/2.0.1. Keep a stable app name; bump version when you ship meaningful integration changes.

How to send

In HTTP, set the standard User-Agent header (not the query string or body).
In the curl examples on this page, use: -H "User-Agent: {your-app-name}/{version}" with your real values.
In SDKs (fetch, requests, HttpClient, etc.), set User-Agent on the client or per request.

Do not rely only on the default user agent from the runtime. Without a clear, app-specific User-Agent, it is much harder to correlate traffic during incidents.

Pagination

The API uses cursor-based pagination for large result sets.

How it works

First request: send startDate, endDate, and limit only
If there are more rows, the response will include nextPageStartKey
To fetch the next page, send the same parameters plus nextPageStartKey
Stop when nextPageStartKey is null or missing

Example

First request:

curl -X GET "https://api-sandbox.contasimples.com/statements/v1/credit-card?startDate=2025-01-01&endDate=2025-01-31&limit=10" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -H "User-Agent: {your-app-name}/{version}"

Response with next page:

{
  "transactions": [],
  "nextPageStartKey": "eyJsYXN0SWQiOiJ0eG5fYWJjMTIzIn0="
}

Second request:

curl -X GET "https://api-sandbox.contasimples.com/statements/v1/credit-card?startDate=2025-01-01&endDate=2025-01-31&limit=10&nextPageStartKey=eyJsYXN0SWQiOiJ0eG5fYWJjMTIzIn0=" \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Content-Type: application/json" \
  -H "User-Agent: {your-app-name}/{version}"

Last page:

{
  "transactions": [],
  "nextPageStartKey": null
}

nextPageStartKey is opaque. Do not decode or modify it — use it exactly as received.

First-request errors

If your first call fails, here's what to check:

Cause: Token missing, invalid, or expired.

Check:

Authorization: Bearer {TOKEN} (with a space after Bearer)
Token is still within expires_in seconds
You are sending the access token, not the API secret

Fix: Get a new token at /oauth/v1/access-token.

Cause: Invalid query parameters.

Check:

startDate and endDate are in YYYY-MM-DD format
The range does not exceed 62 days
limit is between 5 and 100
The JSON is well formed

Fix: Correct the parameters according to the documentation.

Cause: Not allowed to use this resource with these credentials.

Check:

You use the right environment (Sandbox vs Production)
Scopes on your credentials are enough

Fix: Contact support to review permissions.

Cause: Error on the server.

Fix: Wait a few seconds and retry. If it persists, contact support with the request_id if you have it.

Full error guide

Detailed help for all error codes.

Integration checklist

Use this list before you call your integration “done”:

Sandbox credentials from Internet Banking, stored safely
Authentication working (token issued)
First statement call succeeds
Pagination with nextPageStartKey implemented
Error handling (401, 400, 500) in place
Exponential backoff for retries
Request logging for troubleshooting

Next steps

Integration flow

From Sandbox to Production, step by step.

Best practices

Pagination, retry, and errors.

Data dictionary

All response fields explained.

API Reference

Full technical reference.

Was this page helpful?

Last updated today

Built with Documentation.AI