# 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**: ```json { "grant_type": "password", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "username": "your_username", "password": "your_password" } ``` **Respuesta Exitosa (HTTP 200)**: ```json { "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**: ```json { "grant_type": "refresh_token", "client_id": "YOUR_CLIENT_ID", "client_secret": "YOUR_CLIENT_SECRET", "refresh_token": "REFRESH_TOKEN_VALUE" } ``` **Respuesta Exitosa (HTTP 200)**: ```json { "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**: ```json { "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)**: ```json { "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)**: ```json { "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)**: ```json { "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**: ```json { "token": "TOKEN_TO_REVOKE", "token_type_hint": "access_token" } ``` `token_type_hint` puede ser `access_token` o `refresh_token`. **Respuesta Exitosa (HTTP 200)**: ```json { "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**: ```json { "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)**: ```json { "error": "invalid_request", "message": "A detailed error message." } ``` --- # Resumen de Endpoints
MétodoEndpointDescripció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
---