Skip to content

Guía de integración de firma V5 JWT - Api Firma

Es un servicio que permite enviar un documento PDF y recibirlo firmado electrónicamente.

Autenticación

Para consumir el servicio es necesario autenticarse y obtener un token, para ello se debe enviar un request de tipo POST a:

https://www.dactilar.toc.pe/api/v5/auth/token

Formato del request

Es necesario incluir los siguientes parámetros al enviar la solicitud o request:

Header del request:

Se aceptan como válidos los request de los siguientes tipos:

  • Content-type application/json
  • Accept: application/json

Body del request:

  • email: String correspondiente al correo electrónico del usuario que consumirá el servicio de TOC SERVICE CONSULTA DNI.
  • password: String correspondiente a la contraseña del usuario que consumirá el servicio de TOC SERVICE CONSULTA DNI.

Formato de la respuesta

Se responderá un objeto de tipo JSON. Este JSON contiene los siguientes datos:

  • token: String correspondiente al token JWT que se podrá utilizar para identificar al usuario y poder consumir los servicios. Solo se devuelve en caso los datos de acceso sean correctos.
  • error: String correspondiente al mensaje de error en caso los datos no sean válidos.

Ejemplos de consumo

Ejemplo de consumo de API TOKEN con cURL:

curl --location --request POST 'https://www.dactilar.toc.pe/api/v5/auth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
"email": "usuario@correo.com", 
"password": "123456"
}'

{
"token": "ge7WW1symmCfMTNwKJFafsdaiR….bQ1T5FAyzajRZlr6p7WqjOX"
}

Consumo de API SignPDF

La herramienta funciona como una API RESTful. Para consumirla, es necesario enviar un request de tipo POST a:

https://www.dactilar.toc.pe/api/v5/signPDF

Formato del request

Es necesario incluir los siguientes parámetros al enviar la solicitud o request:

Header del request:

Se aceptan como válidos los request de los siguientes tipos:

  • Content-type: multipart/form-data
  • Accept: application/json
  • Authorization: Bearer {token}

Body del request:

  • pdf_file: Archivo en crudo (binary) correspondiente al archivo en formato PDF a Firmar.
  • image: Archivo en crudo (binary) correspondiente a la imagen a colocar en la estampa, en formato JPG o PNG. La imagen podrá contener por ejemplo una huella digital o un selfie. La relación de aspecto deberá ser vertical o cuadrada.
  • nationality: (Opcional) String de 3 caracteres correspondiente al identificador de nacionalidad de la persona, por defecto es PER para Perú.
  • person_id_type: (Opcional) String correspondiente al tipo de documento, por defecto es DNI, pero podría ser también CE, para carné de extranjería o PAS para pasaporte.
  • person_id: String correspondiente al número de documento de identidad de la persona que firma.
  • names: String correspondiente a los nombres de la persona que firma.
  • last_names: String correspondiente a los apellidos de la persona que firma.
  • email: (Opcional) String correspondiente a los los apellidos de la persona que firma.
  • toc_token: (Opcional) String correspondiente al token que identifica a la transacción. Alfanumérico de 20 caracteres. En caso no se envíe el sistema generará uno.
  • page: Entero correspondiente a la página en la que se desea que vaya la firma. Si se envía “0” entonces se agregará una hoja al final del PDF y se agregará la estampa allí. Si se envía “-1” entonces el documento se firmará en todas las páginas (Esta función solo es compatible con la alineación por defecto desde la parte superior izquierda, que se consigue si no se envía el parámetro “align_bottom” o el valor para dicho parámetro es “0”).
  • align_bottom: (Opcional) Entero con valores 1 o 0. Si va con valor 1 entonces se alineará la estampa de la firma desde la esquina inferior izquierda. Si se envía 0 o no se envía el parámetro se usará la alineación por defecto desde la esquina superior izquierda.
  • position_x: Entero correspondiente a la posición X de la hoja en la que irá la estampa de la firma, desde la parte superior o inferior de la hoja de acuerdo con el parámetro “align_bottom”.
  • position_y: Entero correspondiente a la posición Y de la hoja en la que irá la estampa de la firma, desde la parte izquierda de la hoja.
  • async: Entero con valores 1 o 0. Si va con valor 1 entonces se responde a la consulta como asíncrona, para lo cual luego será necesario consumir el API “GetSignedPDF” para traer el archivo PDF Firmado.
  • binary_resp: (Opcional) Entero con valores 1 o 0. Por defecto si no se envía se considera como 0 y la respuesta es en base64 en el modo síncrono. Si se envía con valor 1 entonces se responderá como un archivo binario, cuyo nombre tiene el formato “.pdf”.
  • sign_type: (Opcional) Tipo de firma, con los posibles valores “agente” para agente automatizado, “digital” para firma digital y “otp” para firma OTP. En caso no se envíe nada por defecto es “agente”. En el caso de “otp” el tipo de firma es similar a de agente automatizado, pero adicionalmente pueden enviar el email como parámetro adicional para que aparezca en la estampa de la firma.
