Skip to content

IdentiaSign: PDF Sign Web Service

V0.0.2REV20241025V0.0.2REV20241025

Este servicio le permitirá crear y administrar procesos de firma de PDF, completamente integrado con un sistema de validación de identidad y notificaciones.

Ambientes

El sistema de Identiasign cuenta con 2 ambientes de trabajo: calidad y producción. Esto se traduce en que cada ambiente tiene una URL base distinto (base URL):

  • Calidad: https://apisignqa.identia.pe
  • Producción: https://apisignprod.identia.pe

Estos 2 ambientes se encuentran aislados entre sí, por lo que los datos de una cuenta creada en un ambiente no estarán presentes en los otros (por ende, se requieren credenciales distintas para cada ambiente).

Autenticación

Obtención de un token de acceso (POST /api/auth/login)

Permite a los usuarios autenticarse y obtener un token de acceso requerido para las interacciones con otros API. Este endpoint es crucial para que los usuarios obtengan acceso al servicio y realicen acciones en según sus roles y permisos. El access_token entregado debe ser usado en el encabezado Authorization para las solicitudes subsequentes mediante el protocolo OAuth 2.0.

Los parámetros a incluir dentro del body son los siguientes:

  • username: El nombre de la entidad dueña de los recursos administrados por el backend (posee parámetros, procesos de identificación, usuarios). Formato: Dominio de la entidad
  • clientname: Identificador de la credencial que se utilizará para acceder a los recursos del usuario establecidos al momento de crear la credencial. Formato: Correo electrónico
  • password: Es el secret establecido para la credencial que se utilizará

Request

  • Content-Type: application/json
  • Body: Un string JSON que contiene el nombre de usuario, el nombre de cliente y la contraseña.

Ejemplo:

{
  "username": "example.com",
  "clientname": "client@example.com",
  "password": "yourpassword"
}

Respuestas

200 OK: Login exitoso. Retorna un token de acceso. Ejemplo:

{
  "access_token": "aa.bb.cc"
}
Nota

El encabezado de autorización debe incluir el token en el siguiente formato: jwt-bearer aa.bb.cc

404 Not Found: Error con las credenciales, ya sea porque no existen o las credenciales son incorrectas. Ejemplo:

not found

Administración de procesos de firma

Creación de procesos de firma (PUT /api/signature_processes)

Inicia un nuevo proceso de firma mediante la carga de archivos PDF para ser firmados y especificando los firmantes y sus detalles.

Request

  • Content-Type: multipart/form-data

Body:

  • pdfFiles: Archivo(s) PDF que serán firmados.

  • signOrder: Booleano que indica si la firma debería ser en orden (true / false). (Parámetro opcional)

  • signers: Información detallada para cada firmante, incluyendo:

    • nat: ID de identidad del firmante. Actualmente, solo se permite el valor PER.
    • doc_id: ID de documento del firmante (por ejemplo, DNI).
    • signatureType: Valor por defecto advanced.
    • signChallenges: Arreglo de strings que describen los tipos de validaciones necesarias para firmar. Actualmente, solo se permite facial.
    • stampPositions: Objeto JSON que describe la ubicación de la estampa de la firma según el índice del archivo, la página (este valor es actualmente sobreescrito por el sistema) y la ubicación XY (también sobreescrita por el sistema).
    • contactInfo: Objeto JSON con la información de contacto del firmante para enviar notificaciones relacionadas con el proceso de firma. La subclase contactInfo incluye:
      • type: Tipo de contacto. Puede ser email o whatsapp.
      • value: Valor del contacto. Para contactos del tipo whatsapp, el valor debe incluir el código de país en el formato +NN (por ejemplo, +51), consistiendo solo de números (sin espacios ni guiones).
      • tz (opcional): Zona horaria en formato (+|-)HH:MM. Por defecto, la zona horaria es -05:00.
  • expire: Segundos que transcurrirán hasta que el proceso de firma expire. Valor por defecto: 30 días. (Parámetro opcional)
  • link_expire: Segundos que transcurrirán hasta que expire el enlace de firma compartido con los firmantes.Si no se configura este parámetro, el enlace tomará automáticamente el mismo tiempo de expiración del parámetro expire. (Parámetro opcional)
  • description: Texto descriptivo del proceso de firma. (Parámetro opcional)
  • urlCallback: URL a la que el backend de IdentiaSign realizará un request POST una vez concluya el proceso de firma. (Parámetro opcional)
  • labels: Lista de etiquetas para ser asociadas al folio por crear. Las etiquetas enlistadas en esta propiedad deben haberse creado previamente con la API de administración de etiquetas. (Parámetro opcional)
