Notificaciones

Koywe emite notificaciones para mantener informados a los usuarios del merchant sobre eventos de órdenes — separadas de los webhooks, que están pensados para integraciones servidor-a-servidor.

Existen dos canales independientes, configurables por merchant:

• Notificaciones in-app: se entregan a los usuarios con sesión iniciada en el dashboard de Koywe. Siempre activas.
• Notificaciones por correo: opt-in. Desactivadas por defecto; habilítalas y elige los destinatarios por merchant.

Notificaciones In-App

Las notificaciones in-app se generan automáticamente solo ante eventos de órdenes — eventType utiliza el subconjunto order.* de la taxonomía de webhooks (p. ej. order.completed, order.failed) y no abarca merchant.*, policy.*, webhook.ping ni otras familias. Cada notificación pertenece a un único merchant y puede listarse, contarse y marcarse como leída a través de la API que alimenta el centro de notificaciones del dashboard.

Objeto de Notificación

{
  "id": "d2dd8481-3552-4466-b99e-a7caad69a302",
  "merchantId": "koywe-3-sys",
  "orderId": "ord_abc123",
  "orderType": "PAYIN",
  "eventType": "order.completed",
  "title": "Tu pago se completó",
  "body": "El pago de $500 USD fue procesado correctamente.",
  "read": false,
  "readAt": null,
  "createdAt": "2026-04-13T18:00:00.000Z",
  "metadata": null
}

Listar Notificaciones

GET /api/v1/merchants/{merchantId}/notifications/inapp

Paginado, de la más reciente a la más antigua.

Parámetros de consulta

const response = await axios.get(
  `https://api.koywe.com/api/v1/merchants/${merchantId}/notifications/inapp`,
  {
    params: { page: 1, limit: 50 },
    headers: { Authorization: `Bearer ${token}` }
  }
);
 
const { data, total, page, limit } = response.data;

Conteo de No Leídas

GET /api/v1/merchants/{merchantId}/notifications/inapp/unread-count

Devuelve { "count": 3 }. Úsalo para el badge del ícono de campana — es más económico que paginar la lista completa.

Marcar Una como Leída

PATCH /api/v1/merchants/{merchantId}/notifications/inapp/{notificationId}/read

Devuelve { "ok": true }.

Marcar Todas como Leídas

PATCH /api/v1/merchants/{merchantId}/notifications/inapp/read-all

Devuelve { "updated": 5 } — la cantidad de notificaciones que pasaron de no-leídas a leídas.

Configuración de Notificaciones por Correo

Las notificaciones por correo están desactivadas por defecto. Habilítalas por merchant y define una lista de direcciones destinatarias. Koywe luego envía correos a esos destinatarios en cada evento de orden, en paralelo a la notificación in-app y el webhook.

Obtener Configuración

GET /api/v1/merchants/{merchantId}/notification-settings

Devuelve la configuración existente, o los valores por defecto si aún no se ha configurado nada:

{
  "emailEnabled": false,
  "recipients": []
}

Actualizar Configuración

PUT /api/v1/merchants/{merchantId}/notification-settings

{
  "emailEnabled": true,
  "recipients": ["ops@merchant.com", "finance@merchant.com"]
}

Reglas:

• emailEnabled es requerido.
• Cuando emailEnabled es true, debe proporcionarse al menos un correo válido en recipients.
• Cuando emailEnabled es false, recipients puede omitirse y se conservará la lista existente hasta que la vacíes explícitamente.
• Si envías recipients, reemplaza por completo la lista anterior. Para vaciar la lista, envía un arreglo vacío (recipients: []); omitirla no limpia a los destinatarios ya configurados.

await axios.put(
  `https://api.koywe.com/api/v1/merchants/${merchantId}/notification-settings`,
  {
    emailEnabled: true,
    recipients: ['ops@merchant.com', 'finance@merchant.com']
  },
  { headers: { Authorization: `Bearer ${token}` } }
);

¿Cuándo Usar Qué?

Los tres canales son independientes — un evento de orden dispara los tres donde estén configurados.

Próximos Pasos