Logística em marketplace: integrando transportadoras

Logística é onde a maioria dos marketplaces perde a batalha da experiência do cliente. O produto foi ótimo, o pagamento foi tranquilo, mas o frete demorou o dobro do prometido, o código de rastreamento não funcionou e a devolução virou um pesadelo de e-mails sem resposta. Isso não é culpa exclusiva da transportadora — é resultado de uma integração mal feita, com SLAs mal definidos e processos de exceção inexistentes.

A boa notícia é que o ecossistema logístico brasileiro evoluiu muito nos últimos anos. Hoje existem agregadores de frete maduros, APIs de rastreamento confiáveis e soluções de logística reversa que podem ser integradas em semanas. O segredo está em entender as camadas do problema antes de escolher as ferramentas.

Melhor Envio e Frenet: Cotação Multi-carrier

Integrar cada transportadora individualmente é uma decisão que vai custar caro em manutenção. Cada carrier tem sua própria API com quirks, mudanças de schema sem aviso e limites de rate diferente. Para a maioria dos marketplaces, a solução correta é usar um agregador de frete que abstrai essas diferenças.

Melhor Envio é o agregador mais popular no Brasil para PMEs e marketplaces em crescimento. Conecta Correios, Jadlog, J&T Express, Loggi, Total Express e outras. A cotação retorna múltiplas opções ordenadas por preço e prazo, e o vendedor (ou a plataforma) escolhe qual usar.

