Quickstart
Configure seu ambiente e faça sua primeira chamada à API em 5 minutos
Visão geral
Este guia vai te levar do zero à sua primeira chamada de API em poucos minutos. Ao final, você terá:
- Credenciais de acesso ao ambiente Sandbox
- Ambiente configurado para fazer requisições
- Uma chamada de teste funcionando
Todos os exemplos usam o ambiente Sandbox. Para acesso à Produção, veja Ambientes.
Passo 1: Obtenha suas credenciais
As credenciais da API Conta Simples são gerenciadas diretamente pelo Internet Banking da Conta Simples. Tanto as credenciais de Sandbox quanto de Produção ficam disponíveis no mesmo lugar.
Acesse o painel de credenciais
Acesse o Internet Banking e navegue até a seção de credenciais da API:
Copie suas credenciais
No painel, você encontrará duas credenciais para cada ambiente:
- API Key — identificador da sua aplicação
- API Secret — segredo para autenticação
Guarde com segurança
Armazene as credenciais em um cofre de segredos (Vault, AWS Secrets Manager, etc.). Nunca comite em repositórios ou exponha em logs.
Não consegue ver as credenciais? O acesso ao painel de credenciais depende do seu perfil de usuário e permissões no Internet Banking. Caso não consiga visualizar ou gerenciar as credenciais, solicite acesso ao responsável da sua empresa na Conta Simples.
Credenciais comprometidas devem ser revogadas imediatamente pelo painel do Internet Banking. Se necessário, entre em contato com o suporte.
Passo 2: Obtenha um token de acesso
Com suas credenciais em mãos, autentique-se para obter um token de acesso.
# BASIC_BASE64 = "SUA_API_KEY:SEU_API_SECRET" encodado em base64
curl --location 'https://api-sandbox.contasimples.com/oauth/v1/access-token' \
--header "Authorization: Basic ${BASIC_BASE64}" \
--header "Content-Type: application/x-www-form-urlencoded" \
--data "grant_type=client_credentials"
Onde substituir
| Placeholder | Descrição |
|---|---|
{SUA_API_KEY} | API Key obtida no Internet Banking |
{SEU_API_SECRET} | API Secret obtido no Internet Banking |
Resposta esperada
{
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
"token_type": "Bearer",
"expires_in": 3600
}
O access_token é o que você usará em todas as chamadas subsequentes. Ele expira em expires_in segundos (geralmente 1 hora).
Implemente renovação automática de token antes da expiração para evitar erros 401 em fluxos longos.
Passo 3: Consulte o extrato de transações
Agora que você tem um token válido, consulte o extrato de transações de cartão usando POST /statements/v1/credit-card:
curl -X POST https://api-sandbox.contasimples.com/statements/v1/credit-card \
-H "Authorization: Bearer {TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2025-01-01",
"endDate": "2025-01-31",
"limit": 10
}'
Substitua {TOKEN} pelo access_token obtido no Passo 2.
Parâmetros do body
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
startDate | string | Sim | Data inicial (YYYY-MM-DD). Ex: 2025-01-01 |
endDate | string | Sim | Data final (YYYY-MM-DD). Ex: 2025-01-31 |
limit | integer | Sim | Quantidade de resultados por página (5 a 100) |
nextPageStartKey | string | Não | Cursor para paginação (ver seção abaixo) |
O período máximo entre startDate e endDate é de 62 dias.
Resposta esperada
{
"transactions": [
{
"id": "txn_8f7e6d5c4b3a2190",
"operation": "CASH_OUT",
"transactionDate": "2025-01-15T14:30:00.000Z",
"status": "PROCESSED",
"type": "PURCHASE",
"merchant": "UBER *TRIP",
"amountBrl": 45.90,
"exchangeRateUsd": 0,
"isCanceled": false,
"isConciled": true,
"installment": 1,
"card": {
"id": "card_a1b2c3d4e5f6",
"maskedNumber": "**** **** **** 1234",
"responsibleName": "João Silva",
"responsibleEmail": "joao.silva@empresa.com",
"type": "VIRTUAL"
},
"category": {
"id": "cat_transport",
"name": "Transporte"
},
"costCenter": {
"id": "cc_comercial",
"name": "Comercial"
},
"attachments": []
}
],
"nextPageStartKey": "eyJsYXN0SWQiOiJ0eG5fOGY3ZTZkNWM0YjNhMjE5MCJ9"
}
Se você recebeu uma resposta 200 OK com transações, parabéns! Sua integração está funcionando.
Paginação
A API usa paginação baseada em cursor para lidar com grandes volumes de dados.
Como funciona
- Na primeira requisição, envie apenas
startDate,endDateelimit - Se houver mais resultados, a resposta incluirá
nextPageStartKey - Para obter a próxima página, envie o mesmo request incluindo
nextPageStartKey - Repita até
nextPageStartKeysernullou ausente
Exemplo: paginando resultados
Primeira requisição:
curl -X POST https://api-sandbox.contasimples.com/statements/v1/credit-card \
-H "Authorization: Bearer {TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2025-01-01",
"endDate": "2025-01-31",
"limit": 10
}'
Resposta:
{
"transactions": [],
"nextPageStartKey": "eyJsYXN0SWQiOiJ0eG5fYWJjMTIzIn0="
}
Segunda requisição (próxima página):
curl -X POST https://api-sandbox.contasimples.com/statements/v1/credit-card \
-H "Authorization: Bearer {TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2025-01-01",
"endDate": "2025-01-31",
"limit": 10,
"nextPageStartKey": "eyJsYXN0SWQiOiJ0eG5fYWJjMTIzIn0="
}'
Última página (sem mais resultados):
{
"transactions": [],
"nextPageStartKey": null
}
O nextPageStartKey é um token opaco. Não tente decodificar ou modificar — use exatamente como recebido.
Erros comuns do primeiro request
Se sua primeira chamada falhar, verifique:
Guia completo de erros
Diagnóstico detalhado de todos os códigos de erro.
Checklist de integração
Use este checklist para garantir que sua integração está pronta:
- Credenciais Sandbox obtidas no Internet Banking e armazenadas com segurança
- Autenticação funcionando (token obtido com sucesso)
- Primeira chamada ao extrato realizada
- Paginação implementada (uso de
nextPageStartKey) - Tratamento de erros implementado (401, 400, 500)
- Lógica de retry com backoff exponencial
- Logging de requests para troubleshooting
Próximos passos
Last updated 2 days ago
Built with Documentation.AI