Nota

En caso de que no se proporcione información de contacto para un firmante (por ejemplo, el correo electrónico), este no recibirá notificaciones.

La versión actual del sistema solo permite estampar la firma de cada firmante una vez por archivo, en una página en blanco que se agregará automáticamente al final del documento.

Ejemplo de una solicitud:

{
  "pdfFiles": arhivo(s).pdf,
  "signers": [
    {
      "nat": "PER",
      "doc_id": "12345678",
      "signatureType": "advanced",
      "signChallenges": ["facial"],
      "stampPositions": {
        "$fileIndex": {
          "$pageNumber": {
            "x":1,
            "y":1,
            "size":8,
            "orientation":"horizontal"
          }
        }
      },
      "contactInfo":{
        "type":"email",
        "value":"example@example.com",
        "tz":"-05:00"
      }
    }
  ],
  "expire": 3600,
  "link_expire": 3600,
  "description": "Example description"
}
Nota

En caso de que existan múltiples documentos y se requiera que el firmante firme en documentos específicos o en todos, es necesario agregar un diccionario que incluya el índice del documento $fileIndex que se desea firmar dentro de la lista stampPositions.

Respuestas

  • 201 Created: Creación del proceso de firma exitosa. Entregará el ID del nuevo proceso de firma.

Ejemplo:

{
  "id": "aaaaaaaa:bbbbbbbbb",
  "msg": "https://apisigndev.identia.pe/ui/signature_processes/aaaaaaaa:bbbbbbbbb.cccc.ddddddd"
}
  • 400 Bad Request: El request no es correcto o está incompleto.

Ejemplo:

bad request

Ejemplo de un payload enviado a la urlCallback:

{
  "signers_search": ["PER:11111111"],
  "sign_order": false,
  "status": "signed",
  "expire": 1737298031,
  "documents": [
    {
      "name": "Documento de firma de prueba-1.pdf",
      "id": "abc123",
      "pages": 1,
      "url": "http://example.com"
    }
    // Additional documents
  ],
  "signers": [
    {
      "nat": "PER",
      "stampPositions": {
        "0": {}
      },
      "contactInfo": {
        "type": "email",
        "value": "soporte@toc.pe",
        "tz": "-05:00",
        "notified": false
      },
      "sign_data": {
        "signAction": "sign",
        "facial": {
          "result": true,
          "msg": "success",
          "id": "aaaaaaa.bbbbb.ccccc",
          "expire": 1734706137,
          "selfie": "PER_11111111"
        },
        "date": 1734706127,
        "result": "sign"
      },
      "pinfo": {
        "given_name": "",
        "family_name": ""
      },
      "signatureType": "advanced",
      "signChallenges": ["facial", "signAction"],
      "doc_id": "11111111"
    }
    // Additional signers
  ],
  "date": 1734706031,
  "urlCallback": "",
  "labels": [],
  "readChallenges": ["signerId"],
  "description": "EJEMPLO",
  "id": "ddddd:eeeeee",
  "nat": "PER",
  "per_id": "11111111"
}
Nota

Los enlaces URL generados para la descarga de documentos tienen un tiempo de vida limitado de 2 minutos. Una vez expirado este periodo, será necesario generar un nuevo enlace de descarga utilizando el API GET

Modificar procesos de firma (POST /api/signature_processes)

Este endpoint permite modificar algunos datos de un proceso de firma ya existente.

Request

  • Content-Type: multipart/form-data
  • Body:
  • description: Nuevo texto descriptivo del proceso de firma (opcional).
  • signers: Arreglo de objetos que contiene firmantes para modificar sus detalles, o para eliminaros (opcional).
  • process_id: Identificador del proceso de firma (requerido).

Cada firmante a modificar debe o puede tener los siguientes parámetros:

  • doc_id: ID del firmante a modificar.(no modificable)
  • nat: Codificación del tipo de identificación del firmante.
  • action: Tipo de modificación (update o remove).
  • signerAlias: Nuevo alias para el firmante (opcional).
  • stampPositions: Nueva posición de la estampa de firma para determinadas páginas (opcional).
  • contactInfo: Nueva información de contacto para el firmante (opcional).

Respuestas

  • 200 OK: El proceso de firma ha sido actualizado exitosamente.

Ejemplo:

ok
  • 403 Forbidden: El estado del proceso de firma o los permisos de las credenciales no permiten la modificación.

Ejemplo:

forbidden
  • 404 Not Found: No se pudo encontrar el proceso de firma.

Ejemplo:

not found

Enlistar procesos de firma (GET /api/signature_processes)

