Integração SISCOMEX e Portal Único de Comércio Exterior: guia técnico de API, DUIMP, LPCO e CCT

A reforma do comex tirou o despacho do papel. Agora exige integração de verdade.

A digitalização do comércio exterior brasileiro, descrita em Comércio exterior 2.0: a digitalização do SISCOMEX, DUIMP e o que muda, mudou o cenário. Em 2026, importador ou exportador que opera via Portal Único de forma manual está deixando produtividade na mesa. O ganho de operar via API é entre 60% e 78% de redução em tempo de despacho.

Esse post é o guia técnico para integrar seu sistema corporativo às APIs do Portal Único Siscomex. Não é "vendedor mostrando funcionalidade". É o blueprint que um time de engenharia precisa para começar a implementar hoje.

Visão geral das APIs do Portal Único

O Portal Único expõe famílias de APIs:

Módulo	Função
Catálogo de Produtos	CRUD do catálogo de produtos do importador
DUIMP	Declaração Única de Importação
DU-E	Declaração Única de Exportação
LPCO	Licenças, Permissões, Certificados e Outros (anuências)
CCT	Controle de Carga e Trânsito
Pagamento Centralizado	Liquidação tributária consolidada
Catálogo de Operadores	Despachantes, transportadores, agentes

Todas seguem padrão REST + JSON, autenticação via OAuth 2.0 com certificado ICP-Brasil. Documentação oficial: portalunico.siscomex.gov.br/portal/api/ (referência publica + sandbox de homologação).

Autenticação: o passo zero

Diferente de APIs SaaS normais, o Portal Único exige autenticação por certificado digital ICP-Brasil (e-CPF do responsável legal ou e-CNPJ da empresa). O fluxo:

1. Empresa tem certificado A1 (em arquivo .pfx) ou A3 (em token físico)
2. Sistema carrega certificado e envia request à autenticação:
   POST /api/auth/token
   Headers:
     Content-Type: application/x-www-form-urlencoded
   Body:
     grant_type=client_credentials&scope=siscomex
   TLS Client Cert: <certificado da empresa>

3. Resposta:
   {
     "access_token": "eyJhbG...",
     "expires_in": 3600,
     "token_type": "Bearer",
     "scope": "siscomex"
   }

4. Próximas chamadas levam Authorization: Bearer <token>

Gestão de certificado em produção

• A1 (arquivo .pfx): melhor para automação, expira em 1 ano. Guardar em HSM ou secrets manager (AWS Secrets Manager, Azure Key Vault). NUNCA no repositório.
• A3 (token físico): Mais seguro, mas não automatizável. Em projetos sob medida, usamos A1 em HSM gerenciado.
• Renovação: monitorar validade. Alerta 30 dias antes de expirar. Renovação em ICP-Brasil leva 2–10 dias úteis.

Refresh de token

• Token vida 1 hora. Não fazer login a cada request: cache o token, refresha 5 min antes de expirar.
• Para muitos workers, usar token store centralizado (Redis com TTL).
• Em caso de 401, retry com token novo automaticamente.

Catálogo de Produtos: o pré-requisito

Antes de qualquer DUIMP, catalogar produtos que serão importados. O fluxo:

1. Listar atributos por NCM

GET /api/catalogo/ncm/{ncm}/atributos
Authorization: Bearer ...

Response 200:
{
  "ncm": "85176210",
  "atributos": [
    { "codigo": "ATT001", "nome": "Tipo de equipamento", "tipo": "lista", "valores": ["Roteador", "Switch", "Modem"], "obrigatorio": true },
    { "codigo": "ATT002", "nome": "Capacidade de portas", "tipo": "numerico", "obrigatorio": true },
    { "codigo": "ATT003", "nome": "Velocidade", "tipo": "lista", "valores": ["100Mbps", "1Gbps", "10Gbps"], "obrigatorio": true }
  ]
}

2. Criar produto no catálogo

POST /api/catalogo/produto
Authorization: Bearer ...
Content-Type: application/json

