Case: como construímos um sistema de comércio exterior com integração SISCOMEX

O problema

Uma trading company de médio porte operava 200 processos de importação e 80 de exportação por mês. O controle era feito em planilhas Excel, e-mails e acesso manual ao SISCOMEX. Três despachantes dedicavam cerca de 60% do tempo a retrabalho: copiar dados entre sistemas, conferir numerário, corrigir classificações NCM digitadas erradas.

O custo operacional estava alto. Mas o problema real era outro: a empresa perdia prazos de liberação porque não tinha visibilidade sobre o status de cada processo. Uma DI registrada ficava parada dias sem que ninguém percebesse que faltava um documento de anuência. Multas por atraso na entrega de CE somavam R$ 40 mil por trimestre.

A diretoria procurou a Bradata para construir um sistema que centralizasse registro de DI e CE, integração direta com o SISCOMEX, gestão cambial e rastreamento de cargas.

Decisões de arquitetura

Por que .NET e não Node.js

A operação comex tem regras de negócio densas. Cálculo de impostos (II, IPI, PIS, COFINS, ICMS) com alíquotas que variam por NCM, regime tributário, acordo bilateral e tipo de operação. Isso é código que precisa de tipagem forte e testabilidade rigorosa.

Escolhemos .NET 8 com C#. O sistema de tipos do C# nos permitiu modelar a árvore tributária como value objects imutáveis. Cada cálculo gera um snapshot auditável. Tentamos prototipar a mesma lógica em TypeScript, mas a ausência de tipos numéricos decimais nativos gerava erros de arredondamento em centavos. Em comex, centavos viram milhares quando multiplicados por volume.

Frontend em React com Vite

O painel de operações precisava ser rápido e responsivo. Despachantes trabalham com 15 a 20 abas abertas simultaneamente. Escolhemos React 18 com Vite para builds rápidos e HMR instantâneo em desenvolvimento.

O componente mais complexo foi a timeline de processo. Cada importação passa por 12 a 18 etapas (numerário, registro DI, parametrização, desembaraço, transporte). Construímos um componente visual com status em tempo real via WebSocket.

SQL Server como banco principal

A empresa já tinha licenciamento SQL Server e um DBA experiente. Não fazia sentido introduzir PostgreSQL por preferência técnica quando o time interno já dominava planos de execução, índices columnstore e manutenção do SQL Server.

Modelamos o banco com separação clara: schema comex para processos, schema cambial para contratos de câmbio, schema tracking para rastreamento. Isso facilitou permissões granulares, já que o time financeiro acessa apenas o schema cambial.

Integração SISCOMEX

Essa foi a parte mais difícil do projeto.

Autenticação por certificado digital

O SISCOMEX exige autenticação via certificado ICP-Brasil (e-CNPJ A1). No .NET, isso significa carregar o certificado .pfx e anexá-lo ao HttpClientHandler:

var cert = new X509Certificate2(certPath, certPassword);
var handler = new HttpClientHandler();
handler.ClientCertificates.Add(cert);

var client = new HttpClient(handler);
client.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", accessToken);

O token expira em 1 hora. Implementamos um DelegatingHandler customizado que renova o token automaticamente quando recebe 401.

Registro de DI automatizado

O fluxo de registro de Declaração de Importação (DI) no sistema funciona assim:

1. Operador preenche dados básicos (importador, fornecedor, incoterm, modal)
2. Sistema puxa NCMs do catálogo interno e calcula impostos estimados
3. Operador revisa e confirma
4. Sistema monta o payload JSON conforme schema do Portal Único e envia via API
5. SISCOMEX retorna número da DI e canal de parametrização (verde, amarelo, vermelho, cinza)
6. Sistema atualiza a timeline e dispara notificações por canal

O ponto crítico aqui: o schema do Portal Único muda sem aviso prévio. Em 8 meses de projeto, tivemos 3 breaking changes na API de registro de DI. Criamos uma camada de serialização versionada para lidar com isso. Cada versão do schema é um record C# separado, e um factory resolve qual usar com base na data do registro.

