<!-- Generated from https://developers.superfrete.com/openapi.yaml (operationId: calculateShipping). -->

# Cotar frete

> `POST /api/v0/calculator` · Referência interativa: https://developers.superfrete.com/referencia#calculateShipping

- **Method:** `POST`
- **Path:** `/api/v0/calculator`
- **Operation ID:** `calculateShipping`
- **Tags:** Frete

Calcula preço e prazo de entrega a partir do CEP de origem, do CEP de destino e da caixa ou dos produtos. A resposta traz uma opção por serviço disponível, ordenada pelo código do serviço.

## Caixa pronta ou lista de produtos

Descreva a encomenda de um destes dois jeitos:

- **`package`**: dimensões (cm) e peso (kg) da caixa, quando você já sabe quais são.
- **`products`**: dimensões, peso e quantidade de cada produto. A API calcula uma caixa que acomode todos e devolve essa caixa em `packages`.

Se você enviar os dois, `package` tem prioridade.

> **Use a caixa devolvida pela cotação**
>
> Ao cotar por `products`, envie a caixa calculada pela API em `volumes` quando for [criar a etiqueta](https://developers.superfrete.com/referencia/md/createShipment.md), e não as dimensões dos produtos. Exemplo: dois produtos de 2 kg com 2 × 16 × 20 cm geram uma caixa de 4 kg com 6 × 16 × 24 cm. São esses os valores da etiqueta.

## Serviços

Informe em `services` os códigos separados por vírgula: `1` PAC, `2` SEDEX, `17` Mini Envios, `3` Jadlog, `31` Loggi e `33` J\&T. Exemplo: `"1,2,17,3,31"`.

Um serviço só é cotado quando o código está em `services` **e** está ligado nas configurações do token, em [Integrações](https://web.superfrete.com/#/integrations). Os Correios, a Jadlog e a Loggi vêm ligados; a J\&T vem desligada e precisa ser ativada para a conta. Jadlog, Loggi e J\&T só aparecem quando há um ponto de postagem da transportadora perto do CEP de origem.

## Serviços adicionais e seguro

`own_hand` (mão própria) e `receipt` (aviso de recebimento) valem para os Correios. O seguro usa `insurance_value` quando `use_insurance_value` é `true`; se `use_insurance_value` não for enviado, basta `insurance_value` maior que zero. As configurações do token podem ligar esses serviços para todas as cotações.

## Limites por transportadora

| Transportadora | Medidas máximas                            | Peso máximo                                     |
| -------------- | ------------------------------------------ | ----------------------------------------------- |
| Loggi          | 100 cm por lado, soma dos lados até 200 cm | 30 kg com Loggi Pontos, 11 kg sem               |
| Jadlog         | 80 × 80 × 80 cm                            | 120 kg nas franquias, 30 kg nas lojas parceiras |
| J\&T           | 100 cm por lado, soma dos lados até 200 cm | 11 kg                                           |

Os limites dos Correios (PAC, SEDEX e Mini Envios) vêm de [Consultar regras dos serviços](https://developers.superfrete.com/referencia/md/getServicesInfo.md). O passo a passo completo, da cotação à impressão, está no [guia de frete](https://developers.superfrete.com/guias/frete).

## Effective servers

- `https://sandbox.superfrete.com`

  Sandbox (testes, etiquetas sem validade)
- `https://api.superfrete.com`

  Produção

## Authentication

- **bearerAuth**: HTTP bearer (`JWT`)

  Token de acesso da SuperFrete, no header `Authorization: Bearer {token}`.
  - **Integração da própria loja:** gere o token no painel, em **Integrações** ([produção](https://web.superfrete.com/#/integrations) ou [sandbox](https://sandbox.superfrete.com/#/integrations)).
  - **Plataforma que conecta várias contas:** obtenha um token por seller com o fluxo OAuth 2.0 ([`exchangeOAuthToken`](https://developers.superfrete.com/referencia/md/exchangeOAuthToken.md)).

  O token não expira e dá acesso a todas as rotas da API para a conta; não há escopos. Ele deixa de valer quando a integração é removida no painel. O token de sandbox só funciona no sandbox, e o de produção só em produção.

## Header parameters

- **`User-Agent` (required)**: `string`

  Nome da sua aplicação com um e-mail de contato técnico, no formato `Aplicação (email@exemplo.com)`. Hoje só [Listar pedidos](https://developers.superfrete.com/referencia/md/listOrders.md) recusa um valor fora desse formato, mas envie em todas as rotas.

  **Example:**

  ```json
  "MinhaLoja (dev@minhaloja.com.br)"
  ```

## Request body

**Required:** `true`

**Content type:** `application/json`

**Any of:**

- `object`
- `object`

* **`from` (required)**: `object`

  Origem.
  - **`postal_code` (required)**: `string`

    CEP com 8 dígitos. Pontos e traços são removidos.
* **`services` (required)**: `string | (array of string)`

  Códigos dos serviços a cotar, separados por vírgula. `1` PAC · `2` SEDEX · `17` Mini Envios · `3` Jadlog · `31` Loggi · `33` J\&T. Também aceita um array de códigos.
* **`to` (required)**: `object`

  Destino.
  - **`postal_code` (required)**: `string`

    CEP com 8 dígitos. Pontos e traços são removidos.
* **`options`**: `object`

  Serviços adicionais.
  - **`insurance_value`**: `number`

    Valor da mercadoria, em reais, para o seguro.
  - **`own_hand`**: `boolean`, default: `false`

    Mão própria (Correios).
  - **`receipt`**: `boolean`, default: `false`

    Aviso de recebimento (Correios).
  - **`use_insurance_value`**: `boolean`

    Contrata o seguro com `insurance_value`. Sem este campo, o seguro é contratado sempre que `insurance_value` for maior que zero.
* **`package`**: `object`, schema: `PackageDimensions`

  Dimensões da caixa já conhecida. Tem prioridade sobre `products`.
  - **`height` (required)**: `number`

    Altura, em cm.
  - **`length` (required)**: `number`

    Comprimento, em cm.
  - **`weight` (required)**: `number`

    Peso, em kg.
  - **`width` (required)**: `number`

    Largura, em cm.
* **`products`**: `array`

  Produtos da encomenda. A API calcula uma caixa que acomode todos.

  **Items:**
  - **`height` (required)**: `number`

    Altura, em cm.
  - **`length` (required)**: `number`

    Comprimento, em cm.
  - **`quantity` (required)**: `integer`, minimum: `1`
  - **`weight` (required)**: `number`

    Peso, em kg.
  - **`width` (required)**: `number`

    Largura, em cm.

**Example: byPackage**

Cotação com as dimensões da caixa

```json
{
  "from": {
    "postal_code": "01153000"
  },
  "to": {
    "postal_code": "20020050"
  },
  "services": "1,2,17",
  "options": {
    "own_hand": false,
    "receipt": false,
    "insurance_value": 0,
    "use_insurance_value": false
  },
  "package": {
    "height": 2,
    "width": 11,
    "length": 16,
    "weight": 0.3
  }
}
```

**Example: byProducts**

Cotação a partir dos produtos

```json
{
  "from": {
    "postal_code": "01153000"
  },
  "to": {
    "postal_code": "20020050"
  },
  "services": "1,2,17,3,31",
  "options": {
    "own_hand": false,
    "receipt": false,
    "insurance_value": 150,
    "use_insurance_value": true
  },
  "products": [
    {
      "quantity": 2,
      "height": 2,
      "width": 16,
      "length": 20,
      "weight": 2
    }
  ]
}
```

## Responses

### 200 Uma opção por serviço. Quando um serviço não pode ser usado nessa encomenda (por exemplo, seguro acima do limite), ele volta com o campo `error` e sem preço.

**Content type:** `application/json`

**Array of:**

**One of:**

- `object`, schema: `ShippingQuote`

  Opção de frete cotada.
  - **`company` (required)**: `object`, schema: `QuoteCompany`

    Transportadora.
    - **`id`**: `integer`

      `1` Correios · `2` Jadlog · `14` Loggi.
    - **`name`**: `string`
    - **`picture`**: `string`

      URL do logotipo. Pode vir vazia.
  - **`id` (required)**: `integer`, possible values: `1, 2, 3, 17, 31, 33`

    `1` PAC · `2` SEDEX · `17` Mini Envios · `3` Jadlog · `31` Loggi · `33` J\&T.
  - **`name` (required)**: `string`

    Nome do serviço, como `PAC`, `SEDEX`, `Mini Envios` ou o nome do serviço da transportadora.
  - **`price` (required)**: `number`

    Preço com o desconto SuperFrete, em reais.
  - **`additional_services`**: `object`
    - **`own_hand`**: `boolean`
    - **`receipt`**: `boolean`
  - **`currency`**: `string`, possible values: `"R$"`
  - **`delivery_range`**: `object`

    Prazo mínimo e máximo, em dias úteis.
    - **`max`**: `integer`
    - **`min`**: `integer`
  - **`delivery_time`**: `integer`

    Prazo de entrega, em dias úteis.
  - **`discount`**: `string`

    Desconto em relação ao preço de balcão, em reais, como texto.
  - **`has_error`**: `boolean`, const: `false`
  - **`packages`**: `array`

    Caixa considerada na cotação. Use estes valores em `volumes` ao criar a etiqueta.

    **Items:**
    - **`dimensions`**: `object`

      Medidas em cm, como texto.
      - **`height`**: `string`
      - **`length`**: `string`
      - **`width`**: `string`
    - **`discount`**: `string`
    - **`format`**: `string`

      Formato da embalagem.
    - **`insurance_value`**: `number`

      Valor segurado considerado, em reais.
    - **`price`**: `number`
    - **`weight`**: `string`

      Peso em kg, como texto.
- `object`, schema: `ShippingQuoteError`

  Serviço que não pode ser usado nesta encomenda. Traz o motivo em `error` e não tem preço.
  - **`error` (required)**: `string`

    Motivo, pronto para exibir.
  - **`id` (required)**: `integer`, possible values: `1, 2, 3, 17, 31, 33`

    `1` PAC · `2` SEDEX · `17` Mini Envios · `3` Jadlog · `31` Loggi · `33` J\&T.
  - **`name` (required)**: `string`
  - **`company`**: `object`, schema: `QuoteCompany`

    Transportadora.

    *Schema `QuoteCompany` is shown above.*

**Example:**

```json
[
  {
    "id": 1,
    "name": "PAC",
    "price": 18.61,
    "discount": "5.59",
    "currency": "R$",
    "delivery_time": 5,
    "delivery_range": {
      "min": 5,
      "max": 5
    },
    "packages": [
      {
        "price": 18.61,
        "discount": "5.59",
        "format": "box",
        "dimensions": {
          "height": "2",
          "width": "11",
          "length": "16"
        },
        "weight": "0.3",
        "insurance_value": 0
      }
    ],
    "additional_services": {
      "receipt": false,
      "own_hand": false
    },
    "company": {
      "id": 1,
      "name": "Correios",
      "picture": "https://storage.googleapis.com/sandbox-api-superfrete.appspot.com/logos/correios.png"
    },
    "has_error": false
  },
  {
    "id": 2,
    "name": "SEDEX",
    "price": 10.77,
    "discount": "13.43",
    "currency": "R$",
    "delivery_time": 1,
    "delivery_range": {
      "min": 1,
      "max": 1
    },
    "packages": [
      {
        "price": 10.77,
        "discount": "13.43",
        "format": "box",
        "dimensions": {
          "height": "2",
          "width": "11",
          "length": "16"
        },
        "weight": "0.3",
        "insurance_value": 0
      }
    ],
    "additional_services": {
      "receipt": false,
      "own_hand": false
    },
    "company": {
      "id": 1,
      "name": "Correios",
      "picture": "https://storage.googleapis.com/sandbox-api-superfrete.appspot.com/logos/correios.png"
    },
    "has_error": false
  },
  {
    "id": 3,
    "name": "JADLOG.PACKAGE",
    "price": 14.4,
    "discount": "7.2",
    "currency": "R$",
    "delivery_time": 2,
    "delivery_range": {
      "min": 2,
      "max": 3
    },
    "packages": [
      {
        "price": 14.4,
        "discount": "7.2",
        "format": "box",
        "dimensions": {
          "height": "2",
          "width": "11",
          "length": "16"
        },
        "weight": "0.3",
        "insurance_value": 0
      }
    ],
    "additional_services": {
      "receipt": false,
      "own_hand": false
    },
    "company": {
      "id": 2,
      "name": "jadlog",
      "picture": ""
    },
    "has_error": false
  },
  {
    "id": 31,
    "name": "LOGGI Econômico",
    "error": "Valor segurado ultrapassa o limite máximo de R$ 3000,00",
    "company": {
      "id": 14,
      "name": "loggi",
      "picture": ""
    }
  }
]
```

### 400 Requisição inválida ou nenhum serviço disponível para a encomenda. Quando nenhum serviço pôde ser cotado, a chave do erro é `freight.calculator.no_result`; quando a caixa passa dos limites das transportadoras parceiras, é `package_dimensions_sum_or_weight`.

**Content type:** `application/json`

schema: `ValidationError`

Um ou mais campos da requisição são inválidos.

- **`errors` (required)**: `object`

  Mapa do campo (ex.: `to.postal_code`) para a lista de mensagens de erro desse campo.

  **Additional properties:**

  `array of string`
- **`message` (required)**: `string`

  Sempre `Ocorreu um ou mais erros.`

**Example: noResult**

Nenhum serviço disponível

```json
{
  "message": "Ocorreu um ou mais erros.",
  "errors": {
    "freight.calculator.no_result": [
      "Nenhum frete válido encontrado para esse serviço."
    ]
  }
}
```

**Example: missingField**

Campo obrigatório ausente

```json
{
  "message": "Ocorreu um ou mais erros.",
  "errors": {
    "to.postal_code": [
      "(to.postal_code) é obrigatório."
    ]
  }
}
```

### 401 Token ausente, inválido, removido ou de outro ambiente.

**Content type:** `application/json`

schema: `Error`

Erro de regra de negócio ou de autenticação. `message` e `error` trazem o mesmo texto.

- **`error` (required)**: `string`

  Mesmo conteúdo de `message`, mantido por compatibilidade.
- **`message` (required)**: `string`

  Mensagem legível do erro.

**Example:**

```json
{
  "message": "Token inválida!",
  "error": "Token inválida!"
}
```

### 500 Erro interno. O corpo pode ser um objeto de erro ou só um texto JSON com a mensagem.

**Content type:** `application/json`

**One of:**

- *Schema `Error` is shown above.*
- `string`

**Example:**

```json
{
  "message": "",
  "error": ""
}
```

## Schemas

- `Error` — shown above.
- `ValidationError` — shown above.

### PostalCode

**Type:** `string`

CEP com 8 dígitos. Pontos e traços são removidos.

**Example:**

```json
"01153000"
```

- `PackageDimensions` — shown above.

  Caixa da encomenda.

### ServiceId

**Type:** `integer`, possible values: `1, 2, 3, 17, 31, 33`

`1` PAC · `2` SEDEX · `17` Mini Envios · `3` Jadlog · `31` Loggi · `33` J\&T.

- `ShippingQuote` — shown above.
- `ShippingQuoteError` — shown above.
- `QuoteCompany` — shown above.