Definición de Endpoints de la API REST

A continuación se presenta la definición completa de los endpoints de la API REST. La documentación está en español, pero los endpoints, así como los nombres de los parámetros de entrada y salida, se mantienen en inglés.

---

1. Autenticación

1.1 Obtener Token de Acceso

Endpoint: POST /api/v1/auth/token Descripción: Permite a las aplicaciones cliente autenticarse y obtener un token de acceso mediante OAuth2. Encabezados:

• Content-Type: application/json

Cuerpo de la Solicitud:

  {
    "grant_type": "password",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "username": "your_username",
    "password": "your_password"
  }

Respuesta Exitosa (HTTP 200):

    {
      "access_token": "ACCESS_TOKEN_VALUE",
      "token_type": "Bearer",
      "expires_in": 3600,
      "refresh_token": "REFRESH_TOKEN_VALUE",
      "scope": "sign"
    }
    

1.2 Refrescar Token de Acceso

Endpoint: POST /api/v1/auth/token Descripción: Permite obtener un nuevo token de acceso utilizando un token de refresco. Encabezados: - Content-Type: application/json Cuerpo de la Solicitud:

    {
      "grant_type": "refresh_token",
      "client_id": "YOUR_CLIENT_ID",
      "client_secret": "YOUR_CLIENT_SECRET",
      "refresh_token": "REFRESH_TOKEN_VALUE"
    }

Respuesta Exitosa (HTTP 200):

    {
      "access_token": "NEW_ACCESS_TOKEN_VALUE",
      "token_type": "Bearer",
      "expires_in": 3600,
      "scope": "sign"
    }

---

2. Envío y Firma de Documento

2.1 Enviar Documento para Firma

Endpoint: POST /api/v1/documents
Descripción: Permite enviar un documento PDF codificado en Base64 para ser firmado digitalmente. Encabezados:

• Content-Type: application/json
• Authorization: Bearer ACCESS_TOKEN_VALUE

Cuerpo de la Solicitud:

    {
      "document_name": "contract.pdf",
      "document_content": "BASE64_ENCODED_DOCUMENT",
      "active_directory_user": "john.doe@company.com",
      "signature_type": "digital_signature",
      "callback_url": "https://yourapp.com/signature-callback"
    }
    

Notas:

• active_directory_user es el usuario de directorio activo que debe firmar el documento.
• callback_url es opcional para notificaciones asíncronas.

Respuesta Exitosa (HTTP 202):

    {
      "document_id": "DOCUMENT_UUID",
      "status": "received",
      "message": "The document has been received and is queued for signing."
    }
    

---

3. Consulta de Estado del Documento

3.1 Obtener Estado del Documento

Endpoint: GET /api/v1/documents/{document_id}/status Descripción: Permite consultar el estado actual del documento previamente enviado para firma. Encabezados:

• Authorization: Bearer ACCESS_TOKEN_VALUE

Parámetros de Ruta:

• document_id: El identificador único del documento.

Respuesta Exitosa (HTTP 200):

    {
      "document_id": "DOCUMENT_UUID",
      "status": "signed",
      "date_sent_to_sign": "2024-02-25T14:30:00Z",
      "assigned_active_directory_user": "john.doe@company.com",
      "signing_date": "2024-02-25T15:00:00Z",
      "message": "The document has been successfully signed."
    }

Notas:

• date_sent_to_sign indica la fecha y hora en que el documento fue inicialmente enviado a firma.
• assigned_active_directory_user muestra el usuario de directorio activo asignado al documento.

---

4. Descarga del Documento Firmado

4.1 Descargar Documento Firmado

Endpoint: GET /api/v1/documents/{document_id}/download Descripción: Permite descargar el documento firmado en formato Base64. Encabezados:

• Authorization: Bearer ACCESS_TOKEN_VALUE

Parámetros de Ruta:

• document_id: El identificador único del documento.

Respuesta Exitosa (HTTP 200):

    {
      "document_id": "DOCUMENT_UUID",
      "document_name": "contract_signed.pdf",
      "signed_document_content": "BASE64_ENCODED_SIGNED_DOCUMENT",
      "date_sent_to_sign": "2024-02-25T14:30:00Z",
      "assigned_active_directory_user": "john.doe@company.com"
    }
    

Notas:

• date_sent_to_sign y assigned_active_directory_user se incluyen para referencia.

---

5. Revocación de Token

5.1 Revocar Token de Acceso o Refresh

Endpoint: POST /api/v1/auth/revoke Descripción: Permite revocar un token de acceso o de refresco. Encabezados:

• Content-Type: application/json
• Authorization: Bearer ACCESS_TOKEN_VALUE

Cuerpo de la Solicitud:

    {
      "token": "TOKEN_TO_REVOKE",
      "token_type_hint": "access_token"
    }    

token_type_hint puede ser access_token o refresh_token.

Respuesta Exitosa (HTTP 200):

    {
      "message": "The token has been successfully revoked."
    }    

---

6. Notificaciones Asíncronas (Webhooks)

Si el cliente proporciona callback_url al enviar el documento, el sistema enviará una solicitud POST a esa URL cuando el documento haya sido firmado.

6.1 Formato de la Notificación

Método: POST a callback_url Cuerpo de la Notificación:

    {
      "document_id": "DOCUMENT_UUID",
      "status": "signed",
      "signing_date": "2024-02-25T15:00:00Z",
      "message": "The document has been successfully signed.",
      "date_sent_to_sign": "2024-02-25T14:30:00Z",
      "assigned_active_directory_user": "john.doe@company.com"
    }

---

7. Manejo de Errores

En caso de error, la API responderá con un código de estado HTTP adecuado y un cuerpo en JSON describiendo el error.

Ejemplo de Respuesta de Error (HTTP 400):

{
  "error": "invalid_request",
  "message": "A detailed error message."
}

---

Resumen de Endpoints

Método	Endpoint	Descripción
POST	/api/v1/auth/token	Obtener o refrescar un token de acceso
POST	/api/v1/documents	Enviar un documento para firma (Base64 + usuario AD)
GET	/api/v1/documents/{document_id}/status	Consultar el estado del documento (incluye date_sent_to_sign y assigned_active_directory_user)
GET	/api/v1/documents/{document_id}/download	Descargar el documento firmado (incluye date_sent_to_sign y assigned_active_directory_user)
POST	/api/v1/auth/revoke	Revocar un token de acceso o de refresco

---