# Listar merchants

> Lista os merchants da sua empresa, paginado, com o merchant_id que criar transação e enviar evento de captura pedem.

Página: https://doc.rapidchargeback.com/canais/merchants/listar-merchants/

Lista os merchants (lojas, marcas ou vendedores) da sua empresa. É daqui que sai o `merchant_id` que [criar transação](https://doc.rapidchargeback.com/canais/transactions/criar-transacao/) e [enviar evento pelo servidor](https://doc.rapidchargeback.com/canais/capture/enviar-evento-servidor/) pedem.

Só leitura: cadastrar e editar merchant é pelo painel.

## Endpoint

```
GET https://api.rapidchargeback.com/api/v1/merchants
```

## Autenticação

```
Authorization: Basic base64(client_id:client_secret)
```

---

## Query params

Todos opcionais.

| Param | Tipo | Default | Descrição |
|---|---|---|---|
| `page` | int (≥ 1) | `1` | Página |
| `per_page` | int (1–100) | `20` | Itens por página |
| `merchant_ref` | string (até 100) | - | O ID do vendedor no **seu** sistema, o mesmo `merchant_ref` aceito em [criar transação](https://doc.rapidchargeback.com/canais/transactions/criar-transacao/). Devolve 0 ou 1 item |
| `status` | enum | - | `active` ou `inactive` |

A lista vem sempre paginada, em ordem de cadastro (o mais antigo primeiro). Para percorrer todos, avance `page` até `page` chegar a `total_pages`: merchant cadastrado no meio do caminho entra no fim, sem fazer você pular ou repetir item.

---

## Exemplos

### Todos os merchants

```bash
curl -G "https://api.rapidchargeback.com/api/v1/merchants" \
  --data-urlencode "per_page=100" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
```

### Pelo ID do vendedor no seu sistema

```bash
curl -G "https://api.rapidchargeback.com/api/v1/merchants" \
  --data-urlencode "merchant_ref=seller-77" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="
```

---

## Resposta

### Sucesso

```json
{
  "data": [
    {
      "id": "00000000-0000-0000-0000-000000000001",
      "name": "Loja Exemplo",
      "merchant_ref": null,
      "status": "active",
      "created_at": "2026-03-10T12:00:00.000Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 1,
    "total_pages": 1
  }
}
```

| Campo | Descrição |
|---|---|
| `id` | O `merchant_id` que as outras APIs pedem |
| `name` | Nome do merchant no painel |
| `merchant_ref` | O ID do vendedor no seu sistema, quando o merchant foi criado por `merchant_ref`. `null` nos cadastrados pelo painel |
| `status` | `active` ou `inactive`. Merchant inativo não recebe alertas |
| `created_at` | Quando foi cadastrado |

São só esses campos: dados de contato, endereço e termos do merchant ficam no painel.

### Sem resultados

```json
{
  "data": [],
  "meta": { "page": 1, "per_page": 20, "total": 0, "total_pages": 0 }
}
```

### Parâmetro inválido (ex: `per_page=500`)

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Number must be less than or equal to 100"
  }
}
```

---

## Notas

- **Só os merchants da sua empresa.** A empresa vem da credencial; não há parâmetro para escolher outra.
- **Empresa bloqueada** recebe `403 COMPANY_BLOCKED`, como nas outras APIs.
- **Auth, rate limit, códigos de erro:** ver [Autenticação](https://doc.rapidchargeback.com/referencia/autenticacao/) e [Códigos de resposta](https://doc.rapidchargeback.com/referencia/codigos-de-resposta/).