posts

API HS Code para Aduanas: Guía de Integración y Automatización

Jorge Parada Fernandez

— 6 min read

API HS Code para Aduanas: Guía de Integración y Automatización

La clasificación arancelaria es uno de los cuellos de botella más críticos en el comercio internacional. Esta guía te muestra cómo automatizar la clasificación HS Code mediante APIs, reduciendo errores y acelerando el despacho aduanero.

Impacto real: Empresas que automatizan la clasificación HS reducen los retrasos aduaneros un 40% y los errores de clasificación en un 65%.

¿Qué es el código HS?

Sistema Armonizado de Designación y Codificación de Mercancías

El código HS (Harmonized System) es el estándar internacional para clasificar productos en comercio internacional:

| Nivel | Dígitos | Descripción | Ejemplo | | -------------------- | ------- | ------------------- | -------------------------------------------- | | Capítulo | 2 | Área general | 84 (Reactores nucleares, calderas, máquinas) | | Partida | 4 | Categoría | 8421 (Máquinas y aparatos para centrifugar) | | Subpartida | 6 | Producto específico | 842121 (Máquinas para filtrar agua) | | UE (CN) | 8 | Código combinado UE | 84212100 (Misma subpartida) | | Completo (TARIC) | 10 | Arancel completo | 8421210000 (Con medidas comerciales) |

¿Por qué es crítico?

- Aranceles: Determina el % de derechos a pagar - Estadísticas: Base para comercio exterior - Regulaciones: Identifica restricciones (licencias, sanidad) - Origen: Fundamental para acuerdos comerciales

Error de clasificación:

- Retrasos en frontera - Multas (hasta 3x valor de mercancía) - Decomiso de productos - Sanciones administrativas

API de HS Code de TRANSCEND

Características principales

POST https://api.transcend.cargoffer.com/v1/hs-code/classify

Capacidades:

✅ Clasificación automática: ML + base de datos arancelaria ✅ Validación de códigos: Verifica existencia y validez ✅ Búsqueda inversa: Encuentra producto por código ✅ Batch processing: Clasifica múltiples productos ✅ Historial: Aprende de clasificaciones anteriores

Ejemplo de uso

const classification = await fetch(
  "https://api.transcend.cargoffer.com/v1/hs-code/classify",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      description: "Máquina de café espresso automática para uso doméstico",
      origin: "CN",
      destination: "ES",
      context: "import",
    }),
  },
);

Respuesta:

{
  "query": "Máquina de café espresso automática para uso doméstico",
  "suggestions": [
    {
      "hsCode": "851671",
      "description": "Aparatos electrotermicos para preparar café",
      "confidence": 0.94,
      "tariffRate": 2.7,
      "category": "Electrodomésticos",
      "regulations": ["CE marking required"],
      "additionalCodes": {
        "CN": "85167100",
        "TARIC": "8516710000"
      }
    },
    {
      "hsCode": "851679",
      "description": "Otros aparatos electrotermicos para preparar bebidas",
      "confidence": 0.78,
      "tariffRate": 2.7
    }
  ],
  "processingTime": "0.3s",
  "validation": {
    "valid": true,
    "lastUpdated": "2026-02-12"
  }
}

Integración paso a paso

Paso 1: Configurar autenticación

// Node.js
const axios = require("axios");const TRANSCEND_API_KEY = process.env.TRANSCEND_API_KEY;
const BASE_URL = "https://api.transcend.cargoffer.com/v1";

Python
import requests
import osTRANSCEND_API_KEY = os.environ.get('TRANSCEND_API_KEY')
BASE_URL = 'https://api.transcend.cargoffer.com/v1'

Paso 2: Clasificar un producto

async function classifyProduct(description, origin, destination) {
  try {
    const response = await api.post("/hs-code/classify", {
      description: description,
      origin: origin, // Código país ISO (ej: 'CN')
      destination: destination, // Código país ISO (ej: 'ES')
      context: "import", // 'import' o 'export'
    });    return response.data;
  } catch (error) {
    console.error("Error de clasificación:", error.message);
    throw error;
  }
}// Ejemplo de uso
const result = await classifyProduct(
  "Piezas de repuesto para máquinas industriales de corte láser",
  "DE",
  "ES",
);

Paso 3: Procesamiento por lotes (Batch)

async function classifyBatch(products) {
  const response = await api.post("/hs-code/classify-batch", {
    products: products.map((p) => ({
      id: p.id,
      description: p.description,
      origin: p.origin,
      destination: p.destination,
    })),
  });  return response.data.results;
}// Ejemplo con catálogo de productos
const catalog = [
  {
    id: "SKU001",
    description: "Tornillos de acero inoxidable M8",
    origin: "CN",
    destination: "ES",
  },
  {
    id: "SKU002",
    description: "Motor eléctrico trifásico 5HP",
    origin: "IT",
    destination: "PT",
  },
  {
    id: "SKU003",
    description: "Válvulas de bola de latón",
    origin: "DE",
    destination: "ES",
  },
];const classifications = await classifyBatch(catalog);

