Recommended integration flow

Step-by-step guide to integrate with the Conta Simples API

Overview

This guide describes the recommended path to integrate with the Conta Simples API, from initial setup to production. Follow the steps in order for a safe, efficient rollout.

Typical timeline: A full integration can be built in a few days, depending on your use case.

Integration steps

Get credentials

ib.contasimples.com/integracoes/api/credenciais

You will need:

API key — application identifier
API secret — used to authenticate your application

Cannot see credentials? Access depends on your user profile and permissions. Ask the Conta Simples account owner at your company.

Environments and credentials

How to open and manage credentials.

Get an access token

With your credentials, authenticate with OAuth 2.0 Client Credentials to obtain 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"

Tokens are valid for 30 minutes. Implement automatic refresh.

Authentication guide

Full flow, refresh, and security tips.

Test in Sandbox

Use Sandbox to validate your integration at no real financial risk. Data is simulated.

Validate:

Authentication works
Requests return the expected data
Error handling is in place

Environments

Sandbox vs Production.

Query card transactions

Call GET /statements/v1/credit-card for your first statement. The response includes metadata for card, category, cost center, and attachments.

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}"

GET /statements/v1/credit-card

Full technical reference, parameters, and schemas.

Data dictionary

Meaning of each field in the response.

Handle pagination

For large volumes, the API returns cursor-based pages via nextPageStartKey.

Flow:

Make the first request without nextPageStartKey
If the response has nextPageStartKey, send it in the next request
Repeat until nextPageStartKey is null or missing

Best practices — Pagination

Full code example.

Use attachments

Transactions can include attachments (invoices, receipts). Download with GET /attachments/v1/content/{attachmentId}.

Flow:

From transactions, read the attachments array
For each attachment, take the id
GET /attachments/v1/content/{id} to download the binary
Use the response's Content-Type header to detect the format (PNG, JPEG, PDF)

Best practices — Attachments

Download and file handling.

GET /attachments/v1/content/{id}

Technical reference.

Move to production

When Sandbox is validated, roll out to Production.

Go-live checklist:

All flows work in Sandbox
Token refresh in place
Pagination works end-to-end
Error handling (401, 400, 500) in place
Exponential backoff for retries
Idempotency for critical steps
Secrets in a vault
Monitoring and alerts
Structured request_id logging

Moving to production

Requirements and go-live notes.

Flow at a glance

Endpoint quick reference

Step	Endpoint	More detail
Auth	`POST /oauth/v1/access-token`	Authentication
Transactions	`GET /statements/v1/credit-card`	API Reference
Attachments	`GET /attachments/v1/content/{attachmentId}`	API Reference

Next steps

Quickstart (5 min)

Your first API call.

Best practices

Pagination, retry, and errors.

API Reference

Full endpoint reference.

Data dictionary

Entities, fields, and enums.

Was this page helpful?

Last updated today

Built with Documentation.AI