> ## Documentation Index
> Fetch the complete documentation index at: https://docs.repediu.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar pedidos
> Histórico de pedidos dos merchants do escopo, no contexto CRM — valores em centavos
Retorna o **histórico de pedidos** dos merchants vinculados à sua aplicação, no contexto CRM — esta rota serve para análise e relacionamento com o cliente, **não** para o ciclo operacional do pedido (aceite, despacho, entrega). A lista vem ordenada da venda mais recente para a mais antiga.
Envelope plano (`items`, `page`, `pageSize`, `total`); `pageSize` padrão 50, máximo **500**. O campo `storeId` identifica o merchant dono de cada pedido — o mesmo `id` de [Listar merchants](/open-delivery/listar-merchants).
Todos os **valores monetários são em centavos** (`totalAmount` e `unitPrice`): R\$ 75,90 chega como `7590`. Divida por 100 antes de exibir.
## Modalidade (`originChannel`)
`originChannel` é a **modalidade** do pedido, num enum fechado — use-o também como filtro:
| `originChannel` | Significado |
| -------------------------------------------- | -------------------------------------- |
| `delivery` | Entrega |
| `takeout` | Retirada no balcão |
| `in_store` | Consumo no local |
| `own_app`, `marketplace`, `qr_code`, `kiosk` | Valores do protocolo aceitos no filtro |
| `other` | Pedidos sem modalidade mapeada |
## Filtros
* **Por merchant**: `storeId` (opcional) restringe a um único estabelecimento — o mesmo `id` de [Listar merchants](/open-delivery/listar-merchants). Omitido, retorna os pedidos de todos os merchants do escopo; um `storeId` inexistente ou fora do escopo responde `404` com `Merchant not found.`.
* **Por cliente**: `customerIdentifierType` + `customerIdentifierValue` (sempre em par).
* **Sincronização incremental**: janelas `createdFrom`/`createdTo` (data da venda) e `updatedFrom`/`updatedTo` (última atualização), inclusive nas duas pontas.
## O que vem em `metadata`
Cada pedido traz `metadata.channel` com a **modalidade/canal da venda** como texto livre (o nome do canal registrado na origem), ou `null` quando a venda não informou canal. Diferente de `originChannel` — que é um enum fechado e serve de filtro — o `channel` preserva o valor original, útil para relatórios que precisam do nome exato do canal.
## Erros
| HTTP | `code` no corpo | Quando acontece | O que fazer |
| ----- | --------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
| `400` | `BAD_REQUEST` | Enum fora da lista, identificador sem valor, janela de datas invertida, paginação inválida | Corrija o parâmetro indicado em `details` |
| `401` | `UNAUTHORIZED` | Token ausente, inválido ou expirado | Gere um novo token em [Obter token](/open-delivery/obter-token) |
| `403` | `FORBIDDEN` | Aplicação sem nenhum merchant vinculado | Aguarde ao menos um estabelecimento ativar a integração |
| `404` | `NOT_FOUND` | Filtro `storeId` com id inexistente **ou fora do escopo** | Confirme o `id` em [Listar merchants](/open-delivery/listar-merchants) |
Detalhe de um pedido pelo `id` retornado nesta listagem.
## OpenAPI
````yaml openapi.yaml GET /od/v2/orders
openapi: 3.0.1
info:
title: Repediu — API de integração
description: >-
API de integração da Repediu: rotas Open Delivery 2.0 (capabilities CRM),
dado bruto do CRM do parceiro (/v1/stores) e métricas agregadas
(/v1/stores/.../metrics). A autenticação usa o fluxo client_credentials: o
token identifica a aplicação integradora e dá acesso a todos os
estabelecimentos (merchants) que ativaram a integração.
version: v2
servers:
- url: https://public-api.repediu.com.br
description: Produção
security:
- Bearer: []
paths:
/od/v2/orders:
get:
tags:
- Pedidos
summary: Listar pedidos
description: >-
Lista o histórico de pedidos de todos os merchants do escopo da
aplicação. Envelope plano (`items`, `page`, `pageSize`, `total`). O
campo `storeId` identifica o merchant de cada pedido. Valores monetários
em centavos.
operationId: listOrders
parameters:
- name: storeId
in: query
description: >-
Restringe a lista a um único merchant. Omitido, retorna os pedidos
de todos os merchants do escopo. Id inexistente ou fora do escopo
responde 404.
schema:
type: string
format: uuid
- name: customerIdentifierType
in: query
description: >-
Tipo do identificador canônico do cliente. Exige
customerIdentifierValue.
schema:
type: string
enum:
- phone
- email
- document
- external_id
- name: customerIdentifierValue
in: query
description: >-
Valor do identificador canônico (obrigatório quando
customerIdentifierType é informado).
schema:
type: string
- name: originChannel
in: query
description: Filtra pela modalidade do pedido.
schema:
type: string
enum:
- own_app
- marketplace
- in_store
- qr_code
- kiosk
- delivery
- takeout
- other
- name: createdFrom
in: query
description: >-
Início da janela de criação (inclusive). Deve ser anterior ou igual
a createdTo.
schema:
type: string
format: date-time
- name: createdTo
in: query
description: Fim da janela de criação (inclusive).
schema:
type: string
format: date-time
- name: updatedFrom
in: query
description: >-
Início da janela de atualização (inclusive). Deve ser anterior ou
igual a updatedTo.
schema:
type: string
format: date-time
- name: updatedTo
in: query
description: Fim da janela de atualização (inclusive).
schema:
type: string
format: date-time
- name: Page
in: query
description: Página, iniciando em 1.
schema:
type: integer
format: int32
default: 1
- name: PageSize
in: query
description: Itens por página. Valores acima de 500 são limitados a 500.
schema:
type: integer
format: int32
default: 50
maximum: 500
responses:
'200':
description: >-
Página de pedidos do escopo da aplicação, ordenada da data de venda
mais recente para a mais antiga.
content:
application/json:
schema:
$ref: '#/components/schemas/OrderPageResponse'
example:
items:
- id: '1107300'
storeId: 07f3bb0c-927a-4d99-9ea3-c22ecce8721c
originChannel: delivery
customer:
identifier:
type: phone
value: '5517999998888'
externalIds:
- source: repediu
value: CLI-0042
totalAmount: 7590
items:
- sku: PRD-101
name: Pastel de Carne
quantity: 2
unitPrice: 1200
- sku: PRD-305
name: Caldo de Cana 500ml
quantity: 1
unitPrice: 5190
metadata:
channel: iFood
createdAt: '2026-06-18T20:12:44-03:00'
updatedAt: '2026-06-18T20:45:02-03:00'
page: 1
pageSize: 50
total: 1
'400':
description: >-
Filtro ou paginação inválidos (enum fora da lista, janela invertida,
identificador sem valor).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: BAD_REQUEST
message: One or more validation errors occurred
details:
- >-
originChannel should be one of: own_app, marketplace,
in_store, qr_code, kiosk, delivery, takeout, other
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/MerchantNotFound'
components:
schemas:
OrderPageResponse:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/OrderResponse'
page:
type: integer
format: int32
pageSize:
type: integer
format: int32
total:
type: integer
format: int32
description: >-
Total de registros que atendem ao filtro, considerando todas as
páginas.
ErrorResponse:
type: object
properties:
code:
type: string
description: >-
Código do erro (BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND,
INTERNAL_SERVER_ERROR).
message:
type: string
details:
type: array
nullable: true
description: Lista de mensagens de validação, quando aplicável.
items:
type: string
OrderResponse:
type: object
properties:
id:
type: string
description: Identificador do pedido na Repediu.
storeId:
type: string
format: uuid
description: >-
Identificador do merchant dono do pedido (mesmo id de
/od/v2/merchants).
originChannel:
type: string
description: >-
Modalidade do pedido. Pedidos sem modalidade mapeada retornam
`other`.
enum:
- own_app
- marketplace
- in_store
- qr_code
- kiosk
- delivery
- takeout
- other
customer:
type: object
properties:
identifier:
$ref: '#/components/schemas/CustomerIdentifier'
externalIds:
type: array
items:
type: object
properties:
source:
type: string
value:
type: string
totalAmount:
type: integer
format: int64
description: Valor total do pedido em centavos.
items:
type: array
items:
type: object
properties:
sku:
type: string
description: Código do produto.
name:
type: string
quantity:
type: number
unitPrice:
type: integer
format: int64
description: Preço unitário em centavos.
metadata:
type: object
description: Dados complementares do pedido.
properties:
channel:
type: string
nullable: true
description: >-
Modalidade/canal da venda como texto livre. Null quando a venda
não informou canal.
createdAt:
type: string
format: date-time
description: Data da venda.
updatedAt:
type: string
format: date-time
CustomerIdentifier:
type: object
description: >-
Identificador canônico do cliente, escolhido nesta ordem de prioridade —
document, phone, email, external_id.
properties:
type:
type: string
enum:
- document
- phone
- email
- external_id
value:
type: string
responses:
Unauthorized:
description: Token ausente, inválido ou expirado.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: UNAUTHORIZED
message: Invalid client credentials.
details: null
Forbidden:
description: Token sem o escopo od.crm ou aplicação sem nenhum merchant vinculado.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: FORBIDDEN
message: Application is not authorized to access any merchant.
details: null
MerchantNotFound:
description: Merchant inexistente ou fora do escopo da aplicação.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: NOT_FOUND
message: Merchant not found.
details: null
securitySchemes:
Bearer:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
Token de acesso emitido por POST /od/v2/oauth/token (fluxo
client_credentials). Envie no header Authorization como `Bearer
`.
````