Integração

Fluxo de Integração Recomendado

Passo a passo completo para integrar com a API Conta Simples

Visão geral

Este guia apresenta o caminho recomendado para integrar com a API Conta Simples, do primeiro contato até a operação em produção. Siga cada etapa na ordem para garantir uma integração segura e eficiente.

Tempo estimado: A integração completa pode ser feita em poucos dias, dependendo da complexidade do seu caso de uso.

Etapas da integração

Obter credenciais

Acesse o Internet Banking da Conta Simples para obter suas credenciais de Sandbox:

ib.contasimples.com/integracoes/api/credenciais

O que você vai encontrar:

API Key — identificador da sua aplicação
API Secret — segredo para autenticação

Não consegue ver as credenciais? O acesso depende do seu perfil de usuário e permissões. Solicite acesso ao responsável da sua empresa.

Ambientes e credenciais

Veja detalhes sobre como acessar e gerenciar credenciais.

Obter token de acesso

Com as credenciais em mãos, autentique-se via OAuth 2.0 Client Credentials para obter um access_token.

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

O token retornado tem validade de 1 hora. Implemente renovação automática.

Guia de Autenticação

Fluxo completo de autenticação, renovação e boas práticas.

Testar no Sandbox

Use o ambiente Sandbox para validar sua integração sem risco. Os dados são simulados e não têm impacto financeiro real.

Valide:

Autenticação está funcionando
Requisições retornam dados esperados
Tratamento de erros está implementado

Ambientes

Diferenças entre Sandbox e Produção.

Consultar transações de cartão

Faça sua primeira consulta ao extrato de transações usando o endpoint POST /statements/v1/credit-card. A resposta contém transações do período, incluindo dados do cartão, categoria, centro de custo e anexos.

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

Endpoint: POST /statements/v1/credit-card

Referência técnica completa com parâmetros e schemas.

Dicionário de Dados

Significado de cada campo retornado.

Tratar paginação

Para grandes volumes de dados, a API retorna resultados paginados via cursor (nextPageStartKey).

Fluxo:

Envie a primeira requisição sem nextPageStartKey
Se a resposta incluir nextPageStartKey, envie-o na próxima requisição
Repita até nextPageStartKey ser null ou ausente

Boas Práticas — Paginação

Exemplo completo de paginação com código.

Consumir anexos

Transações podem incluir comprovantes (notas fiscais, recibos). Baixe-os via GET /attachments/v1/content/{attachmentId}.

Fluxo:

Consulte transações e verifique o array attachments
Para cada anexo, extraia o id
Faça GET /attachments/v1/content/{id} para baixar o arquivo binário
Use o header Content-Type da resposta para determinar o formato (PNG, JPEG, PDF)

Boas Práticas — Anexos

Exemplo de download e processamento.

Endpoint: GET /attachments/v1/content/{id}

Referência técnica do endpoint.

Ir para produção

Quando sua integração estiver validada no Sandbox, solicite a promoção para o ambiente de Produção.

Checklist de go-live:

Integração Sandbox validada com todos os fluxos
Autenticação com renovação automática de token
Paginação implementada corretamente
Tratamento de erros (401, 400, 500) implementado
Lógica de retry com backoff exponencial
Idempotência em operações críticas
Credenciais armazenadas em cofre de segredos
Monitoramento e alertas configurados
Logging estruturado com request_id

Ir para Produção

Veja os requisitos e o checklist de go-live.

Resumo visual do fluxo

Referência rápida de endpoints

Etapa	Endpoint	Referência
Autenticação	`POST /oauth/v1/access-token`	Autenticação
Transações	`POST /statements/v1/credit-card`	API Reference
Anexos	`GET /attachments/v1/content/{attachmentId}`	API Reference

Próximos passos

Quickstart (5 min)

Faça sua primeira chamada de API agora.

Boas Práticas

Paginação, retry e tratamento de erros.

API Reference

Referência técnica completa dos endpoints.

Dicionário de Dados

Entidades, campos e enumerações.

Was this page helpful?

Last updated today

Built with Documentation.AI