Seguridad de la integración

Estado documental: Contrato propuesto. Los controles descritos pasan a estado implementado o verificado únicamente después de su implementación y validación.

Objetivo

Esta página define las responsabilidades mínimas de seguridad para integrar y operar YUPY. Su alcance comprende credenciales, API, Web Checkout, webhooks, usuarios, dispositivos, evidencias, reportes y respuesta ante incidentes.

1. Responsabilidad compartida

Responsabilidades de YUPY

• autenticar las integraciones autorizadas;
• separar los ambientes de sandbox y producción;
• limitar el acceso según permisos y funciones;
• proteger las sesiones temporales de Web Checkout;
• firmar los webhooks;
• mantener trazabilidad y auditoría;
• evitar la exposición innecesaria de datos;
• permitir la rotación y revocación de credenciales;
• aplicar controles contra abuso, duplicados y actividad anómala;
• informar al cliente cuando una acción requiera su intervención.

Responsabilidades de la empresa

• guardar de forma segura sus credenciales y secretos;
• mantener los secretos únicamente en sistemas backend controlados;
• controlar quién accede a la consola y a los reportes;
• proteger sus servidores, aplicaciones y dispositivos;
• validar la firma de los webhooks;
• procesar órdenes y eventos de forma idempotente;
• desactivar accesos que ya no correspondan;
• revisar las decisiones operativas antes de ejecutar devoluciones;
• reportar inmediatamente cualquier incidente o sospecha de exposición.

2. Credenciales y secretos

Los siguientes valores deben tratarse como secretos:

client_secret
access_token
webhook_secret
credenciales administrativas
tokens temporales no destinados a exposición pública

El client_id identifica la integración, pero no sustituye al secreto ni debe utilizarse como único mecanismo de autenticación.

Los secretos no deben almacenarse en

JavaScript público
HTML
aplicaciones móviles distribuidas
repositorios de código
capturas de pantalla
tickets públicos
logs sin protección
mensajes de chat
documentación compartida sin control de acceso

Prácticas recomendadas

• utilizar variables de entorno o un gestor de secretos;
• restringir el acceso a las credenciales por función;
• entregar el client_secret una sola vez cuando sea posible;
• rotar las credenciales ante sospecha de exposición;
• revocar inmediatamente las credenciales comprometidas;
• no reutilizar una credencial entre empresas distintas;
• no copiar credenciales de sandbox a producción.

3. Separación de ambientes

Sandbox
≠ Producción

Cada ambiente debe mantener, como mínimo:

• base URL propia;
• credenciales propias;
• datos separados;
• endpoints de webhook separados;
• secretos de firma separados;
• configuración de integración independiente.

Una credencial de sandbox no debe funcionar en producción.

4. Comunicación segura

La comunicación con YUPY debe utilizar HTTPS válido.

Esto aplica a:

• API;
• Web Checkout;
• consola;
• carga de evidencias;
• webhooks;
• descargas de reportes;
• enlaces temporales.

La integración no debe transmitir secretos, datos de autenticación ni evidencias mediante conexiones inseguras.

5. Seguridad del Web Checkout

El checkout_url contiene un token temporal y limitado a una experiencia concreta.

Ese token:

• no es una credencial general de API;
• no autoriza operaciones administrativas;
• tiene una vigencia limitada;
• puede ser revocado;
• no debe reutilizarse para otra operación;
• no debe publicarse en logs, analítica o enlaces compartidos sin control;
• debe sustituirse por una nueva sesión cuando corresponda.

El vencimiento de la sesión no elimina la orden ni impide que YUPY identifique posteriormente un pago realizado por el comprador.

El comprador nunca debe recibir

client_secret
access_token server-to-server
webhook_secret
credenciales bancarias
credenciales administrativas

6. Seguridad de webhooks

La empresa debe seguir el contrato documentado en la sección Webhooks.

El receptor debe:

1. conservar el cuerpo original recibido;
2. validar la firma;
3. comprobar el timestamp;
4. registrar el event_id;
5. evitar efectos comerciales duplicados;
6. responder rápidamente con HTTP 200 cuando el evento haya sido recibido correctamente;
7. procesar el efecto comercial de manera asíncrona cuando corresponda.

Sobre canónico

{
  "event_id": "evt_01JXYZ",
  "event_type": "payment.reconciled",
  "event_version": "1.0",
  "created_at": "2026-07-20T18:00:00-05:00",
  "data": {
    "yupy_transaction_id": "ypt_01JXYZ",
    "external_transaction_id": "ORDER-10482"
  }
}

Headers propuestos

Yupy-Event-Id
Yupy-Timestamp
Yupy-Signature

Una firma inválida, ausente o no verificable debe provocar el rechazo del evento y no debe cambiar el estado comercial de la operación.

Los nombres de headers, algoritmo y tolerancia temporal permanecen como contrato propuesto hasta su implementación y verificación.

7. Idempotencia y protección contra duplicados

La seguridad operativa también exige evitar efectos repetidos.

La empresa debe utilizar:

Idempotency-Key
external_transaction_id
event_id

Estos identificadores ayudan a evitar:

• crear dos órdenes por un reintento;
• procesar dos veces un webhook;
• confirmar dos veces una venta;
• registrar dos veces una devolución;
• ejecutar dos veces una acción administrativa.

Los reintentos deben conservar la misma Idempotency-Key y el mismo payload cuando representan la misma solicitud.

8. Usuarios, roles y dispositivos

YUPY debe aplicar el principio de mínimo privilegio: cada persona accede únicamente a lo necesario para su función.

Roles conceptuales:

administrator
integration_manager
operations_supervisor
seller
report_viewer
refund_reviewer