Valores para Firma Digital

En el caso de la firma digital el certificado es propio de la persona que firma, para ello se tiene la opción de que envíen los 3 parámetros (usuario, contraseña y pin) correspondientes al certificado en el request o si es que solo quieren enviar el pin se tendría que crear un usuario para la persona que firma y podrían registrar el nombre de usuario y contraseña del certificado con el api “updateSignCredentials”.

  • certificate_id: (Opcional) En caso el tipo de firma sea digital es posible enviar el id del certificado el mismo request.
  • certificate_pin: (Opcional) En caso el tipo de firma sea digital es posible enviar el pin del certificado en el mismo request.
  • qr_type: (Opcional) Las opciones para este campo pueden ser “auto” o “text”. Si se envía “auto” entonces no es necesario enviar el campo “qr_text”, y la información del QR se crea de forma automática de acuerdo a los datos de la estampa de la firma. En caso se envíe el valor “text” entonces será necesario también enviar el campo “qr_text”,
  • qr_text: (Opcional) En este campo se puede enviar cualquier valor de texto que se desee representar en el QR, ya sean links o un texto con información sobre el hit o no hit de una transacción y otros datos, el texto será representado en el QR tal cual como se envíe incluyendo saltos de línea.
  • stamp_size: (Opcional) Se puede enviar 2 valores: 1 o 2. Este campo indica el tamaño de la firma, el tamaño por defecto es 1, pero si se desea una firma del doble del tamaño se debe enviar 2. Enviar 2 sirve especialmente para el caso en el que se desea incluir tanto la imagen de la selfie o huella junto a un QR, esto facilita la visibilidad, ya que aparecerá el QR al costado de la imagen a diferencia que si se envía 1 en cuyo caso aparecería el QR debajo de la imagen y más pequeño.

Formato de la respuesta SÍNCRONA

SignPDF responderá un objeto de tipo JSON. Este JSON contiene los siguientes datos:

  • success: Booleano correspondiente a si la transacción fue exitosa o no.
  • message: String que corresponde al mensaje de respuesta de la transacción.
  • toc_token: String que corresponde al identificador de la transacción.
  • signed_pdf: String correspondiente al document PDF firmado, codificado en Base 64.

Formato de la respuesta ASÍNCRONA

SignPDF responderá un objeto de tipo JSON. Este JSON contiene los siguientes datos:

  • success: Booleano correspondiente a si la transacción fue exitosa o no.
  • message: String que corresponde al mensaje de respuesta de la transacción. La lista de mensajes se pueden ver en el "Anexo 1".
  • toc_token: String que corresponde al identificador de la transacción.
  • doc_id: String correspondiente al id del documento que será necesario enviar en el api de consulta de PDF Firmado (GetSignedPDF).

Ejemplos de consumo

Ejemplo de consumo de SignPDF en modo SÍNCRONO con cURL:

curl -X POST https://www.dactilar.toc.pe/api/v5/signPDF \
-H "Accept: application/json" \
-H "Authorization: Bearer tbx2XFgUKCbQs1iz0spaxe0NT…SBE5ymHrRPHIL30QeP9bWXhr1n" \
-H "Content-Type: multipart/form-data \
-F "pdf_file=@example.pdf" \
-F "image=@huella.png" \
-F "person_id=73712895" \
-F "names=Juan José" \
-F "last_names=Pérez Gomez" \
-F "toc_token=HeAG5mOp…eEvFXL34" \
-F "page=12" \
-F "position_x=50" \
-F "position_y=50" \
-F "async=0"

