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

# Criar etiqueta (pedido)

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

- **Method:** `POST`
- **Path:** `/api/v0/cart`
- **Operation ID:** `createShipment`
- **Tags:** Etiquetas

Cria uma etiqueta com o status `pending` (aguardando pagamento). O preço é recalculado na hora com os dados enviados.

Depois de criar, pague a etiqueta de um destes jeitos:

- [Pela API](https://developers.superfrete.com/referencia/md/checkoutShipment.md), com o saldo da carteira SuperFrete.
- [Pelo painel](https://web.superfrete.com/#/minhas-etiquetas), com cartão de crédito ou saldo.

## Remetente e destinatário

- `name` precisa ter nome e sobrenome e é cortado em 32 caracteres. Se o nome da loja tiver uma palavra só, envie algo como `Loja SuperFrete`. Se o token tiver um nome de remetente configurado no painel, ele substitui `from.name`.
- `postal_code` é o CEP com 8 dígitos, como texto. Pontos e traços são removidos.
- `state_abbr` é a UF em maiúsculas, por exemplo `SP`.
- `number` aceita até 10 caracteres; vazio vira `S/N`. `complement` é cortado em 20 caracteres.
- `from.document` e `from.phone` são opcionais: sem eles, usamos o CPF/CNPJ e o telefone da conta. A conta precisa ter telefone cadastrado.
- `to.document` (CPF ou CNPJ válido) é obrigatório para Jadlog, Loggi e J\&T, e para os Correios sempre que houver declaração de conteúdo (`products`).
- `to.phone` precisa ter 10 ou 11 dígitos. Na J\&T, se ele não vier, usamos o telefone do remetente.
- Na Loggi, o remetente precisa de e-mail: envie `from.email` ou cadastre um e-mail na conta.

## Declaração de conteúdo ou nota fiscal

- **Declaração de conteúdo:** envie `products`, com `name`, `quantity` e `unitary_value` em cada item.
- **Nota fiscal:** envie `options.invoice` com a chave de acesso. Nota fiscal vale para os Correios; para as outras transportadoras, só quando liberada para a conta.

## Caixa

Envie em `volumes` a caixa devolvida pela [cotação](https://developers.superfrete.com/referencia/md/calculateShipping.md): altura, largura e comprimento em cm e peso em kg.

## Status da etiqueta

`pending` (aguardando pagamento) · `released` (paga, aguardando postagem) · `posted` (postada) · `delivered` (entregue) · `canceled` (cancelada).

> **Código de rastreio**
>
> O rastreio só existe depois do pagamento. Consulte o campo `tracking` em [Consultar pedido](https://developers.superfrete.com/referencia/md/getOrder.md) ou assine o evento `order.generated` nos [webhooks](https://developers.superfrete.com/referencia/md/orderEvent.md).

## 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`

- **`from` (required)**: `object`, schema: `ShipmentSender`

  Remetente.
  - **`address` (required)**: `string`, maxLength: `50`

    Logradouro.
  - **`city` (required)**: `string`, maxLength: `50`
  - **`district` (required)**: `string`, maxLength: `60`

    Bairro.
  - **`name` (required)**: `string`

    Nome e sobrenome. Cortado em 32 caracteres.
  - **`postal_code` (required)**: `string`

    CEP com 8 dígitos. Pontos e traços são removidos.
  - **`state_abbr` (required)**: `string`, pattern: `^[A-Z]{2}$`

    UF em maiúsculas.
  - **`complement`**: `string | null`

    Complemento. Cortado em 20 caracteres.
  - **`document`**: `string | null`

    CPF ou CNPJ. Sem ele, usamos o documento da conta.
  - **`email`**: `string`

    E-mail do remetente. Usado na Loggi; sem ele, usamos o e-mail da conta.
  - **`number`**: `string | null`, maxLength: `10`

    Número. Vazio vira `S/N`.
  - **`phone`**: `string | null`

    Telefone. Sem ele, usamos o telefone da conta.
- **`service` (required)**: `integer`, possible values: `1, 2, 3, 17, 31, 33`

  Serviço escolhido na cotação. O `33` (J\&T) só é aceito quando a J\&T está liberada para a conta.
- **`to` (required)**: `object`, schema: `ShipmentRecipient`

  Destinatário.
  - **`address` (required)**: `string`, maxLength: `50`

    Logradouro.
  - **`city` (required)**: `string`, maxLength: `50`
  - **`district` (required)**: `string`, maxLength: `50`

    Bairro.
  - **`name` (required)**: `string`

    Nome e sobrenome. Cortado em 32 caracteres.
  - **`postal_code` (required)**: `string`

    CEP com 8 dígitos. Pontos e traços são removidos.
  - **`state_abbr` (required)**: `string`, pattern: `^[A-Z]{2}$`

    UF em maiúsculas.
  - **`complement`**: `string | null`

    Complemento. Cortado em 20 caracteres.
  - **`document`**: `string | null`

    CPF ou CNPJ válido. Obrigatório para Jadlog, Loggi e J\&T, e para os Correios quando houver declaração de conteúdo.
  - **`email`**: `string | null`, maxLength: `100`

    E-mail do destinatário, para avisos de rastreio. Envie `null` ou vazio se não tiver.
  - **`number`**: `string | null`, maxLength: `10`

    Número. Vazio vira `S/N`.
  - **`phone`**: `string | null`

    Telefone com DDD, 10 ou 11 dígitos. Na J\&T, sem ele usamos o telefone do remetente.
- **`volumes` (required)**

  Caixa da encomenda. Use a caixa devolvida pela cotação. Também aceita um array; nesse caso, só o primeiro item é usado.

  **One of:**
  - `object`, schema: `PackageDimensions`

    Caixa da encomenda.
    - **`height` (required)**: `number`

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

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

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

      Largura, em cm.
  - `array`, minItems: `1`

    **Array of:**

    *Schema `PackageDimensions` is shown above.*
- **`options`**: `object`

  Serviços adicionais, nota fiscal e identificação do pedido. Envie sempre este objeto, mesmo vazio (`{}`), quando não enviar `platform`.
  - **`insurance_value`**: `number | null`

    Valor da mercadoria, sem o frete, para contratar seguro. Envie `null` ou `0` para não contratar.
  - **`invoice`**: `object`

    Nota fiscal da encomenda.
    - **`key`**: `string`

      Número da nota fiscal. Se você inverter os dois campos, a API corrige.
    - **`number`**: `string`

      Chave de acesso da nota fiscal, com 44 dígitos.
  - **`non_commercial`**: `boolean`, deprecated

    Ignorado. A declaração de conteúdo é usada sempre que `products` é enviado.
  - **`own_hand`**: `boolean`

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

    Aviso de recebimento (Correios).
  - **`tags`**: `array`

    Identificação do pedido na sua plataforma. Volta em `tags` nas respostas e nos webhooks.

    **Items:**
    - **`tag` (required)**: `string`

      Número do pedido na sua plataforma.
    - **`url`**: `string`

      Link do pedido na sua plataforma.
  - **`use_insurance_value`**: `boolean`

    Contrata o seguro com `insurance_value`. Com `false`, o seguro não é contratado mesmo que `insurance_value` venha preenchido.
- **`platform`**: `string`

  Nome da sua plataforma ou aplicação. Sem ele, usamos a plataforma cadastrada no token.
- **`products`**: `array`

  Itens da declaração de conteúdo. Quando enviado, a etiqueta sai com declaração de conteúdo.

  **Items:**
  - **`name` (required)**: `string`

    Nome do produto.
  - **`quantity` (required)**: `integer`, minimum: `1`

    Quantidade.
  - **`unitary_value` (required)**: `number`

    Valor unitário, em reais.

**Example: contentDeclaration**

PAC com declaração de conteúdo

```json
{
  "from": {
    "name": "Loja Aurora",
    "address": "Rua Barão de Itapetininga",
    "number": "255",
    "complement": "Sala 12",
    "district": "República",
    "city": "São Paulo",
    "state_abbr": "SP",
    "postal_code": "01042001"
  },
  "to": {
    "name": "Mariana Souza",
    "address": "Avenida Rio Branco",
    "number": "156",
    "district": "Centro",
    "city": "Rio de Janeiro",
    "state_abbr": "RJ",
    "postal_code": "20040003",
    "email": "mariana.souza@example.com",
    "phone": "21987654321",
    "document": "52998224725"
  },
  "service": 1,
  "products": [
    {
      "name": "Camiseta básica",
      "quantity": 2,
      "unitary_value": 49.9
    }
  ],
  "volumes": {
    "height": 4,
    "width": 16,
    "length": 24,
    "weight": 0.6
  },
  "options": {
    "insurance_value": 99.8,
    "use_insurance_value": true,
    "receipt": false,
    "own_hand": false,
    "tags": [
      {
        "tag": "3101481",
        "url": "https://minhaloja.com.br/pedidos/3101481"
      }
    ]
  },
  "platform": "MinhaLoja"
}
```

## Responses

### 200 Etiqueta criada com status `pending` (aguardando pagamento).

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

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

  ID do pedido na SuperFrete. Use nas outras rotas.
- **`price` (required)**: `number`

  Preço da etiqueta, em reais.
- **`status` (required)**: `string`, possible values: `"pending"`
- **`protocol`**: `string`

  Igual a `id`.
- **`self_tracking`**: `string`

  Vazio na criação. O rastreio só existe depois do pagamento.
- **`tags`**: `array`, schema: `OrderTags`

  Identificação do pedido na sua plataforma, enviada em `options.tags`.

  **Items:**
  - **`tag`**: `string`
  - **`url`**: `string`

**Example:**

```json
{
  "id": "r8p3dhqjn4I0tBpnvkpU",
  "protocol": "r8p3dhqjn4I0tBpnvkpU",
  "price": 22.38,
  "self_tracking": "",
  "status": "pending",
  "tags": [
    {
      "tag": "3101481",
      "url": "https://minhaloja.com.br/pedidos/3101481"
    }
  ]
}
```

### 400 Dados inválidos, serviço indisponível para a encomenda ou cadastro da conta incompleto.

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

**Any of:**

- `object`, 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.`
- `object`, 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: invalidPostalCode**

Campo inválido

```json
{
  "message": "Ocorreu um ou mais erros.",
  "errors": {
    "to.postal_code": [
      "O CEP do destinatário deve ter 8 dígitos"
    ]
  }
}
```

**Example: missingDocument**

CPF/CNPJ do destinatário ausente

```json
{
  "message": "Ocorreu um ou mais erros.",
  "errors": {
    "to.document": [
      "Campo CPF/CNPJ do destinatário é obrigatório para seguir com geração da etiqueta."
    ]
  }
}
```

**Example: serviceUnavailable**

Serviço indisponível

```json
{
  "message": "Ocorreu um ou mais erros.",
  "errors": {
    "service": [
      "Serviço indisponível para esse carrinho."
    ]
  }
}
```

**Example: incompleteRegistration**

Conta sem CPF/CNPJ

```json
{
  "message": "Cadastro incompleto. Por favor, finalizar o cadastro para prosseguir",
  "error": "Cadastro incompleto. Por favor, finalizar o cadastro para prosseguir"
}
```

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

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

*Schema `Error` is shown above.*

**Example:**

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

### 500 Erro interno. Nos Correios, também é a resposta quando o valor do seguro fica fora da faixa aceita pelo serviço.

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

**One of:**

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

**Example:**

```json
{
  "message": "Houve um erro ao verificar o valor do pedido: Valor segurado ultrapassa o limite máximo de R$ 38.057,59",
  "error": "Houve um erro ao verificar o valor do pedido: Valor segurado ultrapassa o limite máximo de R$ 38.057,59"
}
```

## 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.

### 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.

- `ShipmentSender` — shown above.
- `ShipmentRecipient` — shown above.

### StateAbbr

**Type:** `string`, pattern: `^[A-Z]{2}$`

UF em maiúsculas.

**Example:**

```json
"SP"
```

- `OrderTags` — shown above.