Paso 4: Validar código existente

async function validateHsCode(hsCode, origin, destination) {
  const response = await api.get("/hs-code/validate", {
    params: {
      code: hsCode,
      origin: origin,
      destination: destination,
    },
  });  return response.data;
}// Ejemplo
const validation = await validateHsCode("851671", "CN", "ES");

Flujo de trabajo completo

Escenario: Importación de electrónica desde China

┌─────────────────┐
│ 1. Producto en  │
│    sistema ERP  │
└────────┬────────┘
         │
         ▼
┌─────────────────────────┐
│ 2. Enviar descripción   │
│    a API TRANSCEND      │
│    (automático)         │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│ 3. Recibir sugerencias  │
│    HS + confianza       │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐     Sí      ┌──────────────────┐
│ 4. ¿Confianza > 90%?    │────────────▶│ 5. Aprobar       │
└────────┬────────────────┘              │    automáticamente
         │ No                            └────────┬─────────┘
         ▼                                        │
┌─────────────────────────┐                       │
│ 6. Revisión experto     │◄──────────────────────┘
│    aduanero             │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│ 7. Generar DUA con      │
│    código validado      │
└────────┬────────────────┘
         │
         ▼
┌─────────────────────────┐
│ 8. Presentar en aduana  │
│    (risk-based)         │
└─────────────────────────┘

Implementación práctica

class CustomsAutomation {
  constructor(apiKey) {
    this.api = axios.create({
      baseURL: "https://api.transcend.cargoffer.com/v1",
      headers: {
        Authorization: Bearer ${apiKey},
        "Content-Type": "application/json",
      },
    });
  }  async processImport(product) {
    // Paso 1: Clasificar producto
    const classification = await this.classify(product);    // Paso 2: Decidir flujo según confianza
    if (classification.suggestions[0].confidence >= 0.9) {
      // Auto-aprobación
      return await this.autoApprove(product, classification);
    } else {
      // Revisión manual
      return await this.queueForReview(product, classification);
    }
  }  async classify(product) {
    const response = await this.api.post("/hs-code/classify", {
      description: product.description,
      origin: product.originCountry,
      destination: product.destinationCountry,
      context: "import",
    });    return response.data;
  }  async autoApprove(product, classification) {
    const hsCode = classification.suggestions[0];    // Calcular costes aduaneros
    const customsCost = {
      cifValue: product.value,
      tariff: hsCode.tariffRate,
      duty: product.value * (hsCode.tariffRate / 100),
      vat: product.value * 0.21, // IVA España
      total: 0,
    };
    customsCost.total = customsCost.duty + customsCost.vat;    return {
      status: "approved",
      hsCode: hsCode.hsCode,
      confidence: hsCode.confidence,
      customsCost: customsCost,
      duas: await this.generateDUA(product, hsCode, customsCost),
    };
  }  async queueForReview(product, classification) {
    // Enviar a cola de revisión experto
    return {
      status: "pending_review",
      product: product,
      suggestions: classification.suggestions,
      assignedTo: "customs_expert_queue",
    };
  }
}// Uso
const automation = new CustomsAutomation("YOUR_API_KEY");const importProcess = await automation.processImport({
  sku: "ELEC-2847",
  description: 'Smartphone 5G con pantalla OLED 6.7"',
  value: 450.0,
  originCountry: "CN",
  destinationCountry: "ES",
  quantity: 100,
});

Casos de uso por industria

1. Textil y moda

Desafío: Productos con materiales mixtos, tejidos complejos

const textileProduct = {
  description: "Vestido de mujer 60% algodón 40% poliéster",
  origin: "BD", // Bangladesh
  destination: "ES",
};

2. Electrónica

Desafío: Componentes vs productos terminados

const electronicProduct = {
  description: "Módulo de pantalla LCD TFT 7 pulgadas con controlador",
  origin: "CN",
  destination: "PT",
};

3. Automoción

Desafío: Piezas de repuesto, accesorios

const autoPart = {
  description: "Filtro de aceite para motor diésel de vehículo comercial",
  origin: "DE",
  destination: "ES",
};

4. Alimentación

Desafío: Productos frescos, regulaciones sanitarias

const foodProduct = {
  description: "Aceite de oliva virgen extra en envases de 5 litros",
  origin: "IT",
  destination: "ES",
};

Mejores prácticas

1. Validación humana para confianza baja

const CONFIDENCE_THRESHOLD = 0.85;async function classifyWithValidation(description) {
  const result = await api.post("/hs-code/classify", { description });  const topSuggestion = result.suggestions[0];  if (topSuggestion.confidence < CONFIDENCE_THRESHOLD) {
    // Enviar a revisión experto
    await notifyCustomsExpert(description, result.suggestions);
    return { status: "manual_review_required" };
  }

2. Cachear resultados frecuentes

const classificationCache = new Map();
const CACHE_TTL = 30  24  60  60  1000; // 30 díasasync function getCachedClassification(description) {
  const cacheKey = description.toLowerCase().trim();
  const cached = classificationCache.get(cacheKey);  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }  const result = await api.post("/hs-code/classify", { description });
  classificationCache.set(cacheKey, {
    data: result,
    timestamp: Date.now(),
  });