// Cotação de frete via Melhor Envio API v2
async function cotarFrete(params: FreteParams): Promise<FreteOption[]> {
  const response = await fetch('https://melhorenvio.com.br/api/v2/me/shipment/calculate', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.MELHOR_ENVIO_TOKEN}`,
      'Content-Type': 'application/json',
      Accept: 'application/json',
    },
    body: JSON.stringify({
      from: { postal_code: params.originCep },
      to: { postal_code: params.destinationCep },
      package: {
        height: params.heightCm,
        width: params.widthCm,
        length: params.lengthCm,
        weight: params.weightKg,
      },
      options: {
        receipt: false,
        own_hand: false,
      },
      services: '1,2,3,4,7,8', // PAC, SEDEX, Jadlog, etc
    }),
  });

  const data = await response.json();

  // Filtrar opções com erro e retornar as válidas
  return data
    .filter((option: any) => !option.error)
    .map((option: any) => ({
      carrierId: option.id,
      carrierName: option.company.name,
      serviceName: option.name,
      priceCents: Math.round(option.price * 100),
      deliveryDays: option.delivery_time,
      logo: option.company.picture,
    }))
    .sort((a: FreteOption, b: FreteOption) => a.priceCents - b.priceCents);
}

Frenet é uma alternativa ao Melhor Envio com foco em integrações diretas com plataformas de e-commerce (Vtex, Magento, WooCommerce). Para marketplaces custom, o Melhor Envio costuma ser mais fácil de integrar.

A escolha entre os dois depende principalmente do volume: Melhor Envio tem tabelas competitivas para volumes menores; para volumes acima de R$ 50 mil/mês em fretes, vale negociar diretamente com as carriers via Frenet ou contrato direto.

Correios API: Setup e Limitações

Os Correios são inevitáveis no Brasil. Para muitas regiões, especialmente cidades menores e interior, são a única opção de entrega. A API dos Correios, no entanto, tem particularidades que frustram muitos times.

Limitações que você vai encontrar:

Autenticação por contrato: para usar a API de cotação com preços de tabela padrão, não é necessário contrato. Para preços corporativos (mais baixos), é necessário ter contrato com os Correios e usar credenciais específicas.

Rate limiting agressivo: a API dos Correios tem limite de requisições que varia por contrato. Sem contrato, o limite é muito baixo para uso em produção. Cacheie as cotações sempre que possível.

Instabilidade histórica: a API dos Correios tem um histórico de instabilidade maior do que as carriers privadas. Implemente retry com backoff exponencial e fallback para Melhor Envio quando a API dos Correios falhar.

PAC e SEDEX são os únicos serviços amplamente disponíveis via API. Serviços como SEDEX 10, SEDEX Hoje e Carta Registrada têm disponibilidade limitada ou requerem contrato específico.

Para a maioria dos marketplaces, a melhor prática é acessar os Correios via Melhor Envio (que já tem contratos negociados) em vez de integrar diretamente.

Rastreamento Unificado: Webhook por Transportadora

O rastreamento é onde a experiência do cliente mais sofre em integrações de logística mal feitas. Cada transportadora tem seu próprio formato de status, seus próprios webhooks (quando oferecem) e seus próprios atrasos de atualização.

A solução é uma camada de abstração que normaliza os status de todas as carriers em um modelo único:

Status interno	Descrição	Status Correios	Status Jadlog
label_created	Etiqueta gerada	BDI	Coletado
in_transit	Em trânsito	BDE/BDI	Em Rota
out_for_delivery	Saiu para entrega	BDE (OEC)	Saiu para Entrega
delivered	Entregue	BDE (Entregue)	Entregue
failed_delivery	Tentativa falha	BDE (Ausente)	Endereço não Localizado
returned	Devolvido ao remetente	BDR	Devolvido

// Normalização de status por transportadora
function normalizeTrackingStatus(
  carrier: string,
  rawStatus: string
): TrackingStatus {
  const statusMaps: Record<string, Record<string, TrackingStatus>> = {
    correios: {
      'BDI': 'label_created',
      'OEC': 'out_for_delivery',
      'BDE': 'delivered',  // precisa verificar sub-status
    },
    jadlog: {
      'Coletado': 'label_created',
      'Em Rota': 'in_transit',
      'Saiu para Entrega': 'out_for_delivery',
      'Entregue': 'delivered',
    },
    // ... outras carriers
  };

  return statusMaps[carrier]?.[rawStatus] ?? 'unknown';
}

Para carriers que não oferecem webhooks (os Correios são o exemplo mais relevante), implemente polling periódico com frequência proporcional à urgência esperada: a cada 4 horas para pedidos em processamento, a cada hora para pedidos "saiu para entrega".

Devoluções e Reverse Logistics: o Processo Esquecido

A logística reversa é a parte mais negligenciada na maioria dos projetos de marketplace. Times focam 90% da energia no fluxo de ida (venda → entrega) e tratam as devoluções como um processo manual que "resolve depois".

O resultado é previsível: quando o volume cresce, o time de operações fica soterrado em devoluções sem processo, clientes ficam sem resposta e o índice de disputas explode.

Um processo mínimo viável de devolução tem quatro etapas:

Solicitação: o comprador abre uma solicitação de devolução dentro de um prazo (ex: 7 dias após entrega para arrependimento, 30 dias para defeito). A plataforma coleta o motivo, fotos do produto se aplicável e confirma que a solicitação é válida (dentro do prazo, produto elegível).

Aprovação: o vendedor (ou a plataforma, dependendo do motivo) aprova ou contesta. Para arrependimento dentro do prazo legal de 7 dias, a aprovação é automática — a lei do consumidor não dá escolha. Para defeito, pode haver análise.

Coleta: geração automática de etiqueta de devolução. O Melhor Envio oferece API para criação de etiquetas de logística reversa. O comprador recebe o código da etiqueta por e-mail e pode postar nos pontos de coleta da carrier.

Reembolso: após confirmação de recebimento do produto pelo vendedor (ou após prazo para contestação), o reembolso é processado automaticamente. Isso deve ser automatizado — processar reembolsos manualmente é inescalável.

O SLA de cada etapa deve ser comunicado ao comprador no momento da abertura da solicitação: "Sua solicitação será analisada em até 24 horas. Após aprovação, você receberá a etiqueta de devolução em até 2 horas. O reembolso será processado em até 5 dias úteis após o recebimento do produto."

Conclusão com CTA

Logística bem implementada é uma vantagem competitiva que a maioria dos marketplaces subestima. Compradores que tiveram uma boa experiência de entrega — rastreamento claro, prazo cumprido, devolução sem burocracia — voltam. Os que tiveram uma experiência ruim não voltam e contam para outros.

Integrar transportadoras corretamente exige decisões de arquitetura que afetam o modelo de dados, os fluxos de notificação, a estrutura de custos e a experiência do vendedor. Essas decisões são muito mais fáceis de tomar antes do desenvolvimento do que de corrigir depois.

O SystemForge documenta todos esses fluxos de forma estruturada — desde o modelo de dados de shipments até os webhooks de rastreamento e os fluxos de devolução — criando a base técnica que o time de desenvolvimento precisa para construir a integração logística corretamente na primeira tentativa.