CE e exportação

Para Comprovantes de Exportação, o fluxo é análogo, mas com particularidades. A DU-E (Declaração Única de Exportação) exige vínculo com nota fiscal eletrônica. Construímos um parser de XML de NF-e que extrai automaticamente os dados necessários (chave de acesso, itens, NCM, peso) e preenche a DU-E.

Gestão cambial

Cada processo de importação tem um ou mais contratos de câmbio vinculados. O módulo cambial controla:

Campo	Descrição
Contrato	Número do contrato de câmbio junto ao banco
Moeda	USD, EUR, CNY, JPY
Taxa contratada	Taxa de câmbio fixada no fechamento
Taxa PTAX	Taxa de referência do Banco Central na data de liquidação
Valor FOB	Valor da mercadoria na origem
Spread	Diferença entre taxa contratada e PTAX
Liquidação	Data e valor efetivamente liquidado

O sistema calcula automaticamente o custo efetivo em BRL de cada importação, considerando taxa de câmbio, frete internacional, seguro, capatazia e impostos. Isso alimenta um dashboard de custo por processo que a diretoria usa para decisões de pricing.

Um job Hangfire roda às 13h (após a divulgação da PTAX de fechamento pelo Banco Central) e atualiza todos os contratos pendentes automaticamente.

Rastreamento de cargas

O módulo de tracking acompanha a carga desde a saída do porto de origem até a chegada ao armazém do cliente. Integramos com três fontes de dados:

1. Armadores: APIs de rastreamento de container (Maersk, MSC, Hapag-Lloyd). Cada armador tem formato próprio. Normalizamos tudo em um modelo interno.
2. Terminais portuários: consulta de presença de carga em Santos, Paranaguá e Itajaí via web scraping (esses terminais não oferecem API pública).
3. Transportadoras: integração via EDI para o trecho porto-armazém.

O scraping dos terminais portuários foi o componente mais frágil. Os sites mudam o HTML sem aviso. Isolamos cada scraper em um microserviço separado com health check próprio. Quando o scraper quebra, o sistema sinaliza "dados desatualizados" na interface em vez de mostrar informação incorreta.

O que funcionou bem

Automação do registro de DI reduziu o tempo médio de 45 minutos para 8 minutos por processo. O ganho vem da eliminação de digitação manual e do preenchimento automático via catálogo de produtos e fornecedores cadastrados.

A timeline visual de processos eliminou as reuniões diárias de status. Antes, o gerente de importação gastava 1 hora por dia perguntando "como está o processo X?". Agora a informação está no painel, atualizada em tempo real.

O módulo cambial evitou R$ 120 mil em perdas no primeiro semestre. O sistema alerta quando a diferença entre taxa contratada e PTAX ultrapassa um threshold configurável, permitindo renegociação com o banco antes da liquidação.

O que foi difícil

A instabilidade das APIs do SISCOMEX é um problema real. Timeouts de 30 segundos são comuns em horários de pico. Implementamos retry com exponential backoff e circuit breaker via Polly. Mesmo assim, em dias de alta demanda, o sistema enfileira registros e processa em janelas de menor tráfego.

O web scraping de terminais portuários exige manutenção constante. A cada 2 a 3 meses, algum terminal muda o layout do site. Mantemos alertas no Slack quando o scraper falha por 3 execuções consecutivas.

A legislação comex muda com frequência. Modelamos todas as regras tributárias como configuração em banco de dados, não como código hardcoded. Isso permite que o time de operações atualize regras sem deploy.

Stack final

React 18, Vite, TailwindCSS, .NET 8, C#, SQL Server 2022, Hangfire, Polly, SignalR, Docker, Azure App Service

---

A Bradata constrói sistemas de comércio exterior sob medida, com integração real ao SISCOMEX e automação de processos de importação e exportação. Se sua operação comex ainda depende de planilhas e acesso manual, fale com a gente.