Com este recurso é possível conectar APIs externas de cálculo de frete para serviços que não são integrados nativamente na Yampi.


Como habilitar

Para habilitar este recurso, o lojista deve criar uma nova API de frete pelo painel da Yampi:

  1. Acesse o menu: Configurações > Logística > API de Frete

  2. Clique em Criar nova API de Frete

  3. Preencha os campos obrigatórios:

    • Nome da API
    • URL da API
    • Headers (opcional)

Requisição enviada pela Yampi

Quando um comprador solicitar o cálculo de frete, a Yampi enviará uma requisição POST para a URL cadastrada com o seguinte corpo:

{
  "zipcode": "14940472",
  "amount": 120.00,
  "cart": {
    "promocode": null,
    "customer": {
      "document": "00000000000",
      "email": "foo@bar.com.br"
    }
  },
  "skus": [
    {
      "id": 1231233,
      "product_id": 12313,
      "sku": "716237816313213",
      "price": 12.00,
      "quantity": 2,
      "length": 1,
      "width": 1,
      "height": 1,
      "weight": 1,
      "availability_days": 1,
      "platform": {
        "name": "shopify",
        "external_id": 1231231231313
      }
    }
  ]
}

Campos e descrições

CampoDescrição
zipcodeCEP de entrega
amountValor total do carrinho
skus[].idID do SKU na Yampi
skus[].product_idID do Produto na Yampi
skus[].skuCódigo do SKU
skus[].pricePreço unitário do item
skus[].quantityQuantidade de itens
skus[].lengthComprimento unitário do SKU
skus[].widthLargura unitária do SKU
skus[].heightAltura unitária do SKU
skus[].weightPeso unitário do SKU (em KG)
skus[].availability_daysPrazo de postagem (em dias)
skus[].platform.nameNome da plataforma externa
skus[].platform.external_idID do SKU na plataforma externa
cart.promocodeCupom de desconto (opcional)
cart.customer.documentCPF ou CNPJ do cliente
cart.customer.emailE-mail do cliente

Resposta esperada

Sua API deverá obrigatoriamente responder no formato abaixo:

{
  "quotes": [
    {
      "name": "OPÇÃO FRETE 1",
      "service": "SEDEX",
      "price": 37.5,
      "days": 36,
      "quote_id": 1
    },
    {
      "name": "OPÇÃO FRETE 2",
      "service": "PAC",
      "price": 37.5,
      "days": 36,
      "quote_id": 2
    }
  ]
}

⚠️ Sua aplicação deve responder em até 4 segundos. Caso contrário, a Yampi abortará a requisição.


Segurança nas requisições

Para garantir que a requisição partiu da Yampi, é necessário validar a assinatura enviada no header.

Como validar:

  1. Pegue o valor do header X-Yampi-Hmac-SHA256
  2. Gere a assinatura localmente usando HMAC-SHA256 do corpo da requisição com a chave secreta da API de frete
  3. Codifique em base64
  4. Compare o resultado com o valor recebido no header
const crypto = require('crypto')
const secret = 'SUA_CHAVE_SECRETA'
const body = JSON.stringify(request.body)
const signature = crypto
  .createHmac('sha256', secret)
  .update(body)
  .digest('base64')

Se a assinatura for igual ao valor do header, ✅ requisição é legítima.


Conclusão

Com essa integração, você pode oferecer opções de frete personalizadas no checkout da Yampi, mantendo controle sobre prazos, preços e validação de segurança.