Obtiene una lista de los procesos de firma basado en los parámetros de consulta proporcionados. Este endpoint soporta el filtrado y la paginación para la obtención eficiente de los datos.

Content-Type: Params

Parámetros de consulta

  • limit: Número entero que especifica el número máximo de procesos de firma a retornar.
  • creation_start: Texto que describe el límite inferior de la fecha de creación desde la cual buscar procesos de firma, en formato AAAAMMDDThh:mm:ss+00:00.
  • creation_end: Texto que describe el límite superior de la fecha de creación hasta la cual buscar procesos de firma, en formato AAAAMMDDThh:mm:ss+00:00.
  • status: Estado de los procesos de validación que desea buscar. Los valores pueden ser signed, rejected.
  • process_id: Identificador único del proceso de firma que desea buscar. Si se proporciona este parámetro, se ignorarán los demás parámetros de búsqueda.
  • last_item: Texto (objeto JSON) que representa el último elemento de búsqueda obtenido de una búsqueda parcial, para retomar la búsqueda desde ese elemento.

Respuestas

  • 200 OK: Se ha obtenido correctamente un listado completo de procesos de firma que coinciden con los parámetros de consulta.

Ejemplo:

{
  "signatureProcesses": [
    {
      "date": "2024-12-20T15:10:31+00:00",
      "description": "Documento de firma de prueba-1.pdf",
      "documents": [
        {
          "id": "abc123",
          "name": "Documento de firma de prueba-1.pdf",
          "pages": 1,
          "url": "http://example.com"
        }
      ],
      "expire": "2025-01-19T15:10:31+00:00",
      "id": "aaaaaa:bbbbbbb",
      "labels": [],
      "readChallenges": ["signerId"],
      "sign_order": false,
      "signers": [
        {
          "contactInfo": {
            "notified": false,
            "type": "email",
            "tz": "-05:00",
            "value": "soporte@toc.pe"
          },
          "doc_id": "11111111",
          "nat": "PER",
          "signChallenges": ["facial", "signAction"],
          "signatureType": "advanced",
          "signerAlias": "Otro Nombre",
          "stampPositions": {
            "0": {
              "0": {
                "orientation": "horizontal",
                "size": 8,
                "x": 50,
                "y": 50
              }
            }
          }
        }
        // Firmantes adicionales
      ],
      "signers_search": ["PER:11111111"],
      "status": "signed",
      "urlCallback": ""
    }
    // Otros procesos de firma
  ],
  "last_item": null
}
Nota

Los enlaces URL generados para la descarga de documentos tienen un tiempo de vida limitado de 2 minutos. Una vez expirado este periodo, será necesario volver a generar otra solicitud (request) para obtener un nuevo enlace. Tenga en cuenta que solo se podrá obtener un enlace si el folio sigue disponible; una vez que este expire, ya no será posible obtener una URL del documento.

  • 206 Partial Content: Se ha obtenido correctamente un listado parcial de procesos de firma que coinciden con los parámetros de consulta. Utilice el parámetro last_item para continuar la búsqueda desde este elemento.

Ejemplo:

{
  "signatureProcesses": [
    // Lista parcial de procesos de firma
  ],
  "last_item": {
    "processId": "last_returned_process_id"
    // Otros detalles de `last_item`
  }
}
  • 400 Bad Request: Parámetros de consulta inválidos.

Ejemplo:

bad request
  • 404 Not Found: No se encontraron procesos de firma.

Ejemplo:

not found

Este endpoint es crucial para los usuarios que necesitan manejar y monitorear multiples procesos de firma, brindando flexibilidad en la consulta y listado de procesos por criterios especificos.

La URL de cada documento puede estar presente en el arreglo documents del proceso de firma si el documento aun está disponible en IdentiaSign. Cada enlace expira en 120 segundos desde su creación.

Rechazo de procesos de firma (DELETE /api/signature_processes)

Permite rechazar uno o varios procesos de firma basado en sus IDs, proporcionando el proceso si está en un estado que permite rechazo.

Request

  • Content-Type: multipart/form-data
  • Body: Identificador del proceso de firma que se rechazará.
  "process_id_list": ["process_id_example"]

Respuestas

  • 200 OK: El proceso de firma se ha rechazado exitosamente.
{
  "errors": []
}
  • 403 Forbidden: El proceso de firma no pudo ser rechazado debido a que se encuentra en un estado incorrecto o las credenciales del usuario no tiene los permisos necesarios.
forbidden
  • 404 Not Found: El proceso de firma especificado no existe.
not found

Manejo de notificaciones

Notificar procesos de firma (POST /api/notify)

