Quickstart

Visão geral

Este guia vai te levar do zero à sua primeira chamada de API em poucos minutos. Ao final, você terá:

1. Credenciais de acesso ao ambiente Sandbox
2. Ambiente configurado para fazer requisições
3. Uma chamada de teste funcionando

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.

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" \
  --header "User-Agent: {nome-do-seu-app}/{versao}" \
  --data "grant_type=client_credentials"

Onde substituir

Resposta esperada

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

O access_token é o que você usará em todas as chamadas subsequentes. Ele expira em expires_in segundos (geralmente 30 minutos).

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 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: {nome-do-seu-app}/{versao}"

Substitua {TOKEN} pelo access_token obtido no Passo 2.

Parâmetros da requisição

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.9,
      "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.

User-Agent (obrigatório)

O header User-Agent é obrigatório em toda requisição à API, incluindo POST /oauth/v1/access-token e as chamadas autenticadas com Bearer. Ele identifica de forma clara qual aplicação está integrada e em qual versão, o que é essencial para suporte, diagnóstico e operação.

Formato

Envie o identificador no padrão {nome-do-seu-app}/{versao}, por exemplo: contabil-integra/1.4.0 ou minha-empresa-backoffice/2.0.1. Use um nome estável para a aplicação (não precisa mudar a cada deploy) e atualize a versão quando publicar releases relevantes da integração.

Como enviar

• Em HTTP, o valor vai no header padrão User-Agent (não em query string nem no body).
• Nos exemplos desta página com curl, use: -H "User-Agent: {nome-do-seu-app}/{versao}" (substitua os placeholders pelos valores reais).
• Em SDKs e bibliotecas (fetch, requests, HttpClient, etc.), configure o header User-Agent no cliente HTTP ou em cada requisição, de acordo com a biblioteca.

Paginação

A API usa paginação baseada em cursor para lidar com grandes volumes de dados.

Como funciona

1. Na primeira requisição, envie apenas startDate, endDate e limit
2. Se houver mais resultados, a resposta incluirá nextPageStartKey
3. Para obter a próxima página, envie o mesmo request incluindo nextPageStartKey
4. Repita até nextPageStartKey ser null ou ausente

Exemplo: paginando resultados

Primeira requisição:

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: {nome-do-seu-app}/{versao}"

Resposta:

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

Segunda requisição (próxima página):

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: {nome-do-seu-app}/{versao}"

Última página (sem mais resultados):

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

Erros comuns do primeiro request

Se sua primeira chamada falhar, verifique:

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