Los nombres definitivos pueden cambiar, pero la separación de responsabilidades debe mantenerse.

Ejemplos de separación

• un vendedor no necesita administrar credenciales;
• un usuario de reportes no necesita aprobar devoluciones;
• un supervisor puede revisar pendientes sin modificar la integración;
• solo personas autorizadas pueden rotar secretos o cambiar webhooks;
• las devoluciones requieren permisos específicos.

POS vía chat

• cada usuario debe identificarse;
• cada turno debe quedar vinculado a una persona y un dispositivo;
• cada dispositivo debe registrarse y poder desactivarse;
• un usuario no debe utilizar la identidad de otro;
• el cierre de turno no elimina pendientes ni interrumpe la conciliación.

9. Evidencias y archivos

Las capturas y constancias pueden contener información personal o financiera.

YUPY y la empresa deben:

• admitir únicamente formatos permitidos;
• limitar el tamaño de los archivos;
• validar el contenido recibido;
• restringir el acceso según permisos;
• mantener trazabilidad;
• evitar URLs públicas permanentes;
• no incluir archivos completos en logs;
• aplicar la política de conservación acordada con la empresa.

La información extraída mediante OCR debe limitarse a lo necesario para la operación. OCR no confirma por sí solo que el dinero haya sido recibido.

10. Datos personales y minimización

La integración debe enviar únicamente la información necesaria para cobrar, conciliar y atender la operación.

Datos mínimos habituales

external_transaction_id
amount
buyer_name

Datos opcionales

correo
teléfono
ruta
asiento
pedido
reserva
otras referencias comerciales

La empresa no debe enviar:

• contraseñas;
• claves bancarias;
• secretos de API;
• números completos de tarjetas;
• documentos innecesarios;
• información sensible que no contribuya al proceso de cobro o conciliación.

La información de una empresa no debe ser visible para otra empresa.

11. Logs y auditoría

Los logs deben permitir investigar una operación sin revelar secretos.

Datos que pueden registrarse

request_id
integration_id
endpoint
HTTP status
fecha y hora
duración
resultado
event_id
yupy_transaction_id
external_transaction_id

Datos que deben redactarse o excluirse

client_secret
access_token
webhook_secret
firmas completas
credenciales bancarias
archivos completos
datos personales innecesarios

Acciones auditables

• creación, rotación y revocación de credenciales;
• accesos administrativos;
• cambios de configuración;
• creación y cancelación de órdenes;
• decisiones manuales;
• aprobación y registro de devoluciones;
• entregas de webhooks;
• exportaciones y descargas de reportes;
• activación y desactivación de usuarios y dispositivos.

12. Límites y protección contra abuso

La plataforma puede aplicar:

• rate limiting;
• límites de tamaño;
• límites de paginación;
• límites de carga de archivos;
• bloqueo temporal;
• revocación de credenciales;
• validación de endpoints de webhook;
• controles adicionales ante actividad anómala.

La empresa debe manejar correctamente:

429 rate_limit_exceeded
503 service_unavailable

Los reintentos deben incorporar espera progresiva y no deben producir una tormenta de solicitudes.

Los límites exactos permanecen propuestos hasta su implementación y publicación en el contrato correspondiente.

13. Gestión de incidentes

Se detecta o sospecha una exposición
        ↓
Se revoca la credencial
        ↓
Se genera una nueva
        ↓
Se actualiza la integración
        ↓
Se revisan logs y operaciones
        ↓
Se documenta el incidente

La empresa debe contactar a YUPY cuando detecte:

• una credencial filtrada;
• un webhook desconocido;
• un usuario no autorizado;
• actividad inesperada;
• duplicados;
• evidencia alterada;
• pérdida o robo de un dispositivo;
• sospecha de manipulación de una operación.

Cuando exista riesgo activo, la prioridad es revocar o desactivar el acceso afectado antes de continuar con el análisis.

14. Información que no forma parte del contrato público

La documentación del cliente no publica:

topología de servidores
IPs internas
puertos
nombres de servicios
rutas del servidor
configuración de firewall
proveedores internos
algoritmos antifraude
métodos internos de conciliación
estructura de base de datos
detalles privados de conexión bancaria
certificados o claves reales
procedimientos internos de recuperación

Esta página tampoco declara certificaciones, SLA, estándares o pruebas formales que no hayan sido implementados y verificados.

15. Checklist de producción

[ ] Los secretos están almacenados en backend.
[ ] Sandbox y producción están separados.
[ ] Las credenciales de producción son exclusivas.
[ ] Los webhooks validan firma y timestamp.
[ ] Los event_id se deduplican.
[ ] Las creaciones utilizan Idempotency-Key.
[ ] Los usuarios tienen permisos mínimos.
[ ] Los dispositivos pueden desactivarse.
[ ] Las evidencias no son públicas.
[ ] Los logs redactan secretos.
[ ] Existe un procedimiento de revocación.
[ ] Existe un responsable técnico para incidentes.

Criterios de aceptación documental

1. La responsabilidad de YUPY y de la empresa queda separada.
2. Los secretos permanecen en sistemas backend controlados.
3. Sandbox y producción utilizan credenciales independientes.
4. API, checkout, webhooks y evidencias utilizan HTTPS.
5. El token de checkout no se presenta como credencial general.
6. Los webhooks validan firma, timestamp e idempotencia.
7. Los usuarios aplican mínimo privilegio.
8. Las evidencias y datos personales se minimizan y restringen.
9. Los logs no exponen secretos.
10. Existe un procedimiento de revocación y respuesta ante incidentes.
11. No se publica infraestructura interna.
12. No se declaran certificaciones no verificadas.