# Lote de merchants

> Crea o actualiza hasta 500 merchants en una llamada, por el merchant_ref, con el resultado de cada ítem en el orden enviado.

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

Crea o actualiza hasta **500 merchants** en una llamada. Cada ítem sigue exactamente la regla de [Crear o actualizar merchant](https://doc.rapidchargeback.com/es/canais/merchants/criar-ou-atualizar-merchant/): la clave es el `merchant_ref`, lo que no cambió no se guarda, y repetir el lote no duplica nada.

El lote es siempre **parcial**: cada ítem se guarda o se rechaza por su cuenta, y la respuesta dice qué pasó con cada uno, en el mismo orden del envío.

## Endpoint

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

## Autenticación

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

---

## Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Descripción |
|---|---|---|---|
| `items` | array | Sí | De 1 a 500 merchants, cada uno con los campos de [Crear o actualizar merchant](https://doc.rapidchargeback.com/es/canais/merchants/criar-ou-atualizar-merchant/#cuerpo-de-la-solicitud) |
| `on_name_conflict` | enum | No | `error` (por defecto) o `append_ref`, para todos los ítems. El `on_name_conflict` de un ítem vale más que este |

- Cuerpo de hasta **5 MB**. Por encima, `413 PAYLOAD_TOO_LARGE`.
- Un campo distinto de `items` y `on_name_conflict` en el envoltorio, o `items` vacío o con más de 500: el lote entero se rechaza con `422 VALIDATION_ERROR`, sin guardar nada.

### Repetidos en el mismo lote

El primer ítem vale; los siguientes se rechazan, sin guardar:

- mismo `merchant_ref` (sin distinguir mayúsculas ni acentos): `MERCHANT_REF_DUPLICATE_IN_BATCH`;
- mismo `name` en referencias distintas (sin `append_ref`): `MERCHANT_NAME_DUPLICATE_IN_BATCH`.

---

## Ejemplo de solicitud

```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" }
    ]
  }'
```

---

## Respuesta

### Éxito

`200 OK` siempre que el lote se procesó, incluso con ítems rechazados. Revisa `failed` y el `result` de cada ítem.

```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 | Descripción |
|---|---|
| `total` | Ítems enviados |
| `succeeded` | Ítems creados, actualizados o sin cambios (`total - failed`) |
| `failed` | Ítems rechazados |
| `counts` | Cuántos de cada uno: `created`, `updated`, `unchanged` |
| `results` | Uno por ítem, en el orden del array enviado |
| `results[].index` | Posición del ítem en el array enviado, desde 0 |
| `results[].result` | `created`, `updated`, `unchanged` o `error` |
| `results[].merchant_ref` | El `merchant_ref` que enviaste en el ítem (`null` si no vino texto) |
| `results[].merchant` | En el éxito: el resumen del merchant, el mismo de [Listar merchants](https://doc.rapidchargeback.com/es/canais/merchants/listar-merchants/#éxito) |
| `results[].warnings` | Cuando hay: el aviso `SERVICE_FIELDS_NOT_APPLIED` (ver [Aviso de dato que no se aplica en el momento](https://doc.rapidchargeback.com/es/canais/merchants/criar-ou-atualizar-merchant/#aviso-de-dato-que-no-se-aplica-en-el-momento)) |
| `results[].status` | En el error: el HTTP que el ítem tendría solo |
| `results[].error` | En el error: `code`, `message` y, cuando hay, `params` |

Los errores de cada ítem son los de [Crear o actualizar merchant](https://doc.rapidchargeback.com/es/canais/merchants/criar-ou-atualizar-merchant/#errores), más los dos de repetidos en el lote.

### Otro lote en curso

```
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."
  }
}
```

Tu empresa tiene un lote de merchants a la vez. El segundo lote enviado mientras el primero todavía se está guardando se rechaza entero, sin guardar nada: espera el `Retry-After` y envíalo de nuevo.

### Errores del lote entero

| HTTP | Código | Cuándo |
|---|---|---|
| 422 | `VALIDATION_ERROR` | Envoltorio inválido: `items` ausente, vacío, con más de 500, o campo desconocido en el envoltorio |
| 413 | `PAYLOAD_TOO_LARGE` | Cuerpo por encima de 5 MB |
| 429 | `RATE_LIMIT_EXCEEDED` | Más de 60 escrituras por minuto (cada lote cuenta como una) |
| 429 | `BATCH_IN_PROGRESS` | Otro lote de merchants de tu empresa todavía en curso |
| 403 | `KYB_NOT_APPROVED`, `COMPANY_NOT_ACTIVE`, `COMPANY_BLOCKED` | Ver [Crear o actualizar merchant](https://doc.rapidchargeback.com/es/canais/merchants/criar-ou-atualizar-merchant/#errores) |
| 503 | `SERVICE_UNAVAILABLE` | No disponible temporalmente: repite después del `Retry-After` |

---

## Notas

- **Repetir es seguro.** Después de un `503` o de una caída de conexión, envía el mismo lote: lo que ya se guardó vuelve `unchanged`.
- **Volumen:** 3.000 merchants son 6 llamadas de 500. Envía un lote después del otro, no en paralelo.
- **Auth, rate limit, códigos de error:** ver [Autenticación](https://doc.rapidchargeback.com/es/referencia/autenticacao/) y [Códigos de respuesta](https://doc.rapidchargeback.com/es/referencia/codigos-de-resposta/).
