Sign API

Descripción general

La Sign API de Redtrust es una API REST que permite integrar la firma de documentos con certificados digitales gestionados de forma centralizada en Redtrust. Está diseñada para aplicaciones externas que necesitan autenticar usuarios, recuperar sus certificados, ejecutar operaciones de firma y gestionar el perfil de firma del usuario.

URL base

https://TU_IP_REDTRUST:PUERTO/signapi

El puerto por defecto es 8083. Por ejemplo: https://localhost:8083/signapi/v1/certificate/list.

Autenticación

Token de acceso

Todos los endpoints de la Sign API requieren un token de acceso en la cabecera Authorization:

Authorization: Bearer TU_ACCESS_TOKEN

Hay dos formas de obtener ese token, según el tipo de integración:

Flujo de login de Sign Service

Este es el flujo descrito en detalle en Integración con Sign Service. En resumen:

1. Tu aplicación redirige al usuario a GET /authclient/auth/loginrequest con los parámetros del partner (incluyendo la firma HMAC).
2. El usuario se autentica en Redtrust (o en su proveedor de identidades externo).
3. Redtrust redirige al usuario a tu URL de retorno con un token temporal (tkn).
4. Tu aplicación intercambia ese token temporal por un token de acceso llamando a POST /authapi/v1/login_by_temp_token.

Flujo de código de autorización OAuth2

Este es el flujo estándar OAuth2. Sigue el mismo patrón de redirección, pero usa los endpoints estándar:

1. Tu aplicación redirige al usuario a GET /authclient/authorize con client_id, redirect_uri, response_type=code, state y los parámetros PKCE (code_challenge y code_challenge_method).
2. El usuario se autentica.
3. Redtrust redirige al usuario a tu URL de retorno con un código de autorización (code).
4. Tu aplicación intercambia ese código por un token de acceso llamando a POST /authclient/token.

En ambos casos, el resultado es un token de acceso que debes incluir en la cabecera Authorization de todas las llamadas a la Sign API.

tip

El flujo OAuth2 es el recomendado para integraciones nuevas, ya que sigue un estándar ampliamente adoptado y permite renovar la sesión con un token de refresco.

aviso

Requisito previo: el flujo OAuth2 solo funciona si el administrador de Redtrust ha registrado previamente tu URI de redirección. Consulta Configurar las URI de redirección.

Parámetros del flujo OAuth2

Este flujo implementa PKCE (Proof Key for Code Exchange) para prevenir ataques de intercepción de código.

Solicitud de autorización

GET /authclient/authorize

Parámetro	Requerido	Descripción
response_type	Sí	Debe ser code.
client_id	Sí	Identificador de tu aplicación. Redtrust te lo asigna al registrar tu aplicación.
redirect_uri	Sí	URL a la que Redtrust redirige al usuario tras la autenticación. Debe coincidir exactamente con una de las URI de redirección registradas para el servicio en la consola de administración.
code_challenge	Sí	Challenge PKCE derivado del code_verifier. Entre 43 y 128 caracteres en formato base64url.
code_challenge_method	Sí	Método de transformación del challenge. El único valor admitido es S256.
state	Sí	Valor aleatorio que tu aplicación genera para prevenir ataques CSRF. Entre 16 y 512 caracteres. Redtrust lo devuelve sin modificar en la redirección.
domain	No	Dominio del usuario. Si se omite, el usuario puede seleccionarlo durante la autenticación.

Intercambio de código por token

POST /authclient/token con cuerpo application/x-www-form-urlencoded:

Parámetro	Requerido	Descripción
grant_type	Sí	Debe ser authorization_code.
client_id	Sí	El mismo client_id de la Solicitud de autorización.
redirect_uri	Sí	La misma URL de redirección de la Solicitud de autorización.
code	Sí	El código de autorización recibido en la redirección.
code_verifier	Sí	El valor original del code_verifier PKCE generado por tu aplicación antes de calcular el code_challenge.

El servidor responde con:

{
  "access_token": "...",
  "token_type": "Bearer",
  "refresh_token": "..."
}

Renovación del token

Cuando el token de acceso expira, puedes renovarlo sin que el usuario vuelva a autenticarse. Llama a POST /authclient/token con:

Parámetro	Requerido	Descripción
grant_type	Sí	Debe ser refresh_token.
client_id	Sí	Identificador de tu aplicación.
refresh_token	Sí	El token de refresco recibido en la respuesta anterior.

Cabeceras HMAC

Además del token de acceso, cada instalación de Redtrust puede requerir cabeceras HMAC para validar la identidad del partner en cada llamada a la API. Si están habilitadas, debes incluirlas en todas las solicitudes:

Cabecera	Descripción
x-partner-name	Nombre de la aplicación cliente en mayúsculas. Sirve para identificar y autorizar al partner que realiza la llamada.
x-request-timestamp	Timestamp UNIX que indica cuándo se hace la solicitud. Ayuda a prevenir ataques de repetición.
x-hmac-signature	Firma HMAC-SHA256 generada firmando el mensaje NOMBRE_PARTNER:TIMESTAMP_UNIX con la clave compartida entre el partner y Redtrust.

La validación HMAC puede deshabilitarse desde la configuración de la instalación. Consulta con el administrador de Redtrust si tu integración la requiere.

Formato de respuesta

Todos los endpoints devuelven la siguiente estructura JSON:

{
  "message": "string",
  "messageType": "SUCCESS",
  "errorCode": "string",
  "data": {}
}

Campo	Descripción
message	Mensaje descriptivo del resultado.
messageType	SUCCESS si la operación se completó correctamente; ERROR si se produjo algún problema.
errorCode	Código identificativo del error, o OK cuando la operación es correcta.
data	Contenido de la respuesta. El tipo varía según el endpoint — puede ser un objeto, una lista o estar vacío.