Quickstart

Overview

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

1. Credentials for the Sandbox environment
2. A working setup to send requests
3. A successful test call

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.

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

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

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

Sample response

{
  "transactions": [
    {
      "id": "01JB4M8WQ2YX5KN7RT9HF3DE6C",
      "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.

User-Agent (required)

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.

Pagination

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

How it works

1. First request: send startDate, endDate, and limit only
2. If there are more rows, the response will include nextPageStartKey
3. To fetch the next page, send the same parameters plus nextPageStartKey
4. 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
}

First-request errors

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

Integration checklist

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

• Sandbox credential created in Internet Banking, with the scopes the integration uses
• Public key registered, if any granted scope requires signing
• API key, API secret, and private key stored in a secret manager
• Authentication working (token issued)
• First statement call succeeds
• Request signing implemented, when the credential has a public key
• Pagination with nextPageStartKey implemented
• Error handling (401, 400, 500) in place
• Exponential backoff for retries, signing each attempt again
• Server clock kept in sync via NTP
• Request logging for troubleshooting

Next steps