# Editar merchant

> Modifica el registro de un merchant por el merchant_id y guarda el merchant_ref en un merchant que todavía no tiene. La referencia no se cambia después de guardada.

Página: https://doc.rapidchargeback.com/es/canais/merchants/editar-merchant/

Modifica el registro de un merchant de tu empresa por el `merchant_id`. Es también la forma de guardar el `merchant_ref` en un merchant que ya existía sin referencia (por ejemplo, uno registrado en el panel): después de eso, [Crear o actualizar merchant](https://doc.rapidchargeback.com/es/canais/merchants/criar-ou-atualizar-merchant/) y el [Lote de merchants](https://doc.rapidchargeback.com/es/canais/merchants/lote-de-merchants/) pasan a actualizarlo por la referencia.

## Endpoint

```
PATCH https://api.rapidchargeback.com/api/v1/merchants/:merchant_id
```

## Autenticación

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

---

## Parámetros de URL

| Param | Tipo | Descripción |
|---|---|---|
| `merchant_id` | string (UUID) | El `id` del merchant |

## Cuerpo de la solicitud

Cualquier campo de [Crear o actualizar merchant](https://doc.rapidchargeback.com/es/canais/merchants/criar-ou-atualizar-merchant/#cuerpo-de-la-solicitud), todos opcionales, con los mismos límites. `on_name_conflict` no existe aquí.

- Envía solo lo que cambia. El campo que no vino queda como está; `null` o `""` lo limpia (menos `name`).
- Cuerpo vacío (`{}`): `422 VALIDATION_ERROR` "Send at least one field".
- Nombre de otro merchant tuyo: `409 MERCHANT_DUPLICATE`, con su `merchant_id`.

### `merchant_ref`: se guarda una vez

| Situación | Respuesta |
|---|---|
| El merchant no tiene referencia | Guarda la enviada |
| La enviada es igual a la guardada | Nada cambia (`unchanged`, si ningún otro campo cambió) |
| El merchant ya tiene otra referencia | `409 MERCHANT_REF_IMMUTABLE`: la referencia no se cambia |
| Otro merchant tuyo ya usa esa referencia | `409 MERCHANT_REF_TAKEN`, con su `merchant_id` |

La referencia no se cambia porque las transacciones y las entregas de webhook ya hechas con ella siguen apuntando al mismo merchant. Si dos merchants tienen que volverse uno, habla con el soporte de Rapid.

### `status`

`active` o `inactive`. Es informativo: `inactive` no detiene alertas ni transacciones. Para dejar de recibir alertas de un merchant, [solicita la desactivación](https://doc.rapidchargeback.com/es/canais/enrollments/pedir-desativacao/) de sus enrollments.

---

## Ejemplo de solicitud

Guardar la referencia de tu sistema en un merchant que vino del panel:

```bash
curl -X PATCH https://api.rapidchargeback.com/api/v1/merchants/00000000-0000-0000-0000-000000000001 \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ=" \
  -H "Content-Type: application/json" \
  -d '{ "merchant_ref": "PB-1001" }'
```

---

## Respuesta

### Éxito

```
HTTP/1.1 200 OK
```

```json
{
  "data": {
    "id": "00000000-0000-0000-0000-000000000001",
    "name": "Loja Exemplo",
    "merchant_ref": "PB-1001",
    "status": "active",
    "created_at": "2026-03-10T12:00:00.000Z",
    "updated_at": "2026-11-06T12:00:00.000Z",
    "...": "registro completo"
  },
  "meta": { "result": "updated", "warnings": [] }
}
```

`data` es el registro completo, el mismo de [Consultar merchant](https://doc.rapidchargeback.com/es/canais/merchants/consultar-merchant/). `meta.result` es `updated` o `unchanged` (nada cambió, nada guardado); `meta.warnings` puede traer 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)).

### Referencia ya guardada

```
HTTP/1.1 409 Conflict
```

```json
{
  "error": {
    "code": "MERCHANT_REF_IMMUTABLE",
    "message": "merchant_ref cannot be changed once set"
  }
}
```

### Errores

| HTTP | Código | Cuándo |
|---|---|---|
| 404 | `MERCHANT_NOT_FOUND` | El merchant no existe, es de otra empresa, o el id no es un UUID |
| 409 | `MERCHANT_DUPLICATE` | Otro merchant tuyo ya tiene el nombre |
| 409 | `MERCHANT_REF_IMMUTABLE` | El merchant ya tiene otra referencia |
| 409 | `MERCHANT_REF_TAKEN` | Otro merchant tuyo ya usa la referencia (`params.merchant_id`) |
| 422 | `VALIDATION_ERROR`, `FIELD_REQUIRED`, `FIELD_TOO_LONG`, `FIELD_INVALID`, `FIELD_INVALID_OPTION` | Ver [Crear o actualizar merchant](https://doc.rapidchargeback.com/es/canais/merchants/criar-ou-atualizar-merchant/#errores) |
| 403 | `KYB_NOT_APPROVED`, `COMPANY_NOT_ACTIVE`, `COMPANY_BLOCKED` | Empresa sin registro aprobado, inactiva o bloqueada |
| 429 | `RATE_LIMIT_EXCEEDED` | Más de 60 escrituras por minuto |
| 503 | `SERVICE_UNAVAILABLE` | No disponible temporalmente: repite después del `Retry-After` |

---

## Notas

- **Repetir es seguro:** la misma edición de nuevo vuelve `unchanged`.
- **Actividad:** cada modificación aparece en la Actividad del panel como hecha por la integración.
