Arquitectura general de integración

La arquitectura de YUPY conecta múltiples canales de venta con diferentes medios de pago y una capa central de conciliación bancaria. Su objetivo no es únicamente presentar una experiencia de cobro: debe identificar el dinero recibido, relacionarlo con la operación correcta y automatizar las acciones posteriores.

Principio arquitectónico: los canales pueden ser distintos, pero la orden, la trazabilidad, la evidencia bancaria y la conciliación deben seguir un contrato común.

Visión general

┌──────────────────────────────────────────────┐
│          CANALES Y SISTEMAS DE ORIGEN        │
│                                              │
│ POS vía chat: WhatsApp · Chat YUPY · Otros   │
│ Web · Pasarela · POS integrado · CRM · ERP    │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│         ÓRDENES Y CONTRATO COMÚN YUPY        │
│                                              │
│ Identidad · Monto · Canal · Correlación      │
│ Idempotencia · Comprador · Destino operativo │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│          EXPERIENCIA OMNICANAL DE PAGO       │
│                                              │
│ POS vía chat · Web Checkout · POS integrado  │
│ Estado · “Ya pagué” · Alertas · Reintentos   │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│              MEDIOS DE PAGO                  │
│                                              │
│ Yape · Plin · Transferencias bancarias       │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│       CUENTAS BANCARIAS DE LA EMPRESA        │
│                                              │
│ El dinero llega directamente al comercio     │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│       BANKBRIDGE / CONECTORES BANCARIOS      │
│                                              │
│ Movimientos · Referencias · Fechas · Cuentas │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│            MOTOR DE CONCILIACIÓN             │
│                                              │
│ Coincidencias · Diferencias · Ambigüedades   │
│ Duplicados · Pagos tardíos · Revisión manual │
└──────────────────────┬───────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────┐
│          AUTOMATIZACIÓN DEL NEGOCIO          │
│                                              │
│ Webhooks · POS · Ventas · Administración     │
│ Finanzas · Reportes · Atención · Contabilidad│
└──────────────────────────────────────────────┘

1. Canales y sistemas de origen

Un sistema de origen es cualquier aplicación o canal que necesita cobrar y conocer después el resultado del pago.

Puede ser:

WhatsApp;
el chat propio de YUPY;
otro chat, asistente o bandeja conversacional;
una tienda virtual;
una pasarela o página de pago;
un sistema de reservas;
un POS;
un CRM o ERP;
una aplicación interna;
un proceso operado por vendedores o agentes.

Todos deben poder crear una orden compatible con el mismo núcleo transaccional, aunque la experiencia visible para el comprador sea diferente.

2. Contrato común de la orden

La orden YUPY normaliza la información mínima necesaria para seguir el cobro a través de todos los componentes.

{
  "external_transaction_id": "ORDER-10482",
  "created_at": "2026-07-20T14:30:00-05:00",
  "amount": "85.50",
  "currency": "PEN",
  "channel": "web_checkout",
  "buyer": {
    "first_name": "María",
    "last_name": "Ramos"
  }
}

El esquema definitivo se documentará en el contrato de API. Como mínimo, la arquitectura necesita conservar:

identificador del sistema de origen;
identificador YUPY;
monto y moneda;
fecha y hora;
canal;
comprador;
vendedor, local, turno, POS o destino, cuando corresponda;
cuenta o configuración receptora;
estado y eventos;
movimiento bancario relacionado.

3. API y capa de orquestación

La API recibe solicitudes, valida el contrato y crea una identidad interna estable.

{
  "yupy_transaction_id": "ypt_01JXYZ...",
  "external_transaction_id": "ORDER-10482",
  "status": "created"
}

Entre sus responsabilidades se encuentran:

autenticación;
validación de campos;
idempotencia;
correlación;
selección del canal;
selección de la cuenta o QR aplicable;
registro de eventos;
entrega de respuestas y webhooks.

4. Motor de experiencias omnicanales

Este componente adapta la orden a la modalidad de cobro y al canal utilizado.

POS vía chat

Es la modalidad conversacional de venta y cobro. Administra la orden, el vendedor, el turno, el destino operativo, las acciones del usuario y el seguimiento de la conciliación. Puede funcionar sobre distintos canales:

WhatsApp: canal de conversación y entrega.
Chat propio de YUPY: experiencia conversacional administrada por YUPY.
Otros chats: canales externos conectados mediante API y eventos.

WhatsApp no define la modalidad ni la lógica del POS; es solamente uno de los canales disponibles.

Web Checkout o pasarela

Devuelve una URL segura o componente web para mostrar monto, QR, instrucciones, vigencia y estado.

