Skip to main content

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
Back to top