{
  "ncm": "85176210",
  "descricao_comercial": "Roteador Cisco RV340 Dual WAN VPN",
  "descricao_tecnica": "Roteador empresarial com 2 portas WAN gigabit, 4 portas LAN gigabit, VPN site-to-site IPsec",
  "marca": "Cisco",
  "modelo": "RV340",
  "fabricantes": [
    { "razao_social": "Cisco Systems Inc", "pais": "US" }
  ],
  "atributos": [
    { "codigo": "ATT001", "valor": "Roteador" },
    { "codigo": "ATT002", "valor": 6 },
    { "codigo": "ATT003", "valor": "1Gbps" }
  ],
  "ex_tarifario": null,
  "destacavel": false
}

Response 201:
{
  "id": "prod_12345678",
  "codigo_interno": "CAT-2026-00001",
  "status": "ativo"
}

3. Reutilizar o produto em DUIMPs

O id do produto é referenciado em cada DUIMP. Não precisa redigitar a cada operação. Esse é o ganho principal do Catálogo.

Erros comuns

• Atributo faltando: NCMs eletrônicos têm 8–14 atributos obrigatórios. Esquecer um = produto rejeitado.
• Fabricante não cadastrado: Receita Federal mantém cadastro de fabricantes. Se o fabricante novo, pode levar validação.
• Descrição genérica demais: "produto eletrônico" não passa. Específica obrigatoriamente.

DUIMP: o ciclo completo

O fluxo de uma DUIMP, do registro à conclusão:

1. Registrar DUIMP

POST /api/duimp
Authorization: Bearer ...
Content-Type: application/json

{
  "importador": { "cnpj": "12345678000199" },
  "modalidade": "para_consumo",
  "tipo_carga": "FCL",
  "via_transporte": "maritima",
  "data_chegada_prevista": "2026-06-15",
  "porto_descarga": "BRSSZ",
  "moeda_negociacao": "USD",
  "incoterm": "FOB",
  "fornecedor": {
    "nome": "Acme Trading Co Ltd",
    "pais": "CN"
  },
  "itens": [
    {
      "ordem": 1,
      "produto_catalogo_id": "prod_12345678",
      "quantidade": 100,
      "unidade": "UN",
      "valor_unitario_moeda": 152.50,
      "peso_liquido_kg": 0.8,
      "peso_bruto_kg": 1.2,
      "frete_internacional_moeda": 8.00,
      "seguro_internacional_moeda": 0.50
    }
  ],
  "documentos_eletronicos": [
    {
      "tipo": "INVOICE",
      "numero": "INV-2026-00789",
      "hash_sha256": "abc123...",
      "url": "https://meusistema.com.br/docs/inv-789.pdf"
    },
    {
      "tipo": "PACKING_LIST",
      "numero": "PL-2026-00789",
      "hash_sha256": "def456..."
    },
    {
      "tipo": "BL",
      "numero": "BL-2026-789-XX",
      "hash_sha256": "ghi789..."
    }
  ]
}

Response 201:
{
  "id": "duimp_98765432",
  "numero_duimp": "26BR12345670000001",
  "status": "registrada",
  "canal_estimado": "verde",
  "tributos_estimados": {
    "ii": { "aliquota": 0.16, "valor_brl": 2440.00 },
    "ipi": { "aliquota": 0.15, "valor_brl": 2287.50 },
    "pis_importacao": { "aliquota": 0.021, "valor_brl": 320.25 },
    "cofins_importacao": { "aliquota": 0.0965, "valor_brl": 1472.49 },
    "icms_importacao": { "aliquota": 0.18, "valor_brl": 2746.13 }
  }
}

2. Acompanhar status

GET /api/duimp/{id}
Authorization: Bearer ...

Response 200:
{
  "id": "duimp_98765432",
  "status": "em_analise",
  "canal": "amarelo",
  "exigencia_documental": null,
  "eventos": [
    { "timestamp": "2026-06-10T09:23:11Z", "tipo": "REGISTRO", "descricao": "DUIMP registrada" },
    { "timestamp": "2026-06-10T11:45:33Z", "tipo": "PARAMETRIZACAO", "descricao": "Selecionada para canal amarelo" }
  ]
}

3. Webhook de mudança de status

Sistema do importador registra webhook para receber updates assíncronos:

