Visão geral - Yampi Developer Portal

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:

Acesse o menu: Configurações > Logística > API de Frete
Clique em Criar nova API de Frete
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,
      "unit_price": 6.00,
      "quantity": 2,
      "length": 1,
      "width": 1,
      "height": 1,
      "weight": 1,
      "availability_days": 1,
      "platform": {
        "name": "shopify",
        "external_id": "1231231231313"
      }
    }
  ]
}

Campos da requisção

Campo	Descrição
`zipcode`	CEP de entrega
`amount`	Valor total do carrinho
`skus[].id`	ID do SKU na Yampi
`skus[].product_id`	ID do Produto na Yampi
`skus[].sku`	Código do SKU
`skus[].price`	Preço do SKU multiplicado pela quantidade
`skus[].unit_price`	Preço unitário do SKU.
`skus[].quantity`	Quantidade de itens
`skus[].length`	Comprimento unitário do SKU
`skus[].width`	Largura unitária do SKU
`skus[].height`	Altura unitária do SKU
`skus[].weight`	Peso unitário do SKU (em KG)
`skus[].availability_days`	Prazo de postagem (em dias)
`skus[].platform.name`	Nome da plataforma externa
`skus[].platform.external_id`	ID do SKU na plataforma externa
`cart.promocode`	Cupom de desconto (opcional)
`cart.customer.document`	CPF ou CNPJ do cliente
`cart.customer.email`	E-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,
      "free_shipment": false
    },
    {
      "name": "OPÇÃO FRETE 2",
      "service": "PAC",
      "price": 37.5,
      "days": 36,
      "quote_id": 2,
      "free_shipment": true
    }
  ]
}

Campos da resposta

Campo	Descrição
`name`	Nome da opção de frete apresentada ao cliente.
`service`	Serviço de entrega (Alias de frete) utilizado (exemplo: PAC, SEDEX, LOGGI, etc.).
`price`	Valor do frete em reais.
`days`	Prazo estimado de entrega em dias.
`quote_id`	Identificador único da cotação gerada para essa opção de frete.
`free_shipment`	Indica se o frete é grátis (`true`) ou não será grátis (`false`).

⚠️ 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:

Pegue o valor do header X-Yampi-Hmac-SHA256
Gere a assinatura localmente usando HMAC-SHA256 do corpo da requisição com a chave secreta da API de frete
Codifique em base64
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.

​Como habilitar

​Requisição enviada pela Yampi

​Campos da requisção

​Resposta esperada

​Campos da resposta

​Segurança nas requisições

​Como validar:

​Conclusão