{
  "checkout": {
    "url": "https://checkout.example/...",
    "token": "token_temporal",
    "expires_at": "2026-07-20T15:30:00-05:00"
  }
}

La URL real, el formato del token y los tiempos definitivos permanecerán como contrato propuesto hasta su implementación.

Integración con un POS existente

Permite que un sistema físico o digital de punto de venta cree la orden, muestre o envíe la experiencia de pago y espere la conciliación antes de cerrar la operación. Esta integración es independiente del POS vía chat.

5. Capa de evidencias auxiliares

YUPY puede recibir información complementaria desde mensajes, imágenes, capturas o constancias de pago. Esta capa puede extraer y ordenar datos como:

monto visible;
fecha y hora;
nombre mostrado;
número de operación;
medio de pago;
referencias disponibles.

Estas señales ayudan a priorizar y explicar una operación, pero no sustituyen la información bancaria conciliada.

6. Medios de pago y flujo económico

La arquitectura inicial contempla Yape, Plin y transferencias bancarias.

Comprador
   ↓
Yape, Plin o transferencia bancaria
   ↓
Cuenta receptora de la empresa
   ↓
Movimiento disponible para YUPY
   ↓
Conciliación con la orden

YUPY no necesita recibir el dinero en una cuenta propia. El flujo económico termina directamente en la empresa y la plataforma trabaja con la información necesaria para identificar el ingreso.

7. BankBridge y conectores bancarios

BankBridge representa la capa que obtiene movimientos de las cuentas autorizadas. Según el banco y el entorno, puede utilizar:

API bancaria;
servicio autorizado;
consulta periódica;
callback o notificación;
simulador para pruebas;
otro conector compatible.

El conector normaliza la información para que el motor de conciliación no dependa de un formato particular de cada banco.

8. Motor de conciliación

Este es el núcleo funcional de YUPY. Compara órdenes pendientes con movimientos detectados y determina si existe una relación suficientemente clara.

Resultado	Significado	Acción
Conciliado	Existe evidencia suficiente para asociar el movimiento con la orden.	Confirmar y notificar.
Pendiente	Todavía no se encontró un movimiento compatible.	Continuar buscando según la política.
Monto diferente	El ingreso no coincide con el monto esperado.	Crear diferencia o enviar a revisión.
Ambiguo	Existen varias órdenes o movimientos igualmente posibles.	No asignar arbitrariamente.
Duplicado	La orden o el movimiento ya fue utilizado o repetido.	Bloquear la doble aplicación y alertar.
Pago tardío	El movimiento apareció después del cierre o vencimiento operativo.	Notificar y aplicar la regla comercial correspondiente.

9. Automatización del negocio

Una conciliación debe producir acciones útiles. Según la integración, YUPY puede:

marcar una venta como pagada;
continuar un checkout;
liberar una reserva;
autorizar una entrega;
actualizar un POS, CRM o ERP;
informar al vendedor;
enviar una confirmación al comprador;
alimentar reportes administrativos;
crear una excepción para revisión;
registrar diferencias o devoluciones.

Esta automatización posterior es la que convierte la conciliación en ahorro real de trabajo.

10. Eventos y webhooks

Los cambios relevantes se representan como eventos y pueden notificarse al sistema de origen.

payment_order.created
checkout.created
checkout.opened
payment.reported
payment.verification_pending
payment.not_found
payment.amount_difference
payment.ambiguous
payment.reconciled
payment.expired
payment.cancelled
payment.late_detected
refund.requested
refund.pending
refund.completed

Este catálogo es una propuesta inicial. Los nombres y payloads definitivos se aprobarán junto con el contrato de integración.

Tres dimensiones de estado

Una sola etiqueta no puede describir correctamente toda la operación. La arquitectura propone separar:

Estado operativo

created
active
expired
cancelled
closed

Estado financiero o de conciliación

awaiting_payment
payment_reported
movement_detected
reconciliation_pending
reconciled
amount_difference
ambiguous
not_found
late_detected

Estado del canal o entrega

pending
sent
delivered
opened
failed

Esta separación permite representar, por ejemplo, una experiencia vencida que recibe un pago tardío y termina conciliándose después.

Fuente de verdad

La fuente de verdad financiera es el movimiento bancario correctamente conciliado. El canal, el mensaje, la captura y el botón Ya pagué son señales operativas o auxiliares.

Resultado arquitectónico

Múltiples canales
   → una orden normalizada
   → múltiples medios de pago
   → dinero directo en la empresa
   → una capa bancaria común
   → conciliación centralizada
   → automatización de ventas, administración y operaciones

API Technical Docs