Quando um comprador chega à tela de pagamento de uma loja D2C e vê um preço que não inclui o custo real de importação, ele fecha a aba. Segundo o Baymard Institute, 48% dos abandonos em compras internacionais acontecem por custos inesperados no checkout. A solução técnica para esse problema tem nome: integração de API de landed cost.

Este guia é para times de e-commerce e squads técnicas que precisam integrar cálculo de frete e impostos internacionais em tempo real no checkout. Vamos cobrir os dados necessários, a arquitetura de integração, os requisitos de performance e os pontos de conformidade que determinam se o cálculo vai estar correto ou vai gerar passivo fiscal.

O que é uma API de landed cost e o que ela calcula

Uma API de landed cost recebe os dados do pedido e retorna o custo total entregue ao comprador, incluindo frete internacional, duties de importação, impostos locais e taxas alfandegárias relevantes para aquele destino específico.

O que ela não faz é adivinhar. A precisão do resultado depende diretamente da qualidade dos dados que você envia. Um código HS incorreto ou ausente produz um cálculo errado. Um valor de produto mal declarado gera inconsistência na declaração aduaneira. Por isso, a integração começa antes do checkout: começa no setup do catálogo de produtos.

Para operações brasileiras exportando para os EUA e a Europa, os componentes do cálculo incluem tarifas alfandegárias baseadas no código HS e na origem declarada, Sales Tax americano por estado de destino, VAT europeu por país membro, e o custo de frete calculado com base no corredor, peso dimensional e nível de serviço selecionado.

Dados obrigatórios para o cálculo em tempo real

O payload mínimo que a API precisa receber por linha de item é o código HS ou NCM do produto, o valor do item em moeda base, o peso e as dimensões, o país de origem do produto e o endereço completo de destino incluindo CEP.

Dados adicionais que melhoram a precisão do cálculo: categoria de produto para aplicação correta de alíquotas, composição de material quando relevante para classificação, se o item contém bateria ou é produto regulado, e o modelo de importação que será usado, DDP ou DAP.

A ausência de qualquer dado obrigatório deve gerar um fallback explícito no frontend, não um cálculo impreciso. Mostrar um valor de frete estimado com ressalva visível é melhor do que mostrar um valor incorreto que vai gerar retenção alfandegária depois.

O NCM é o código brasileiro equivalente ao HS internacional. Ele tem oito dígitos e é obrigatório na documentação fiscal brasileira. Muitas APIs de landed cost aceitam tanto NCM quanto HS. Se a sua plataforma armazena NCM, confirme se a API que você está integrando aceita esse formato diretamente ou se precisa de conversão para HS de seis dígitos.

Arquitetura da integração no checkout

A integração de API de landed cost no checkout tem três padrões possíveis: chamada síncrona no carregamento do carrinho, chamada síncrona no evento de mudança de endereço, ou pré-cálculo assíncrono com cache por destino e SKU.

A chamada síncrona no carregamento do carrinho é a mais simples de implementar, mas tem o maior impacto no tempo de resposta da página. Se a API de landed cost tiver latência acima de 400ms, o usuário percebe a demora antes de ver o total.

A chamada no evento de mudança de endereço é o padrão mais comum em checkout D2C. O cálculo é disparado quando o comprador confirma o CEP ou o país de destino, e o resultado é exibido como linha separada no resumo do pedido antes da confirmação de pagamento. Essa abordagem equilibra precisão e performance.

O pré-cálculo assíncrono com cache é recomendado para operações com volume alto em destinos recorrentes. Você calcula o landed cost por combinação de SKU e país de destino em batch, armazena em cache com TTL de 24 a 48 horas e serve o resultado do cache no checkout sem chamada de API em tempo real. A desvantagem é que o cache precisa ser invalidado quando há mudança de tarifas ou de frete contratado.

Para integrações em Shopify, a API de landed cost se conecta ao checkout via Shopify Functions ou via extensão de Checkout UI. Em VTEX, a integração acontece via APIs de simulação de carrinho ou via customização do checkout responsivo. Em plataformas headless, o ponto de integração é a camada de orquestração que compõe o payload antes da renderização do checkout.

Requisitos de performance e SLA da API

A latência máxima aceitável para uma chamada de API no checkout é de 500ms no percentil 95. Acima disso, o impacto no abandono começa a ser mensurável. Uma pesquisa da Google sobre velocidade de páginas mobile indica que um atraso de 1 segundo na resposta reduz a conversão em até 20%.

