Integrar aduana Colombia (DIAN) a tu ERP con API SonarTrade

El problema: la DIAN no publica API

La Direccion de Impuestos y Aduanas Nacionales (DIAN) de Colombia publica sus datos de comercio exterior en archivos XLSX cargados a un SharePoint publico. Los archivos son acumulativos por ano y se actualizan mensualmente, normalmente entre el 15 y el 20 del mes siguiente. No hay endpoint REST, no hay webhook, no hay autenticacion. Si quieres integrar este dato a tu ERP tienes que scrapear el SharePoint, bajar XLSX pesados (100-200 MB cada uno), parsearlos y normalizar.

Estructura de los archivos DIAN

Cada XLSX tiene un prefijo de mes (01_ para enero, 02_ para febrero) y contiene todas las operaciones acumuladas desde el 1 de enero del ano hasta el cierre de ese mes. Las columnas incluyen NIT del importador, razon social, subpartida NANDINA, pais de origen, aduana, cantidad, peso, FOB USD, flete, seguro y CIF USD. El formato cambio al menos 3 veces entre 2020 y 2025, lo que complica parsers naive.

Scraping manual: que implica

Si optas por el camino manual, necesitas: (1) un crawler que detecte archivos nuevos en el SharePoint, (2) un parser XLSX que maneje los cambios de formato, (3) un sistema de deduplicacion porque los archivos son acumulativos (el archivo de febrero incluye enero), (4) normalizacion de NIT (algunos vienen con digito de verificacion, otros no), (5) un pipeline que maneje fallos (los archivos a veces se suben corruptos). Mantener este stack cuesta entre 20 y 40 horas mensuales de ingenieria.

La alternativa: API SonarTrade

SonarTrade ya corre ese pipeline en produccion. El ingest filtra por prefijo mensual (01_*, 02_*, etc.) para evitar reprocesar datos acumulativos, normaliza NITs al estandar de 9 digitos sin digito de verificacion, unifica los cambios de schema historicos y escribe en la tabla canonica public.movements. Tú consumes el dato ya limpio via API REST con autenticacion por API Key.

Endpoint de empresas: /api/integration/companies/{entity_id}

El endpoint principal para integrar con un ERP es el de empresas. Primero buscas la empresa por NIT o razon social con el parametro q en /api/integration/companies, y con el entity_id del resultado obtienes el perfil completo (operaciones historicas, resumen por HS, top paises de origen y tendencia mensual) en /api/integration/companies/{entity_id}. Autenticacion via header X-API-Key. Ejemplo basico con curl:

curl -H "X-API-Key: tu_api_key" \
  "https://sonartrade.app/api/integration/companies?country_id=62&q=900123456&limit=10"

curl -H "X-API-Key: tu_api_key" \
  "https://sonartrade.app/api/integration/companies/{entity_id}?country_id=62"

La respuesta es JSON con operaciones, cada una con fecha, HS, producto, pais origen, cantidad, FOB y CIF. El rate limit en plan Business es 120 requests/minuto.

Endpoint de busqueda por HS

Para alimentar modulos de market intelligence conviene usar busqueda por subpartida:

curl -H "X-API-Key: tu_api_key" \
  "https://sonartrade.app/api/integration/search?country_id=62&hs=847130&tipo_operacion_id=1&date_from=2025-01-01&limit=100"

Este query devuelve todas las importaciones colombianas de portatiles (HS 8471.30) desde enero 2025. Se puede paginar con offset y limit, y filtrar por texto libre (q), tipo de operacion (tipo_operacion_id) y rango de fechas (date_from/date_to).

Webhooks y alertas

Para integraciones ETL, SonarTrade ofrece webhooks Business+ solo para alertas de watchlist (evento watchlist.alert). No hay webhooks de sincronización de datos: para cargar nuevos cortes a tu ERP usa la API de integración con polling.

Frecuencia de actualizacion

Los datos se actualizan según la disponibilidad de cada fuente oficial y el calendario operativo de SonarTrade. La latencia puede variar por publicación, formato y validación de la fuente; si necesitas un compromiso específico, se define por contrato Enterprise.

Casos de uso tipicos

Agencias de aduana colombianas usan la API para enriquecer fichas de clientes con historial de operaciones. ERPs sectoriales (textil, agroindustria) integran el endpoint de HS para mostrar benchmarks de precio dentro de su propia app. Consultoras de trade arman dashboards mensuales alimentados por el endpoint de busqueda. Empresas extranjeras con presencia regional consolidan datos de 5 paises LATAM en un solo data warehouse gracias a que public.movements tiene schema unificado.

Planes y precios

El acceso a la API esta disponible desde plan Business (USD 349/mes, 5.000 requests/dia). Enterprise (desde USD 1.299/mes) incluye 25.000 requests/día y soporte prioritario; SLA, soporte dedicado y rate limits custom se definen por contrato Enterprise. Revisa /pricing para comparativa completa y /embed/docs para la referencia tecnica de los endpoints.

Ahorro concreto vs scraping propio

Un equipo tipico que decide scrapear DIAN invierte 80-120 horas en setup inicial (scraper, parser, normalizacion, deploy) y 20-40 horas/mes en mantenimiento. A USD 50/hora de ingenieria eso son USD 5.000-7.000 de setup y USD 1.000-2.000 mensuales. El plan Business de SonarTrade cuesta USD 349/mes con data de los 5 paises LATAM, no solo Colombia. El payback es inmediato.

Revisa los planes en /pricing y la documentacion de endpoints en /embed/docs. Si necesitas un caso de integracion custom, escríbenos.