POST /api/webhook/registrar
{
  "url": "https://meusistema.com.br/api/webhooks/duimp",
  "eventos": ["DUIMP_PARAMETRIZADA", "DUIMP_EXIGENCIA", "DUIMP_DESEMBARACADA"],
  "secret": "<segredo do webhook>"
}

# Quando DUIMP muda de status, recebe:
POST https://meusistema.com.br/api/webhooks/duimp
X-Signature: <HMAC do payload>
{
  "evento": "DUIMP_DESEMBARACADA",
  "duimp_id": "duimp_98765432",
  "timestamp": "2026-06-12T14:30:00Z",
  "dados": {...}
}

Sempre validar HMAC do webhook (não confie em chamadas externas sem assinatura).

4. Em caso de exigência documental

SEFAZ pede documento adicional. Sistema responde:

POST /api/duimp/{id}/exigencias/{exigencia_id}/responder
{
  "resposta": "Documento anexado em referência à solicitação X",
  "documentos": [
    { "tipo": "CERTIFICADO_ORIGEM", "hash_sha256": "...", "url": "..." }
  ]
}

LPCO: pedindo licença unificada

O fluxo de pedido de licença (ex: Anvisa pra cosmético importado):

POST /api/lpco/pedido
Authorization: Bearer ...

{
  "orgao_anuente": "ANVISA",
  "tipo_pedido": "RDC_LICENCIAMENTO",
  "produtos": [
    { "produto_catalogo_id": "prod_12345678", "quantidade": 100 }
  ],
  "documentos": [
    { "tipo": "REGISTRO_ANVISA", "numero": "MS-2.3456.0789", "url": "..." }
  ]
}

Response 201:
{
  "lpco_id": "lpco_456",
  "status": "submetido",
  "prazo_analise_estimado": "2026-06-20"
}

Status possíveis:

• submetido: pendente análise
• em_analise: anuente revisando
• exigencia: anuente pediu mais informação
• deferido: aprovado, pode usar na DUIMP
• indeferido: rejeitado

A LPCO deferida é referenciada na DUIMP automaticamente.

CCT: rastreando a carga

GET /api/cct/conhecimento/{numero_bl}
Authorization: Bearer ...

Response 200:
{
  "numero_bl": "MAEU123456789",
  "navio": "EVER GIVEN",
  "viagem": "VYG-2026-15",
  "porto_origem": "CNSGH",
  "porto_destino": "BRSSZ",
  "data_partida_origem": "2026-05-15",
  "data_chegada_estimada": "2026-06-12",
  "status_atual": "em_transito",
  "containers": [
    {
      "numero": "MAEU1234567",
      "tipo": "20DV",
      "lacre": "LACRE-2026-001",
      "peso_carga_kg": 18000
    }
  ]
}

Útil para:

• Antecipar problemas (atraso, desvio de rota)
• Calcular demurrage iminente
• Sincronizar com sistema WMS para reserva de espaço no armazém

Padrões de produção que importam

Retry strategy

Portal Único pode ter latência variável e ocasionalmente timeout. Strategy padrão:

Tipo de erro	Retry?	Backoff
Timeout (>30s sem resposta)	Sim, até 3x	5s, 20s, 60s
503 Service Unavailable	Sim, até 5x	exponencial 5s..120s
429 Rate Limit	Sim	aguardar Retry-After header
400 Bad Request	Não	validar dado antes
401 Unauthorized	Sim, 1x após refresh token	imediato
422 Unprocessable Entity	Não	corrigir payload
500 Internal Server Error	Sim, 3x	10s, 30s, 90s

Idempotência

Toda operação POST deve incluir header Idempotency-Key com UUID único. Garante que retry não cria DUIMP duplicada:

POST /api/duimp
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Observabilidade

Para cada chamada, logar:

• Request ID (gerado no seu lado)
• Endpoint chamado
• Status HTTP retornado
• Latência
• Resposta resumida

Dashboard mostra:

• Taxa de sucesso/erro por endpoint
• Latência p50/p95/p99
• Volume de chamadas por hora
• Top códigos de erro

Rate limiting

Portal Único impõe rate limits (varia por endpoint, tipicamente 60–600 req/min). Implementar rate limiter do seu lado para não estourar:

