Ambientes
A API Topo Contábil oferece dois ambientes independentes: Sandbox para desenvolvimento e testes, e Produção para dados reais. Cada ambiente possui sua própria URL base, chaves de API e dados isolados.
Visão geral
| Característica | Sandbox | Produção |
|---|---|---|
| URL Base | api-sandbox.topocontabil.com.br | api.topocontabil.com.br |
| Prefixo da chave | topo_sk_sandbox_... | topo_sk_live_... |
| Dados | Dados ficticioss, resetáveis | Dados reais |
| Webhooks | Entrega com delay simulado | Entrega em tempo real |
| Rate limit | 100 req/min | 1.000 req/min |
| SLA de uptime | Não garantido | 99.9% |
| Tamanho max. import | 10MB | 50MB |
Sandbox
O ambiente Sandbox e ideal para desenvolvimento e testes de integração. Ele vem pre-populado com dados ficticioss que simulam cenários reais, incluindo empresas, planos de contas, balancetes e conciliações.
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
- Conciliações em diversos status (rascunho, em revisão, aprovada)
- Usuários com diferentes níveis de permissão
i
Reset de dados
Os dados do Sandbox podem ser resetados para o estado inicial a qualquer momento através do painel administrativo em Configurações > Sandbox > Resetar dados.
Exemplo de uso
Requisição 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..."Produção
O ambiente de Produção manipula dados reais e possui garantias de SLA. Antes de migrar para produção:
- Valide toda a integração no Sandbox
- Gere chaves de produção separadas (nunca reutilize chaves do Sandbox)
- Configure webhooks de produção com URLs definitivas
- Implemente tratamento de erros e idempotencia em todas as operações de escrita
!
Chaves de produção
Nunca exponha chaves de produção em código front-end, repositorios públicos ou logs. Use variáveis de ambiente em seu servidor.
Checklist de migração
Use esta lista para garantir que sua integração esta pronta para produção:
Todos os testes passam no Sandbox
Chave de produção gerada e armazenada com segurança
URLs base atualizadas para api.topocontabil.com.br
Webhooks configurados com URLs de produção
Tratamento de erros implementado para todos os cenários
Idempotencia implementada em operações POST
Rate limiting respeitado (verifique headers X-RateLimit-*)
Logs de auditoria configurados para rastrear chamadas
Variáveis 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_...
# Produção (use em .env.production)
TOPO_API_BASE_URL=https://api.topocontabil.com.br
TOPO_API_KEY=topo_sk_live_...
TOPO_WEBHOOK_SECRET=whsec_live_...