{
"success": true,
"message": "OK",
"toc_token": "HeAG5mOp9BKSeEvFXLyxaHrlkANuHl6zEfcuxqGQdFbtR28VS4InEnHeSa1JYb9O",
"signed_pdf": "JVBERi0xLjUKJeLjz9MKNTEgMCBvYmoKPDwgL0xpbmVhcml6ZWQgMSAvTCAzNzQ2NTQgL0ggWyAxMTE5IDI5MyBdIC9PIDU1IC9FIDYyMDExIC9OIDEyIC9UIDM3NDA3OSA+PgplbmRvYmoKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg…"
}

Ejemplo de consumo de SignPDF en modo ASÍNCRONO y con toc_token autogenerado (cuando no se envía toc_token) con cURL:

curl -X POST https://www.dactilar.toc.pe/api/v5/signPDF \
-H "Accept: application/json" \
-H "Authorization: Bearer tbx2XFgUKCbQs1iz0spaxe0NT…SBE5ymHrRPHIL30QeP9bWXhr1n" \
-H "Content-Type: multipart/form-data \
-F "pdf_file=@ example.pdf" \
-F "image=@huella.png" \
-F "person_id=73712895" \
-F "names=Juan José" \
-F "last_names=Pérez Gomez" \
-F "page=12" \
-F "position_x=50" \
-F "position_y=50" \
-F "async=1"

{
"success": true,
"message": "OK",
"toc_token": "HeAG5mO…p9BKSeEv"
}

Consumo de API GetSignedPDF (Modo Asíncrono)

La herramienta funciona como una API RESTful. Para consumirla, es necesario enviar un request de tipo GET a:

https://www.dactilar.toc.pe/api/v5/getSignedPDF?toc_token=<toc_token>

Formato del request

Es necesario incluir los siguientes parámetros al enviar la solicitud o request:

Header del request:

Se aceptan como válidos los request de los siguientes tipos:

  • Content-type: application/json
  • Accept: application/json
  • Authorization: Bearer {token}

Params del request:

  • toc_token: String correspondiente al token que identifica a la transacción. Alfanumérico de 64 caracteres.
  • binary_resp: (Opcional) Entero con valores 1 o 0. Por defecto si no se envía se considera como 0 y la respuesta es en base64 para el archivo PDF. Si se envía con valor 1 entonces se responderá como un archivo binario, cuyo nombre tiene el formato ".pdf".

Formato de la respuesta

GetSignedPDF responderá un objeto de tipo JSON. Este JSON contiene los siguientes datos:

  • success: Booleano correspondiente a si la transacción fue exitosa o no.
  • message: String que corresponde al mensaje de respuesta de la transacción.
  • toc_token: String que corresponde al identificador de la transacción.
  • signed_pdf: String correspondiente al document PDF firmado, codificado en Base 64.

Ejemplos de consumo

Ejemplo de consumo de GetSignedPDF en modo con cURL:

curl -X GET https://www.dactilar.toc.pe/api/v5/getSignedPDF?
 toc_token=HeAG5mOp9BKSeEvFXLyxaHrlkANuHl6zEfcuxqGQdFbtR28VS4InEnHeSa1JYb9O \
-H "Accept: application/json" \
-H "Authorization: Bearer tbx2XFgUKCbQs1iz0spaxe0NT…SBE5ymHrRPHIL30QeP9bWXhr1n" \
-H "Content-Type: application/json

{
"success": true,
"message": "OK",
"toc_token": "HeAG5m…Op9BKSeE",
"signed_pdf": "JVBERi0xLjUKJeLjz9MKNTEgMCBvYmoKPDwgL0xpbmVhcml6ZWQgMSAvTCAzNzQ2NTQgL0ggWyAxMTE5IDI5MyBdIC9PIDU1IC9FIDYyMDExIC9OIDEyIC9UIDM3NDA3OSA+PgplbmRvYmoKICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAg…"
}

ANEXOS

Anexo 01

Success Message Observación
true OK Firma exitosa.
false El valor del parámetro 'toc_token' ya se ha utilizado para un proceso, por favor utilizar un valor diferente. En caso se envié el valor toc_token de forma manual como parámetro y esté repetido.
false Ocurrió un error al firmar el documento. Por favor contactar con el administrador del sistema Otros errores.