Ambientes
Entenda os ambientes Sandbox e Produção, o limite de requisições e como acessar suas credenciais
Visão geral
A API Conta Simples disponibiliza dois ambientes isolados para diferentes estágios do seu projeto:
Sandbox
Ambiente de testes para desenvolvimento e validação de integração. Dados simulados, sem impacto real.
Produção
Ambiente real com dados e transações reais. Requer aprovação e validação prévia.
Sandbox
Características
| Aspecto | Descrição |
|---|---|
| Propósito | Desenvolvimento, testes e validação |
| Dados | Simulados, sem valor real |
| Disponibilidade | 99.5% SLA (pode ter janelas de manutenção) |
| Rate limit | 100 chamadas por minuto por IP |
| Credenciais | Específicas para Sandbox |
URL base
https://api-sandbox.contasimples.com
Comportamento e limitações
No Sandbox, os filtros e parâmetros de consulta não se aplicam: a API devolve respostas estáticas, independentemente de valores como datas, limites ou chaves de paginação.
Nenhuma ação é executada de fato — por exemplo, bloqueio ou desbloqueio de cartão, ou qualquer outra operação que altere estado, não produz efeito real; o objetivo é apenas validar contrato, fluxo HTTP e tratamento de respostas.
Produção
Características
| Aspecto | Descrição |
|---|---|
| Propósito | Operações reais com clientes |
| Dados | Reais, com valor financeiro |
| Disponibilidade | 99.9% SLA |
| Rate limit | 100 chamadas por minuto por IP |
| Credenciais | Específicas para Produção |
URL base
https://api.contasimples.com
Requisitos para acesso
Integração validada em Sandbox
Demonstre que sua integração funciona corretamente no ambiente de testes.
Checklist de segurança e boas práticas aprovado
Termos de uso e privacidade aceitos
Termos de uso e política de privacidade revisados e aceitos.
Credenciais de produção
Acesse as credenciais de produção no painel do Internet Banking.
Comparativo
| Característica | Sandbox | Produção |
|---|---|---|
| Propósito | Testes | Operações reais |
| Dados | Simulados | Reais |
| Impacto financeiro | Nenhum | Real |
| Filtros e parâmetros de consulta | Não alteram o resultado (resposta estática) | Aplicados aos dados reais |
| Ações que mudam estado (ex.: bloqueio de cartão) | Simuladas; sem efeito real | Executadas de fato |
| Credenciais | Específicas Sandbox | Específicas Produção |
| SLA disponibilidade | 99.5% | 99.9% |
| Suporte | Horário comercial | 24/7 (conforme contrato) |
| Rate limit | 100 chamadas/minuto por IP | 100 chamadas/minuto por IP |
Limite de taxa (rate limit)
A API aplica 100 chamadas por minuto por endereço IP. Esse limite vale para Sandbox e Produção: a regra é a mesma em api-sandbox.contasimples.com e api.contasimples.com.
O contador é por IP de origem. Tráfego que sair do mesmo IP — por exemplo, vários processos no mesmo servidor ou clientes atrás do mesmo NAT — compartilha o mesmo orçamento por minuto.
Ao atingir o limite, as requisições podem ser recusadas com HTTP 429 (Too Many Requests). Implemente retry com backoff e evite rajadas; veja Boas práticas para paginação e tratamento de erros.
Nunca use credenciais de Produção em ambientes de desenvolvimento ou testes. Mantenha segregação total.
Como acessar suas credenciais
As credenciais de ambos os ambientes (Sandbox e Produção) são gerenciadas diretamente pelo Internet Banking da Conta Simples:
ib.contasimples.com/integracoes/api/credenciais
Acesse o Internet Banking
Faça login no Internet Banking da Conta Simples e navegue até Integrações → API → Credenciais.
Selecione o ambiente
No painel de credenciais, você verá as credenciais disponíveis para Sandbox e Produção.
Copie API Key e API Secret
Cada ambiente possui:
- API Key — identificador da sua aplicação
- API Secret — segredo para autenticação
Permissões de acesso
O acesso ao painel de credenciais é controlado pelo perfil de usuário e permissões configurados no Internet Banking. Apenas usuários com as permissões adequadas podem visualizar ou gerenciar credenciais.
Não consegue ver as credenciais? Solicite acesso ao responsável da sua empresa na Conta Simples. A gestão de permissões é feita internamente pela própria empresa no Internet Banking.
Promoção para Produção
Quando sua integração estiver validada no Sandbox, suas credenciais de Produção já estarão disponíveis no mesmo painel. Antes de operar em produção, complete o checklist:
- Integração Sandbox validada
- Tratamento de erros implementado
- Lógica de retry com backoff
- Credenciais armazenadas com segurança
- Monitoramento e alertas configurados
- Logging de request_id implementado
Boas práticas
Segregação de ambientes
Use variáveis de ambiente para alternar entre ambientes:
# Desenvolvimento/Testes
export OPENAPI_ENV=sandbox
export OPENAPI_BASE_URL=https://api-sandbox.contasimples.com
export OPENAPI_API_KEY={API_KEY_SANDBOX}
# Produção
export OPENAPI_ENV=production
export OPENAPI_BASE_URL=https://api.contasimples.com
export OPENAPI_API_KEY={API_KEY_PRODUCAO}
Valide o ambiente antes de operações críticas:
// Exemplo conceitual
function getApiConfig() {
const env = process.env.OPENAPI_ENV ?? 'sandbox';
if (env === 'production') {
return new ProductionConfig();
}
return new SandboxConfig();
}
Proteções recomendadas
- Feature flags: Use flags para habilitar/desabilitar integrações por ambiente
- Logs diferenciados: Marque logs com o ambiente para facilitar troubleshooting
- Alertas: Configure alertas diferentes para Sandbox e Produção
- Revisão de código: Exija revisão antes de deploy em produção
FAQ
Não. Cada ambiente tem credenciais específicas e independentes. Isso garante isolamento total entre os ambientes.
Não. Os ambientes são completamente isolados. Dados criados em Sandbox não existem em Produção e vice-versa.
O acesso ao painel de credenciais depende do perfil de usuário e das permissões configuradas no Internet Banking. Solicite acesso ao responsável da sua empresa na Conta Simples.
O acesso ao Sandbox geralmente é gratuito para parceiros em fase de integração. Confirme com o time comercial.
Próximos passos
Last updated today
Built with Documentation.AI