> ## 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 merchants
> Descubra quais estabelecimentos autorizaram a sua aplicação — o escopo do seu token
Esta rota é o ponto de partida da integração: ela retorna os **estabelecimentos (merchants) que autorizaram a sua aplicação** — o escopo completo do token. O vínculo nasce quando o estabelecimento ativa a integração no painel da Repediu; quando ele desativa, o merchant sai do escopo e os dados dele deixam de aparecer em **todas** as rotas.
O `id` de cada merchant é o UUID que você usará no restante da API:
É o `merchantId` do detalhe do estabelecimento.
É o mesmo valor de `storeId` nos pedidos e de `merchantId` nos clientes.
É o `merchantId` do caminho de todas as rotas `/v1/stores/{merchantId}/...`.
O envelope desta rota é **aninhado**: a lista vem em `merchants` e a paginação num objeto `pagination` separado — diferente das rotas de clientes e pedidos, que usam envelope plano (`items`, `page`, `pageSize`, `total` no mesmo nível).
`pageSize` padrão é 50 e o máximo é **200** — valores maiores são reduzidos para 200 silenciosamente (não geram erro).
## Status do merchant
| `status` | Significado |
| -------- | ------------------------------------------------------------ |
| `OPEN` | Estabelecimento ativo na Repediu |
| `CLOSED` | Estabelecimento inativo |
| `PAUSED` | Faz parte do enum do protocolo, mas não é emitido atualmente |
## Erros
| HTTP | `code` no corpo | Quando acontece | O que fazer |
| ----- | --------------- | --------------------------------------------------------------- | --------------------------------------------------------------- |
| `400` | `BAD_REQUEST` | `page`/`pageSize` menor que 1 ou `status` fora do enum | 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 (nenhuma ativação viva) | Aguarde ao menos um estabelecimento ativar a integração |
## OpenAPI
````yaml openapi.yaml GET /od/v2/merchants
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/merchants:
get:
tags:
- Merchants
summary: Listar merchants
description: >-
Lista os estabelecimentos (merchants) autorizados para a aplicação — o
escopo completo do token. A resposta usa envelope aninhado (`merchants`
+ `pagination`).
operationId: listMerchants
parameters:
- 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 200 são limitados a 200.
schema:
type: integer
format: int32
default: 50
maximum: 200
- name: status
in: query
description: Filtra pelo status do merchant.
schema:
type: string
enum:
- OPEN
- CLOSED
- PAUSED
responses:
'200':
description: Lista de merchants do escopo da aplicação.
content:
application/json:
schema:
$ref: '#/components/schemas/MerchantListResponse'
example:
merchants:
- id: 07f3bb0c-927a-4d99-9ea3-c22ecce8721c
name: Pastelaria do Luiz
status: OPEN
- id: 5eeb5b9f-cece-4ebe-9715-b26783225e10
name: Pizzaria Bella Massa
status: CLOSED
pagination:
page: 1
pageSize: 50
total: 2
'400':
description: >-
Parâmetro inválido (page/pageSize menor que 1 ou status fora do
enum).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
code: BAD_REQUEST
message: One or more validation errors occurred
details:
- 'status should be one of: OPEN, CLOSED, PAUSED'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
components:
schemas:
MerchantListResponse:
type: object
properties:
merchants:
type: array
items:
$ref: '#/components/schemas/MerchantSummary'
pagination:
$ref: '#/components/schemas/Pagination'
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
MerchantSummary:
type: object
properties:
id:
type: string
format: uuid
description: >-
Identificador do merchant, usado em /od/v2/merchants/{merchantId} e
referenciado por storeId e metadata.merchantId.
name:
type: string
description: Nome do estabelecimento.
status:
type: string
description: >-
Status do merchant. OPEN quando ativo na Repediu; CLOSED caso
contrário.
enum:
- OPEN
- CLOSED
- PAUSED
Pagination:
type: object
properties:
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.
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
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
`.
````