Defina um timeout para a chamada de API de landed cost. Se a resposta não chegar dentro do timeout definido, o comportamento correto é exibir uma estimativa com ressalva ou bloquear a finalização do pedido com mensagem explicativa, não silenciar o erro e exibir zero de imposto.

Monitore separadamente a taxa de erro da API e a taxa de chamadas com fallback. Um aumento na taxa de fallback pode indicar que os dados do catálogo de produtos estão incompletos ou que a API está com degradação de performance.

Para operações com múltiplos destinos simultâneos, considere implementar chamadas paralelas para os corredores mais frequentes durante o onboarding do usuário, antes mesmo de ele chegar ao checkout, para ter o resultado em cache local no browser quando ele precisar.

Conformidade fiscal e declaração aduaneira

O cálculo de landed cost no checkout não é apenas uma experiência de usuário. É também o dado que vai alimentar a documentação aduaneira quando o pedido for despachado.

Por isso, o valor calculado pela API precisa corresponder ao valor que será declarado na fatura comercial. Se há discrepância entre o que o cliente pagou no checkout e o que foi declarado para a alfândega, o volume pode ser retido por inconsistência de valor.

Para operações em DDP, você está coletando o imposto do comprador e assumindo a responsabilidade de recolher esse valor para a autoridade fiscal do país de destino. Isso exige que o cálculo seja preciso e que o fluxo de reconciliação fiscal esteja estruturado no seu sistema financeiro.

No Brasil, exportações precisam de Nota Fiscal de exportação e o processo de desembaraço de exportação pelo Siscomex. A API de landed cost calcula o custo no destino, mas os documentos de saída do Brasil seguem as regras da Receita Federal. Certifique-se de que os sistemas de gestão de pedido e de documentação fiscal estejam sincronizados com os dados do cálculo.

Para o Programa Remessa Conforme, as plataformas participantes precisam declarar os dados do remetente, do destinatário, do produto e do valor de forma estruturada. A API de landed cost deve conseguir alimentar esse payload automaticamente a partir dos dados do pedido.

Erros comuns na integração e como evitá-los

O primeiro erro mais comum é usar o código HS genérico da categoria em vez do código específico do produto. Um suéter de algodão e um suéter de lã têm códigos HS diferentes e alíquotas diferentes. Usar o código errado gera cálculo impreciso e pode criar discrepância na declaração aduaneira.

O segundo erro é não atualizar o cache de tarifas quando há mudança regulatória. Tarifas alfandegárias mudam, acordos comerciais entram em vigor e limiares de isenção são ajustados. Um cache estático com TTL longo pode servir dados desatualizados por semanas sem que o time perceba.

O terceiro erro é tratar o resultado da API como dado informativo em vez de dado operacional. Se o sistema de gestão de pedidos não consome o resultado da API de landed cost para alimentar a documentação aduaneira, você criou uma experiência de checkout correta e uma operação de despacho incorreta.

O quarto erro é não testar o comportamento do checkout quando a API está indisponível. Defina o comportamento de fallback em homologação e valide que ele funciona conforme o esperado antes de colocar em produção.

Como escolher a API certa para sua operação

Avalie as APIs disponíveis em cinco dimensões: cobertura de mercados e corredores relevantes para a sua operação, precisão de cálculo com dados reais dos seus SKUs, latência média e SLA documentado, suporte a modelo DDP com passagem de dados para documentação aduaneira, e capacidade de integração com o seu stack de e-commerce, seja Shopify, VTEX, plataforma headless ou ERP customizado.

Solicite um ambiente de sandbox com dados reais antes de assinar qualquer contrato. Teste com os SKUs que você realmente vende, para os corredores que você realmente atende, e compare o resultado com a alíquota publicada nas tabelas oficiais de cada país de destino.

Para operações brasileiras com foco em EUA e Europa, a API precisa cobrir Sales Tax americano por estado, VAT europeu por país membro da União Europeia, e as regras do Programa Remessa Conforme para cálculo de ICMS e imposto de importação no Brasil como destino.

A ShipSmart oferece uma API de landed cost com cobertura para os principais corredores de exportação brasileiros, integração nativa com VTEX e Shopify, e cálculo em tempo real que alimenta automaticamente a documentação aduaneira de cada pedido.

Fale com um especialista ShipSmart e veja a API em funcionamento com os seus SKUs