# Lote de merchants

> Cria ou atualiza até 500 merchants numa chamada, pelo merchant_ref, com o resultado de cada item na ordem enviada.

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

Cria ou atualiza até **500 merchants** numa chamada. Cada item segue exatamente a regra de [Criar ou atualizar merchant](https://doc.rapidchargeback.com/canais/merchants/criar-ou-atualizar-merchant/): a chave é o `merchant_ref`, o que não mudou não é gravado, e repetir o lote não duplica nada.

O lote é sempre **parcial**: cada item é gravado ou recusado por conta própria, e a resposta diz o que aconteceu com cada um, na mesma ordem do envio.

## Endpoint

```
POST https://api.rapidchargeback.com/api/v1/merchants/batch
```

## Autenticação

```
Authorization: Basic base64(client_id:client_secret)
Content-Type: application/json
```

---

## Corpo da requisição

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `items` | array | Sim | De 1 a 500 merchants, cada um com os campos de [Criar ou atualizar merchant](https://doc.rapidchargeback.com/canais/merchants/criar-ou-atualizar-merchant/#corpo-da-requisição) |
| `on_name_conflict` | enum | Não | `error` (padrão) ou `append_ref`, para todos os itens. O `on_name_conflict` de um item vale mais que este |

- Corpo de até **5 MB**. Acima disso, `413 PAYLOAD_TOO_LARGE`.
- Campo fora de `items` e `on_name_conflict` no envelope, `items` vazio ou com mais de 500: o lote inteiro é recusado com `422 VALIDATION_ERROR`, sem gravar nada.

### Repetidos no mesmo lote

O primeiro item vale; os seguintes são recusados, sem gravar:

- mesmo `merchant_ref` (sem diferenciar maiúsculas nem acentos): `MERCHANT_REF_DUPLICATE_IN_BATCH`;
- mesmo `name` em referências diferentes (sem `append_ref`): `MERCHANT_NAME_DUPLICATE_IN_BATCH`.

---

## Exemplo de requisição

```bash
curl -X POST https://api.rapidchargeback.com/api/v1/merchants/batch \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "merchant_ref": "PB-1001", "name": "Loja Exemplo" },
      { "merchant_ref": "PB-1002", "name": "Loja Exemplo Dois", "merchant_url": "https://lojaexemplodois.com" },
      { "merchant_ref": "PB-1003", "name": "Loja Exemplo" }
    ]
  }'
```

---

## Resposta

### Sucesso

`200 OK` sempre que o lote foi processado, mesmo com itens recusados. Confira `failed` e o `result` de cada item.

```json
{
  "data": {
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "counts": { "created": 1, "updated": 0, "unchanged": 1 },
    "results": [
      {
        "index": 0,
        "result": "unchanged",
        "merchant_ref": "PB-1001",
        "merchant": {
          "id": "00000000-0000-0000-0000-000000000001",
          "name": "Loja Exemplo",
          "merchant_ref": "PB-1001",
          "status": "active",
          "created_at": "2026-11-06T12:00:00.000Z",
          "updated_at": "2026-11-06T12:00:00.000Z"
        }
      },
      {
        "index": 1,
        "result": "created",
        "merchant_ref": "PB-1002",
        "merchant": {
          "id": "00000000-0000-0000-0000-000000000002",
          "name": "Loja Exemplo Dois",
          "merchant_ref": "PB-1002",
          "status": "active",
          "created_at": "2026-11-07T12:00:00.000Z",
          "updated_at": "2026-11-07T12:00:00.000Z"
        }
      },
      {
        "index": 2,
        "result": "error",
        "merchant_ref": "PB-1003",
        "status": 422,
        "error": {
          "code": "MERCHANT_NAME_DUPLICATE_IN_BATCH",
          "message": "name appears more than once in the batch",
          "params": { "name": "Loja Exemplo" }
        }
      }
    ]
  }
}
```

| Campo | Descrição |
|---|---|
| `total` | Itens enviados |
| `succeeded` | Itens criados, atualizados ou sem mudança (`total - failed`) |
| `failed` | Itens recusados |
| `counts` | Quantos de cada: `created`, `updated`, `unchanged` |
| `results` | Um por item, na ordem do array enviado |
| `results[].index` | Posição do item no array enviado, a partir de 0 |
| `results[].result` | `created`, `updated`, `unchanged` ou `error` |
| `results[].merchant_ref` | O `merchant_ref` que você mandou no item (`null` se não veio texto) |
| `results[].merchant` | No sucesso: o resumo do merchant, o mesmo de [Listar merchants](https://doc.rapidchargeback.com/canais/merchants/listar-merchants/#sucesso) |
| `results[].warnings` | Quando houver: o aviso `SERVICE_FIELDS_NOT_APPLIED` (ver [Aviso de dado que não vale na hora](https://doc.rapidchargeback.com/canais/merchants/criar-ou-atualizar-merchant/#aviso-de-dado-que-não-vale-na-hora)) |
| `results[].status` | No erro: o HTTP que o item teria sozinho |
| `results[].error` | No erro: `code`, `message` e, quando houver, `params` |

Os erros de cada item são os de [Criar ou atualizar merchant](https://doc.rapidchargeback.com/canais/merchants/criar-ou-atualizar-merchant/#erros), mais os dois de repetidos no lote.

### Outro lote em andamento

```
HTTP/1.1 429 Too Many Requests
Retry-After: 5
```

```json
{
  "error": {
    "code": "BATCH_IN_PROGRESS",
    "message": "Another batch from this account is still being processed. Try again in a few seconds."
  }
}
```

A sua empresa tem um lote de merchants por vez. O segundo lote enviado enquanto o primeiro ainda está sendo gravado é recusado inteiro, sem gravar nada: espere o `Retry-After` e mande de novo.

### Erros do lote inteiro

| HTTP | Código | Quando |
|---|---|---|
| 422 | `VALIDATION_ERROR` | Envelope inválido: `items` ausente, vazio, com mais de 500, ou campo desconhecido no envelope |
| 413 | `PAYLOAD_TOO_LARGE` | Corpo acima de 5 MB |
| 429 | `RATE_LIMIT_EXCEEDED` | Mais de 60 escritas por minuto (cada lote conta uma) |
| 429 | `BATCH_IN_PROGRESS` | Outro lote de merchants da sua empresa ainda em andamento |
| 403 | `KYB_NOT_APPROVED`, `COMPANY_NOT_ACTIVE`, `COMPANY_BLOCKED` | Ver [Criar ou atualizar merchant](https://doc.rapidchargeback.com/canais/merchants/criar-ou-atualizar-merchant/#erros) |
| 503 | `SERVICE_UNAVAILABLE` | Indisponibilidade temporária: repita depois do `Retry-After` |

---

## Notas

- **Repetir é seguro.** Depois de um `503` ou de uma queda de conexão, mande o mesmo lote: o que já foi gravado volta `unchanged`.
- **Volume:** 3.000 merchants são 6 chamadas de 500. Mande um lote depois do outro, não em paralelo.
- **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/).