3. Mantener historial de decisiones

// Almacenar decisiones para ML
async function logClassificationDecision(product, suggestion, approved) {
  await api.post("/hs-code/feedback", {
    query: product.description,
    suggestedCode: suggestion.hsCode,
    approved: approved,
    correctedCode: approved ? null : correctedCode,
    context: {
      origin: product.origin,
      destination: product.destination,
      industry: product.industry,
    },
  });
}

Integración con sistemas existentes

SAP

// RFC call desde SAP
const sapIntegration = {
  rfcName: "Z_HSCODE_CLASSIFY",
  parameters: {
    IV_DESCRIPTION: product.description,
    IV_ORIGIN: product.origin,
    IV_DESTINATION: product.destination,
  },
  result: {
    EV_HSCODE: classification.hsCode,
    EV_CONFIDENCE: classification.confidence,
    EV_TARIFF: classification.tariffRate,
  },
};

Odoo

Módulo personalizado Odoo
from odoo import models, fields, apiclass ProductTemplate(models.Model):
    _inherit = 'product.template'    hs_code = fields.Char(string='HS Code')
    hs_confidence = fields.Float(string='Classification Confidence')    def auto_classify_hs(self):
        for product in self:
            result = self.env['transcend.api'].classify(
                description=product.name,
                origin=product.country_of_origin.code,
                destination='ES'
            )

WooCommerce/Shopify

// Plugin WordPress
add_action('woocommerce_product_options_general_product_data', 'add_hs_code_field');function add_hs_code_field() {
    woocommerce_wp_text_input([
        'id' => '_hs_code',
        'label' => 'HS Code',
        'description' => 'Código arancelario para exportación'
    ]);
}add_action('woocommerce_process_product_meta', 'save_hs_code');function save_hs_code($post_id) {
    $hs_code = $_POST['_hs_code'];    // Si está vacío, autoclacificar
    if (empty($hs_code)) {
        $product = wc_get_product($post_id);
        $classification = transcend_classify($product->get_name());
        $hs_code = $classification['suggestions'][0]['hsCode'];
    }

Precios y límites

Tier gratuito

- 500 clasificaciones/mes - Confianza básica - Soporte comunitario

Growth

- 10,000 clasificaciones/mes - 99€/mes - Confianza avanzada (ML) - Email support

Enterprise

- Ilimitado - Precio personalizado - Modelos ML custom - API dedicada - Soporte 24/7

Recursos adicionales

- TARIC Consulta - Base de datos OMA HS - Aduanas España - Aduanas Portugal

Preguntas frecuentes

¿Qué es el código HS y por qué es importante?

El código HS (Harmonized System) es un sistema internacional estandarizado de nomenclatura y codificación de mercancías mantenido por la Organización Mundial de Aduanas (OMA). Consta de 6 dígitos y sirve para clasificar productos en aduanas, determinar aranceles, recopilar estadísticas comerciales y aplicar regulaciones. Un código incorrecto puede resultar en retrasos, multas o decomiso de mercancías.

¿Cómo automatizar la clasificación HS Code?

La automatización se logra mediante APIs que utilizan machine learning y bases de datos arancelarias para sugerir códigos HS basados en descripciones de productos. El proceso típico incluye: (1) Enviar descripción del producto a la API, (2) Recibir sugerencias de códigos con nivel de confianza, (3) Validar con experto aduanero, (4) Almacenar para uso futuro. Esto reduce el tiempo de clasificación de horas a segundos y minimiza errores humanos.

¿Qué pasa si el código sugerido es incorrecto?

La API proporciona un nivel de confianza con cada sugerencia. Para clasificaciones con confianza inferior al 85%, recomendamos revisión humana por un experto aduanero. Además, puede proporcionar retroalimentación a la API con el código correcto, mejorando el modelo para futuras clasificaciones similares.

¿La API cubre todos los países?

La API de TRANSCEND cubre toda la base de datos HS (más de 5,000 códigos de productos) que es universal. Para aranceles específicos y regulaciones, actualmente cubrimos la Unión Europea (España, Portugal, Francia, Alemania, Italia) con expansión planificada a otros mercados.

¿Puedo integrar esto con mi software de gestión aduanera?

Absolutamente. La API está diseñada para integración con software de gestión aduanera (SGA), ERPs, e-commerce platforms y TMS. Ofrecemos SDKs para JavaScript, Python, PHP y documentación completa REST API.

¿Listo para automatizar? Prueba la API gratuita con 500 clasificaciones/mes.

_Última actualización: Febrero 2026. Las tarifas arancelarias pueden cambiar; consulta siempre las fuentes oficiales para valores exactos._

Read more