Conceptos

Riversoft® STCP DirectLink API actúa en nombre de los usuarios de transferencia de Riversoft STCP DirectLink: cada llamada autenticada usa el buzón del usuario para enviar, recibir y compartir archivos. Esta página reúne lo que necesita saber antes de integrar. Para el buzón, las reglas de transferencia y el enrutamiento, vea los conceptos de Riversoft STCP DirectLink.

URL base y host

Todas las llamadas usan el prefijo de versión /directlink/v2:

https://{host}/directlink/v2

Use exactamente el host configurado para el servicio, proporcionado por el administrador del entorno. La API puede rechazar la solicitud (HTTP 403) cuando el host o el puerto enviados por el cliente no corresponden a la dirección configurada. Por eso, evite acceder al servicio por dirección IP o por un nombre alternativo.

Control de versiones

La versión de la API forma parte de la ruta (v2) y se informa en el campo apiver de las respuestas, junto con la versión del producto (por ejemplo, v2 (9.0.1)). Esta documentación describe la versión v2, disponible a partir de Riversoft STCP DirectLink 9.0.1. La versión v1 ya no se atiende; vea Migración de la v1 a la v2.

Métodos de autenticación

La API ofrece cuatro formas de autenticar a un usuario. Todas dan como resultado una credencial de sesión que se usa en las rutas protegidas.

Consulte cómo elegir y usar cada método en Autenticación.

Credenciales en las rutas protegidas

Las rutas protegidas aceptan la credencial de sesión de dos formas:

Cuando se envían ambas, prevalece la cabecera Authorization. Detalles en Sesión y cierre de sesión.

Flujo de una integración

    flowchart TD
    A[Cliente] --> B{Método de autenticación}
    B -->|Inicio de sesión local| C[POST /auth/login con Basic]
    C --> D{¿MFA habilitado?}
    D -->|Sí| E[Validar desafío en /auth/mfa]
    D -->|No| F[Sesión autenticada]
    E --> F
    B -->|OAuth 2.0| G[POST /auth/token o /oauth2/token]
    G --> F
    B -->|SSO| H[Redirigir al proveedor]
    H --> I[Callback OAuth 2.0 o SAML 2.0]
    I --> F
    F --> K{Operación}
    K -->|Enviar| L[POST /upload]
    K -->|Recibir| M[GET /download/list]
    M --> N[GET linkURL devuelto]
    K -->|Consultar| O[GET /report]
    L --> Q[POST /auth/logout o cierre de sesión SSO]
    N --> Q
    O --> Q
  

Las descargas mediante enlace compartido siguen una validación propia y no requieren que el destinatario inicie una sesión. Consulte Enlaces compartidos.

Enlaces seguros

Algunas respuestas incluyen URL emitidas por el servicio, en general en el campo linkURL:

Los enlaces seguros:

• están firmados y vinculados a la operación, al usuario y al archivo para los cuales se crearon;
• tienen un plazo de validez definido por el administrador (de forma predeterminada, 24 horas para los enlaces de descarga y 180 segundos para los PIN) y pueden requerir un PIN;
• dejan de funcionar cuando el archivo ya no está disponible.

Use cada enlace exactamente como lo recibió. No elimine, edite ni construya manualmente sus parámetros, y trátelo como una credencial.

Reglas de acceso

Una credencial válida no garantiza que toda operación se autorice. Cada operación también se valida según las reglas configuradas para el usuario y para el entorno, por ejemplo:

• servicio de envío o descarga habilitado para el usuario;
• usuario desbloqueado y autorizado;
• horario o intervalo de acceso permitido;
• límites de tamaño, tipos de archivo y filtros de nombre;
• límite de sesiones simultáneas y disponibilidad del recurso;
• éxito de las etapas de preprocesamiento configuradas en el entorno.

Cuando una de estas reglas impide la operación, la API responde con un error (generalmente 403). Consulte al administrador del servicio qué reglas se aplican a su usuario.

Formatos de datos

Fechas y horas: el campo timestamp del health check usa RFC 3339 en UTC; el campo modified de los listados usa Unix time en milisegundos. El formato de los demás campos de fecha (como time) lo define el entorno.

Envoltorio de respuesta

La mayoría de las operaciones responde con un objeto JSON con campos comunes:

{
  "status": 0,
  "description": "<descripción devuelta por la API>",
  "apiver": "v2 (9.0.1)",
  "user": "<usuario>",
  "time": "<fecha y hora>"
}

Cada operación agrega sus propios campos. Los endpoints de token siguen el formato OAuth 2.0 y no usan este envoltorio. Consulte Modelos de datos.

El formato del cuerpo de error varía entre los endpoints: trate primero el status HTTP y, cuando exista, use la descripción devuelta. Vea Códigos y eventos.