Cuando un comprador llega a la pantalla de pago de una tienda D2C y ve un precio que no incluye el costo real de importación, cierra la pestaña. Según el Baymard Institute, el 48% de los abandonos en compras internacionales ocurren por costos inesperados en el checkout. La solución técnica a ese problema tiene nombre: integración de API de landed cost.
Esta guía es para equipos de e-commerce y squads técnicos que necesitan integrar cálculo de flete e impuestos internacionales en tiempo real en el checkout. Cubriremos los datos necesarios, la arquitectura de integración, los requisitos de performance y los puntos de cumplimiento que determinan si el cálculo será correcto o generará pasivo fiscal.
Qué es una API de landed cost y qué calcula
Una API de landed cost recibe los datos del pedido y devuelve el costo total entregado al comprador. Eso incluye flete internacional, derechos de importación, impuestos locales y tarifas aduanales relevantes para ese destino específico.
Lo que no hace es adivinar. La precisión del resultado depende directamente de la calidad de los datos que envíes. Un código HS incorrecto o ausente produce un cálculo erróneo. Un valor de producto mal declarado genera inconsistencia en la declaración aduanal. Por eso, la integración comienza antes del checkout: comienza en la configuración del catálogo de productos.
Para marcas mexicanas que exportan hacia EUA y Europa, los componentes del cálculo incluyen aranceles basados en el código HS y el origen declarado, Sales Tax americano por estado de destino, VAT europeo por país miembro y el costo de flete calculado con base en el corredor, peso dimensional y nivel de servicio seleccionado.
Datos obligatorios para el cálculo en tiempo real
El payload mínimo que la API necesita recibir por línea de artículo es el código HS del producto, el valor del artículo en moneda base, el peso y las dimensiones, el país de origen del producto y la dirección completa de destino incluyendo código postal.
Datos adicionales que mejoran la precisión del cálculo: categoría de producto para aplicación correcta de alícuotas, composición de material cuando sea relevante para la clasificación, si el artículo contiene batería o es un producto regulado, y el modelo de importación que se usará, DDP o DAP.
La ausencia de cualquier dato obligatorio debe generar un fallback explícito en el frontend, no un cálculo impreciso. Mostrar un costo de flete estimado con una advertencia visible es mejor que mostrar un valor incorrecto que generará una retención aduanal después.
Para marcas mexicanas, las reglas de origen del T-MEC son un input adicional relevante. Si el producto califica como originario bajo las reglas del T-MEC, la API debe poder recibir esa información para aplicar correctamente las preferencias arancelarias en el corredor hacia EUA. Un producto que califica puede tener derecho de 0%, mientras que sin esa declaración pagaría la alícuota general.
Arquitectura de la integración en el checkout
La integración de una API de landed cost en el checkout tiene tres patrones posibles: llamada síncrona al cargar el carrito, llamada síncrona en el evento de cambio de dirección, o precálculo asíncrono con caché por destino y SKU.
La llamada síncrona al cargar el carrito es la más simple de implementar, pero tiene el mayor impacto en el tiempo de respuesta de la página. Si la API de landed cost tiene una latencia superior a 400ms, el usuario percibe la demora antes de ver el total.
La llamada en el evento de cambio de dirección es el patrón más común en checkout D2C. El cálculo se dispara cuando el comprador confirma el código postal o el país de destino, y el resultado se muestra como una línea separada en el resumen del pedido antes de la confirmación del pago. Este enfoque equilibra precisión y performance.
El precálculo asíncrono con caché es recomendable para operaciones con alto volumen en destinos recurrentes. Calculas el landed cost por combinación de SKU y país de destino en batch, almacenas en caché con un TTL de 24 a 48 horas y sirves el resultado del caché en el checkout sin una llamada de API en tiempo real. La desventaja es que el caché debe invalidarse cuando hay cambios en las tarifas o en el flete contratado.
Para integraciones en Shopify, la API de landed cost se conecta mediante Shopify Functions o extensiones de Checkout UI. En VTEX, la integración ocurre mediante las APIs de simulación de carrito o mediante personalización del checkout responsivo. En plataformas headless, el punto de integración es la capa de orquestación que compone el payload antes del renderizado del checkout.
Requisitos de performance y SLA de la API
La latencia máxima aceptable para una llamada de API en el checkout es de 500ms en el percentil 95. Por encima de ese umbral, el impacto en el abandono comienza a ser medible. Una investigación de Google sobre velocidad en páginas móviles indica que un retraso de 1 segundo en la respuesta reduce la conversión hasta en un 20%.
Define un timeout para la llamada de API de landed cost. Si la respuesta no llega dentro del timeout definido, el comportamiento correcto es mostrar una estimación con una advertencia visible o bloquear la finalización del pedido con un mensaje explicativo. Silenciar el error y mostrar cero de impuesto no es un comportamiento aceptable en un checkout con cumplimiento fiscal.
Monitorea de forma separada la tasa de error de la API y la tasa de llamadas con fallback. Un aumento en la tasa de fallback puede indicar que los datos del catálogo de productos están incompletos o que la API está experimentando degradación de performance.
Para operaciones con múltiples destinos simultáneos, considera implementar llamadas paralelas para los corredores más frecuentes durante el onboarding del usuario, antes de que llegue al checkout, para tener el resultado en caché local del navegador cuando lo necesite.
Cumplimiento fiscal y declaración aduanal
El cálculo de landed cost en el checkout no es solo una experiencia de usuario. Es también el dato que alimentará la documentación aduanal cuando el pedido se despache.
Por eso, el valor calculado por la API debe corresponder al valor que se declarará en la factura comercial. Si hay una discrepancia entre lo que el cliente pagó en el checkout y lo que se declaró ante aduana, el paquete puede ser retenido por inconsistencia de valor.
Para operaciones en DDP, estás cobrando el impuesto al comprador y asumiendo la responsabilidad de remitir ese monto a la autoridad fiscal del país de destino. Eso requiere que el cálculo sea preciso y que el flujo de conciliación fiscal esté estructurado en tus sistemas financieros.
En México, las exportaciones requieren CFDI de exportación y el proceso de despacho mediante el Módulo de Ventanilla Digital del SAT. La API de landed cost calcula el costo en el destino, pero los documentos de salida de México siguen las reglas del SAT. Asegúrate de que los sistemas de gestión de pedidos y de documentación fiscal estén sincronizados con los datos del cálculo.
Para operaciones hacia EUA, la correcta declaración de reglas de origen bajo el T-MEC puede significar la diferencia entre un derecho de 0% y una alícuota general de hasta 25% en algunas categorías. La API debe poder transmitir esa información a la documentación de entrada en EUA.
Errores comunes en la integración y cómo evitarlos
El primer error más común es usar el código HS genérico de la categoría en lugar del código específico del producto. Un suéter de algodón y uno de lana tienen códigos HS diferentes y alícuotas distintas. Usar el código incorrecto genera un cálculo impreciso y puede crear una discrepancia en la declaración aduanal.
El segundo error es no actualizar el caché de tarifas cuando hay cambios regulatorios. Los aranceles cambian, los tratados comerciales entran en vigor y los umbrales de exención se ajustan. Un caché estático con TTL largo puede servir datos desactualizados durante semanas sin que el equipo lo note.
El tercer error es tratar el resultado de la API como dato informativo en lugar de dato operacional. Si el sistema de gestión de pedidos no consume el resultado de la API de landed cost para alimentar la documentación aduanal, creaste una experiencia de checkout correcta y una operación de despacho incorrecta.
El cuarto error es no probar el comportamiento del checkout cuando la API no está disponible. Define el comportamiento de fallback en staging y valida que funcione como se espera antes de lanzar a producción.
Cómo elegir la API correcta para tu operación
Evalúa las APIs disponibles en cinco dimensiones: cobertura de los corredores y mercados relevantes para tu operación, precisión del cálculo probada con datos reales de tus SKUs, latencia promedio y SLA documentado, soporte al modelo DDP con transferencia de datos para documentación aduanal, y compatibilidad de integración con tu stack de e-commerce, ya sea Shopify, VTEX, plataforma headless o ERP personalizado.
Solicita un entorno sandbox con datos reales antes de firmar cualquier contrato. Prueba con los SKUs que realmente vendes, para los corredores que realmente atiendes, y compara el resultado con los aranceles publicados en las tablas oficiales de cada país de destino.
Para marcas mexicanas con foco en EUA y Europa, la API debe cubrir el Sales Tax americano por estado, el VAT europeo por país miembro de la Unión Europea, las preferencias T-MEC para productos con origen calificado, y el manejo correcto de categorías con IEPS en el mercado doméstico.
ShipSmart ofrece una API de landed cost con cobertura para los principales corredores de exportación mexicanos, integración nativa con VTEX y Shopify, y cálculo en tiempo real que alimenta automáticamente la documentación aduanal de cada pedido.
Habla con un especialista de ShipSmart y ve la API en funcionamiento con tus SKUs
