Autenticación y credenciales de integración

Estado documental: Contrato propuesto. Las rutas, tiempos y mecanismos de autenticación pasan a estado confirmado únicamente después de su implementación y verificación.

Principio general

YUPY genera las credenciales privadas de integración.

La empresa puede solicitar su creación, rotación o revocación, consultar su estado y determinar qué sistemas y responsables pueden utilizarlas. La empresa no define manualmente el valor secreto.

La empresa solicita una credencial
        ↓
YUPY genera un secreto seguro
        ↓
YUPY lo entrega una sola vez
        ↓
La empresa lo almacena en su servidor

Separación por ambiente

Sandbox
Producción

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

Separación por integración

Cuando una empresa conecta más de un sistema, YUPY puede entregar credenciales independientes.

Empresa
├── Comercio electrónico
├── Sistema de ventas
├── POS vía chat
├── ERP
└── Servicio de reportes

Esto permite rotar o revocar una integración sin afectar a las demás.

Componentes propuestos

client_id
client_secret
integration_id
environment
status
created_at
last_rotated_at

El client_id puede volver a consultarse. El client_secret se muestra o entrega una sola vez.

Secreto perdido
→ no se recupera
→ YUPY genera uno nuevo
→ se ejecuta una rotación

Entrega segura

La entrega inicial puede realizarse mediante:

• visualización única en consola;
• archivo cifrado;
• gestor seguro de secretos;
• canal protegido acordado durante el onboarding.

El secreto completo no debe enviarse mediante WhatsApp, correo abierto, documentos sin protección, capturas, tickets ni archivos públicos.

Almacenamiento

La empresa debe guardar el secreto en un gestor de secretos, variables protegidas del servidor, almacén cifrado o infraestructura equivalente.

No debe incluirse en:

JavaScript frontend
HTML
aplicaciones móviles
repositorios Git
URLs
logs
capturas
documentación pública

Uso server-to-server

Navegador del comprador
    ✕ no conoce client_secret

Backend de la empresa
    ✓ utiliza la credencial

YUPY
    ✓ autentica la integración

Obtención de token

Endpoint propuesto:

POST <YUPY_API_BASE_URL>/v1/auth/token
Content-Type: application/json

Solicitud:

{
  "client_id": "<YUPY_CLIENT_ID>",
  "client_secret": "<YUPY_CLIENT_SECRET>"
}

Ejemplo:

curl --request POST \
  --url '<YUPY_API_BASE_URL>/v1/auth/token' \
  --header 'Content-Type: application/json' \
  --data '{
    "client_id": "<YUPY_CLIENT_ID>",
    "client_secret": "<YUPY_CLIENT_SECRET>"
  }'

Respuesta propuesta:

{
  "access_token": "<OPAQUE_ACCESS_TOKEN>",
  "token_type": "Bearer",
  "expires_in_seconds": 3600,
  "expires_at": "2026-07-20T15:00:00-05:00",
  "environment": "sandbox"
}

Uso posterior:

Authorization: Bearer <ACCESS_TOKEN>

La duración definitiva del token queda pendiente de confirmación.

Elementos separados

client_secret
≠ access_token
≠ secreto de firma de webhooks
≠ token de checkout
≠ código público de transacción
≠ external_transaction_id

El token de Web Checkout permite abrir una experiencia temporal. No permite utilizar la API privada.

Rotación

1. La empresa solicita la rotación.
2. YUPY genera una nueva credencial.
3. La nueva credencial se entrega una sola vez.
4. La empresa la instala y prueba.
5. Ambas pueden coexistir durante una transición.
6. La empresa confirma el cambio.
7. YUPY revoca la credencial anterior.

La duración de la transición se acuerda con cada empresa.

Revocación inmediata

Puede solicitarse o ejecutarse ante exposición, pérdida, cambio de proveedor, salida de un responsable, uso indebido o desactivación de la integración.

HTTP/1.1 401 Unauthorized

{
  "error": {
    "code": "credential_revoked",
    "message": "La credencial de integración fue revocada.",
    "request_id": "req_01JXYZ"
  }
}

Criterios de aceptación

1. YUPY genera los secretos.
2. La empresa puede solicitar rotación y revocación.
3. El secreto se entrega una sola vez.
4. Sandbox y producción usan credenciales distintas.
5. Las credenciales son server-to-server.
6. El navegador no recibe secretos.
7. Un secreto perdido se reemplaza.
8. La rotación puede tener transición controlada.
9. La revocación puede ser inmediata.
10. El secreto de API se mantiene separado del secreto de webhooks.