• Token bucket por endpoint
• Fila de espera se aproximar do limite
• Métrica de "throttling do nosso lado"

Sandbox vs produção

Portal Único tem ambiente de homologação separado. Sempre testar em sandbox primeiro. Diferenças importantes:

• Sandbox tem dados sintéticos
• Sandbox pode estar mais instável
• Validação fiscal em sandbox simula, em produção vale

Pipeline de deploy: dev → sandbox → produção, com validação automatizada de happy path + edge cases em sandbox antes de production.

Patterns de produção: o que separa integração amadora de profissional

1. Diff-based sync de Catálogo

Em vez de re-enviar produtos toda vez, manter local o hash do produto e enviar só os modificados. Se hash igual ao remoto, skip.

2. Pré-validação no seu lado

Antes de submeter DUIMP, rodar validações sintáticas localmente. Reduz rejeição (que custa tempo).

3. Catálogo de produtos sincronizado

Ter sincronização bidirecional entre seu sistema e o Catálogo. Catálogo é fonte da verdade para o que o governo "vê", seu sistema é fonte da verdade para o que sua operação opera.

4. Cálculo tributário paralelo

Calcular tributos localmente com motor próprio. Comparar com o calculado pelo Portal Único. Divergência = bug em algum lado, debug.

5. Audit log de comex

Toda operação tem trilha: quem registrou DUIMP X, quando, com qual valor. Para auditoria fiscal/aduaneira.

6. Conciliação contábil

DUIMP desembaraçada gera NF de entrada no ERP automaticamente. Tributos pagos refletem em DRE. Sistema de comex que não fala com ERP gera retrabalho contábil.

Erros que vimos em produção (e como evitar)

"Sistema reenvia DUIMP toda vez que cliente clica em 'Submeter'"

Falta de idempotência. 14 DUIMPs duplicadas para um único container. Cancelar todas custou 3 semanas.

Fix: Idempotency-Key obrigatório, lock no botão pós-clique, status visível ao usuário.

"Token expirou de noite, todos os jobs falharam"

Token cache sem refresh proativo.

Fix: refresh 5 min antes de expirar, monitoramento de age do token.

"Certificado A1 expirou em produção, ninguém viu"

Falta de alerta de validade.

Fix: cron diário verifica validade, alerta 30/14/7 dias antes.

"Erro 400 acontece intermitentemente"

Cliente está enviando timestamps em fuso errado (UTC vs BRT).

Fix: sempre normalizar para ISO 8601 com offset explícito.

"Webhook chega múltiplas vezes para mesmo evento"

Portal Único retenta se não recebeu 200 rápido.

Fix: handler de webhook precisa ser rápido (< 2s), com fila interna para processamento pesado, e idempotente (registrar event_id processado).

A entrega que a Bradata faz

Quando construímos sistema de comex sob medida, entregamos:

• Cliente API Siscomex completo (DUIMP, DU-E, LPCO, CCT, Catálogo)
• Cache de Catálogo sincronizado
• Pipeline assíncrono com fila e retry
• Dashboard de operações em tempo real
• Webhook handler com validação HMAC
• Motor tributário paralelo para validação cruzada
• Integração com ERP (NF de entrada automatizada)
• Audit log completo
• Monitoring stack (Grafana, Sentry)

Conheça nosso sistema de comércio exterior e aprofunde em Comércio exterior 2.0: digitalização e DUIMP.

Conclusão

Integração Portal Único Siscomex em 2026 é infraestrutura crítica para qualquer operação séria de comex. Sistema integrado bem reduz tempo de despacho de 9 dias para 4 dias, custo por operação em 45%, e dá visibilidade que despachante manual não consegue.

Se você opera comex e quer modernizar com integração API, fale conosco. Em 24 horas úteis fazemos análise inicial.

A Bradata é uma software house brasileira com profundidade em comércio exterior, fiscal e desenvolvimento sob medida. Veja cases e soluções.

---

Fontes: Portal Único Siscomex Documentação API (portalunico.siscomex.gov.br), Instrução Normativa RFB 2.090/2022, Instrução Normativa SECEX 28/2018, Manual de Operação DUIMP v3.2 (2026), projetos internos Bradata.