> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yampi.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Visão geral

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:

```json theme={"system"}
{
  "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:

```json theme={"system"}
{
  "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:

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

```js theme={"system"}
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.