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

# Listar pedidos

> `GET /api/v0/me/orders` · Referência interativa: https://developers.superfrete.com/referencia#listOrders

- **Method:** `GET`
- **Path:** `/api/v0/me/orders`
- **Operation ID:** `listOrders`
- **Tags:** Pedidos

Lista os pedidos da conta, com filtro por status, busca, paginação e ordenação. Sem filtros, traz todos os status, 20 por página, do mais recente para o mais antigo.

> **User-Agent obrigatório**
>
> Esta rota recusa a requisição se o `User-Agent` não seguir o formato `Aplicação (email@exemplo.com)`.

`sort_by` escolhe a data usada na ordenação (`created_at` ou `updated_at`) e `order` escolhe a direção. `meta` traz o total de pedidos, o tamanho da página, a página atual e a última página.

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

## Query parameters

- **`status`**: `string`, possible values: `"pending", "released", "posted", "delivered", "canceled"`

  Filtra por status. Sem ele, traz todos.

  `pending`: aguardando pagamento · `released`: paga, aguardando postagem · `posted`: postada · `delivered`: entregue · `canceled`: cancelada.
- **`q`**: `string`

  Busca exata pelo ID do pedido ou pelo número da etiqueta.
- **`page`**: `integer`, default: `1`, minimum: `1`

  Página, a partir de 1.
- **`per_page`**: `integer`, default: `20`, minimum: `1`, maximum: `100`

  Pedidos por página, de 1 a 100.
- **`sort_by`**: `string`, possible values: `"created_at", "updated_at"`, default: `"created_at"`

  Data usada na ordenação.
- **`order`**: `string`, possible values: `"asc", "desc"`, default: `"desc"`

  `desc` (mais recentes primeiro) ou `asc`.

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

## Responses

### 200 Página de pedidos.

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

- **`data` (required)**: `array`

  **Items:**

  schema: `OrderListItem`
  - **`carrier`**: `string`, possible values: `"correios", "jadlog", "loggi", "jt"`

    Transportadora.
  - **`created_at`**: `string | null`, format: `date-time`
  - **`delivery`**: `object`

    Prazo de entrega, em dias úteis.
    - **`max`**: `integer`
    - **`min`**: `integer`
  - **`from`**: `object`, schema: `OrderListAddress`
    - **`address`**: `string | null`
    - **`city`**: `string | null`
    - **`complement`**: `string | null`
    - **`district`**: `string | null`
    - **`document`**: `string | null`
    - **`name`**: `string | null`
    - **`number`**: `string | null`
    - **`phone`**: `string | null`
    - **`postal_code`**: `string | null`
    - **`state`**: `string | null`

      UF.
  - **`order_id`**: `string`

    ID do pedido.
  - **`price`**: `object`

    Valores em reais.
    - **`discount`**: `number`

      Desconto SuperFrete.
    - **`total`**: `number`

      Valor com desconto.
    - **`without_discount`**: `number`

      Preço de balcão da transportadora.
  - **`pudo`**: `object`

    Ponto de postagem escolhido, quando houver. Campos `null` quando a postagem é numa agência.
    - **`address`**: `string | null`
    - **`city`**: `string | null`
    - **`complement`**: `string | null`
    - **`district`**: `string | null`
    - **`number`**: `string | null`
    - **`postal_code`**: `string | null`
    - **`state`**: `string | null`
    - **`unit`**: `string | null`

      Nome do ponto.
  - **`status`**: `string`, possible values: `"pending", "released", "posted", "delivered", "canceled"`

    `pending`: aguardando pagamento · `released`: paga, aguardando postagem · `posted`: postada · `delivered`: entregue · `canceled`: cancelada.
  - **`to`**

    **All of:**
    - *Schema `OrderListAddress` is shown above.*
    - `object`
      - **`email`**: `string | null`
  - **`tracking`**: `string | null`

    Código de rastreio, quando já existe.
  - **`updated_at`**: `string | null`, format: `date-time`
- **`meta` (required)**: `object`
  - **`last_page`**: `integer`
  - **`page`**: `integer`
  - **`per_page`**: `integer`
  - **`total`**: `integer`

    Total de pedidos que atendem ao filtro.

**Example:**

```json
{
  "data": [
    {
      "order_id": "r8p3dhqjn4I0tBpnvkpU",
      "status": "released",
      "carrier": "correios",
      "tracking": null,
      "price": {
        "total": 22.38,
        "discount": 7.41,
        "without_discount": 29.79
      },
      "delivery": {
        "min": 5,
        "max": 5
      },
      "from": {
        "name": "Loja Aurora",
        "phone": "11912345678",
        "document": "11222333000181",
        "postal_code": "01042001",
        "address": "Rua Barão de Itapetininga",
        "number": "255",
        "complement": "Sala 12",
        "state": "SP",
        "city": "São Paulo",
        "district": "República"
      },
      "to": {
        "name": "Mariana Souza",
        "phone": "21987654321",
        "email": "mariana.souza@example.com",
        "document": "52998224725",
        "postal_code": "20040003",
        "address": "Avenida Rio Branco",
        "number": "156",
        "complement": null,
        "state": "RJ",
        "city": "Rio de Janeiro",
        "district": "Centro"
      },
      "pudo": {
        "unit": null,
        "postal_code": null,
        "address": null,
        "number": null,
        "complement": null,
        "state": null,
        "city": null,
        "district": null
      },
      "created_at": "2026-10-29T14:01:47.399Z",
      "updated_at": "2026-10-29T14:03:12.902Z"
    }
  ],
  "meta": {
    "total": 1,
    "per_page": 20,
    "page": 1,
    "last_page": 1
  }
}
```

### 400 `User-Agent` ausente ou fora do formato, ou filtro inválido.

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

**Any of:**

- `object`, schema: `UserAgentError`

  `User-Agent` ausente ou fora do formato `Aplicação (email@exemplo.com)`.
  - **`code` (required)**: `string`, possible values: `"invalid-argument"`
  - **`error` (required)**: `string`
- `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: userAgent**

User-Agent fora do formato

```json
{
  "error": "User-Agent deve seguir o formato: Aplicação (email@exemplo.com)",
  "code": "invalid-argument"
}
```

**Example: pagination**

per_page fora da faixa

```json
{
  "message": "Quantidade de itens por página deve estar entre 1 e 100",
  "error": "Quantidade de itens por página deve estar entre 1 e 100"
}
```

### 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. 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.
- `UserAgentError` — shown above.

### OrderStatus

**Type:** `string`, possible values: `"pending", "released", "posted", "delivered", "canceled"`

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

- `OrderListAddress` — shown above.
- `OrderListItem` — shown above.