> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.sellercenter.pe/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.sellercenter.pe/_mcp/server.

# Webhooks

Seller Center puede **notificarte en línea** cuando ocurre un evento, en lugar de que consultes periódicamente.

### Cómo suscribirte

Indica la URL y los tópicos en el [formulario de solicitud](https://form.jotform.com/263074591114050): en la solicitud de **Credenciales de QA** para QA, y en la de **Pase a producción** para PRD. Para cambiarlos después, escríbele a tu contacto de Intercorp Retail. En cada caso necesitas:

1. La **URL** de tu endpoint.
2. Los **tópicos** que quieres recibir (puedes usar la misma URL para varios).

### Requisitos de tu endpoint

* Método **POST**, recibe JSON.
* Debe responder **`2xx` en menos de 10 segundos.** Procesa en segundo plano si tu lógica tarda más.
* Seller Center **no envía** headers de autenticación (apiKey, token). Si quieres proteger tu endpoint, incluye un secreto en la URL: `https://tusitio.pe/webhooks/sellercenter?key=TU_SECRETO`.
* Debe ser **idempotente**: puedes recibir la misma notificación más de una vez.

### Reintentos

Si tu endpoint no responde `2xx` (o tarda más de 10 s), Seller Center reintenta **10 veces durante las siguientes 12 horas**. Luego la notificación se marca como fallida.

> Como respaldo, consulta periódicamente **Listar órdenes** para recuperar eventos que hayas perdido.

### Headers que recibirás

| Header                     | Ejemplo                                      | Descripción                                                                                                                                                                    |
| -------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-SellerCenter-Topic`     | `ORDER_READY_FOR_HANDLING`                   | Tópico del evento.                                                                                                                                                             |
| `X-SellerCenter-Domain`    | `https://inretailqa.mysellercenter.com` (QA) | Origen de la notificación.                                                                                                                                                     |
| `X-SellerCenter-Signature` | `VFJJQVRITE9OOmh0dHBz...`                    | Base64 de `accountName:<URL registrada>` (p. ej. `MITIENDA:https://tusitio.pe/webhooks/sellercenter?key=...`). Puedes compararlo con el valor esperado para validar el origen. |
| `Content-Type`             | `application/json`                           | —                                                                                                                                                                              |

### Tópicos

**Órdenes** (el payload es la **orden completa**, con la misma estructura del *Detalle de orden*):

| Tópico                     | Cuándo se envía                                           |
| -------------------------- | --------------------------------------------------------- |
| `ORDER_READY_FOR_HANDLING` | Nueva orden pagada, lista para atender.                   |
| `ORDER_HANDLING`           | La orden pasó a preparación.                              |
| `ORDER_INVOICE`            | La orden fue facturada y entregada al operador logístico. |
| `ORDER_DELIVERY`           | Entregada al cliente (domicilio) o en tienda.             |
| `ORDER_PENDING_WITHDRAWAL` | Pendiente de retiro en tienda.                            |
| `ORDER_RETIRED`            | Retirada por el cliente.                                  |
| `ORDER_CANCEL`             | Cancelada. **No debe atenderse.**                         |
| `ORDER_IN_ANNULMENT`       | Se inició una solicitud de anulación.                     |
| `ORDER_IN_RETURN`          | Se inició una solicitud de devolución.                    |
| `ORDER_RETURNED`           | Orden devuelta.                                           |

**Controversias:**

| Tópico                 | Cuándo se envía                                                                                               | Payload                                                                                                                                               |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CONTROVERSY_CREATION` | Se creó una controversia (queja, reclamo, solicitud de anulación, devolución o cambio) en una de tus órdenes. | La controversia: `id`, `type`, `orderId`, `text`, `state[]`, `controversyStatus`, `responsible`, `userTypeControversy` (`SELLER` o `ADMIN`), `monto`. |

### Tipos de controversia (`type`)

| Tag   | Nombre                                                           |
| ----- | ---------------------------------------------------------------- |
| `DY`  | Delivery exitoso                                                 |
| `CT`  | Controversia abierta de cualquier tipo                           |
| `DR`  | Solicitud de devolución                                          |
| `EC`  | Error del cliente                                                |
| `PI`  | Primer despacho infructuoso                                      |
| `DI`  | Despacho infructuoso (segundo intento)                           |
| `DX`  | Devolución – Entrega incompleta                                  |
| `DE`  | Devolución – Entrega de producto errado                          |
| `DP`  | Devolución – Error en elección del producto                      |
| `DF`  | Devolución – Producto fallado                                    |
| `DN`  | Devolución – Producto no cumple expectativas                     |
| `DD`  | Devolución – Características no coinciden con la descripción     |
| `DC`  | Devolución – Compra duplicada                                    |
| `DO`  | Devolución – Cambio de opinión                                   |
| `DB`  | Devolución – Pedido abandonado por el cliente (retiro en tienda) |
| `AC`  | Anulación – Desistimiento del cliente                            |
| `AI`  | Anulación – Datos insuficientes del cliente                      |
| `AR`  | Anulación – Despacho rechazado                                   |
| `AZ`  | Anulación – Zona inaccesible                                     |
| `AE`  | Anulación – Error en elección de producto                        |
| `AS`  | Anulación – Quiebre de stock                                     |
| `AD`  | Anulación – Compra duplicada                                     |
| `AO`  | Anulación – No contacto con el cliente                           |
| `AL`  | Anulación – Inconformidad con el flete                           |
| `AF`  | Anulación – Fraude                                               |
| `AB`  | Anulación – Incumplimiento de entrega                            |
| `AP`  | Anulación – Producto no recogido por el operador logístico       |
| `S`   | Siniestro                                                        |
| `CDD` | Cambio – Fecha de entrega                                        |
| `CPF` | Cambio – Producto fallado                                        |
| `CSC` | Cambio – Solicitud del cliente                                   |
| `CR`  | Cambio – Entrega errada                                          |
| `CPE` | Comprobante de pago errado                                       |
| `NRH` | Seller no inició manejo                                          |
| `SNA` | Seller no aceptó el pedido                                       |
| `PNC` | Producto no conforme                                             |
| `ST`  | Servicio técnico                                                 |
| `LDR` | Libro de reclamaciones                                           |