Ambientes
A API Topo Contabil oferece dois ambientes independentes: Sandbox para desenvolvimento e testes, e Producao para dados reais. Cada ambiente possui sua propria URL base, chaves de API e dados isolados.
Visao geral
| Caracteristica | Sandbox | Producao |
|---|---|---|
| URL Base | api-sandbox.topocontabil.com.br | api.topocontabil.com.br |
| Prefixo da chave | topo_sk_sandbox_... | topo_sk_live_... |
| Dados | Dados ficticioss, resetaveis | Dados reais |
| Webhooks | Entrega com delay simulado | Entrega em tempo real |
| Rate limit | 100 req/min | 1.000 req/min |
| SLA de uptime | Nao garantido | 99.9% |
| Tamanho max. import | 10MB | 50MB |
Sandbox
O ambiente Sandbox e ideal para desenvolvimento e testes de integracao. Ele vem pre-populado com dados ficticioss que simulam cenarios reais, incluindo empresas, planos de contas, balancetes e conciliacoes.
Dados de teste
O Sandbox inclui os seguintes dados pre-configurados:
- 3 empresas com planos de contas completos
- Balancetes de Janeiro a Dezembro de 2025
- Conciliacoes em diversos status (rascunho, em revisao, aprovada)
- Usuarios com diferentes niveis de permissao
i
Reset de dados
Os dados do Sandbox podem ser resetados para o estado inicial a qualquer momento atraves do painel administrativo em Configuracoes > Sandbox > Resetar dados.
Exemplo de uso
Requisicao no Sandboxbash
# Note a URL diferente: api-sandbox
curl -X GET https://api-sandbox.topocontabil.com.br/v1/tenants \
-H "Authorization: Bearer topo_sk_sandbox_a1b2c3d4..."Producao
O ambiente de Producao manipula dados reais e possui garantias de SLA. Antes de migrar para producao:
- Valide toda a integracao no Sandbox
- Gere chaves de producao separadas (nunca reutilize chaves do Sandbox)
- Configure webhooks de producao com URLs definitivas
- Implemente tratamento de erros e idempotencia em todas as operacoes de escrita
!
Chaves de producao
Nunca exponha chaves de producao em codigo front-end, repositorios publicos ou logs. Use variaveis de ambiente em seu servidor.
Checklist de migracao
Use esta lista para garantir que sua integracao esta pronta para producao:
Todos os testes passam no Sandbox
Chave de producao gerada e armazenada com seguranca
URLs base atualizadas para api.topocontabil.com.br
Webhooks configurados com URLs de producao
Tratamento de erros implementado para todos os cenarios
Idempotencia implementada em operacoes POST
Rate limiting respeitado (verifique headers X-RateLimit-*)
Logs de auditoria configurados para rastrear chamadas
Variaveis de ambiente recomendadas
.envbash
# Sandbox
TOPO_API_BASE_URL=https://api-sandbox.topocontabil.com.br
TOPO_API_KEY=topo_sk_sandbox_...
TOPO_WEBHOOK_SECRET=whsec_sandbox_...
# Producao (use em .env.production)
TOPO_API_BASE_URL=https://api.topocontabil.com.br
TOPO_API_KEY=topo_sk_live_...
TOPO_WEBHOOK_SECRET=whsec_live_...