Gatilla las notificaciones para un proceso de firma. Las notificaciones pueden enviarse a través de correo electrónico basados en la información de contacto proporcionada durante la creación del proceso de firma.

Request

  • Content-Type: multipart/form-data

  • Body:

  • process_id: Identificador único del proceso de firma a ser notificado.

  • link_expire: Expiración del enlace de firma compartido (opcional).

    {
  "process_id": "unique_process_id",
  "link_expire": 3600
}

Respuestas

  • 200 OK: Responde con un nuevo link.
https://apisigndev.identia.pe/ui/signature_processes/aaaaaaa:bbbbbb.ccccc.dddd
  • 400 Bad Request: Solicitud incorrecta o incompleta.
bad request
  • 404 Not Found: No se ha podido encontrar el proceso de firma especificado.
not found

Si link_expire no se especifica, por defecto el enlace compartido tendra tiempo de expiración del proceso de firma.

Administración de etiquetas

Enlistar etiquetas (GET /api/labels)

Este método permite enlistar las etiquetas creadas. Se ordenan en orden descendente alfabético según el nombre de la etiqueta.

Request

  • URL query parameters:
  • limit: Cantidad de etiquetas que se devolverán. 
    {
  "limit": 0
}
  • last_item: Continuar el enlistado de etiquetas desde este elemento. JSON parseado como string, obtenido de la respuesta de un enlistado parcial de etiquetas. 
    {
  "last_item": {
    "label": "etiqueta de ejemplo",
    "usr_id": "usr_id_example"
  }
}

Respuestas

  • 206 Partial Content: Se ha obtenido correctamente un listado parcial de etiquetas. Utilice el parámetro last_item para continuar la búsqueda desde este elemento.

Ejemplo:

{
  "labels": [
    // Lista parcial de procesos de firma
  ],
  "last_item": {
    "label": "etiqueta de ejemplo",
    "usr_id": "usr_id_example"
  }
}
  • 200 Full query: Se ha obtenido correctamente un listado completo de etiquetas.

Ejemplo:

{
  "labels": [
    // Lista completa de procesos de firma
  ]
}
  • 400 Bad Request: Solicitud incorrecta o incompleta.
bad request

Crear/modificar etiquetas (POST /api/labels)

Creación o modificación de etiquetas para clasificaciones.

Request

  • Content-Type: multipart/form-data

  • Body:

  • label: Nombre identificador de la etiqueta. Si una etiqueta con este nombre no ha sido previamente creada, la llamada a esta API permitirá crear una etiqueta nueva con este nombre. Pero si la etiqueta ya existía, la llamada a esta API permitira modificar los detalles de la etiqueta existente. Es sensible a mayúsculas y minúsculas.

    {
  "label": "etiqueta de ejemplo"
}

Respuestas

  • 200 OK: La creación o modificación de la etiqueta ha sido exitosa.
ok
  • 400 Bad Request: Solicitud incorrecta o incompleta.
bad request

Eliminar etiquetas (DELETE /api/labels)

Eliminar etiquetas previamente creadas.

Request

  • Content-Type: multipart/form-data

  • Body:

  • label: Nombre identificador de la etiqueta que se desea eliminar.

    {
  "label": "etiqueta de ejemplo"
}

Respuestas

  • 200 OK: La etiqueta ha sido correctamente eliminada.
ok
  • 400 Bad Request: Solicitud incorrecta o incompleta.
bad request

Codificación de tipos de ID

El tipo de codificación definido en el parámetro nat de cada firmante es usado para indicarle al sistema cómo debe interpretar el parámetro doc_id, dado que cada país puede tener un formato de ID diferente o contar con diferentes sistemas de identidad, lo que puede cambiar las opciones disponibles para los tipos de firma y flujos de verificación de identidad.

La siguiente tabla muestra los tipos de ID soportados:

Tipo de ID Formato de ID Descripción
PER 12345678 Número de identidad nacional Peruano (DNI)
CHL * 12345678-9 Número de identidad nacional Chileno (RUN)
PERPASS* 1234567891 Número de pasaporte peruano
PERCE* 123456789123 Número del carnet de extranjeria peruano
Nota
  • Funcionalidad disponible según condiciones contratadas

Colección Postman - API de IdentiaSign

Descripción

Se proporciona una colección de Postman que contiene todos los endpoints disponibles del API de Identia Sign. Esta colección le permitirá probar y validar las diferentes funcionalidades antes de realizar su integración.

Nota

Sugerimos validar el comportamiento utilizando esta colección de Postman. Esto ayudará a identificar si el problema está relacionado con su implementación o con el servicio.

Recursos Disponibles

Descargar Colección Postman