Skip to content

Guía de integración de firma V3 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/v3/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, de acuerdo al resultado de la autenticación:

  • 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/v3/auth/token' \
--header 'Content-Type: application/json' \
--data-raw '{
 "email": "usuario@correo.com", "password": "123456"
}'

Ejemplo de respuesta exitosa:

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

Ejemplo de respuesta con error:

{
  "error": "invalid_credentials"
}

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/v3/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 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: (Opcional) 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í. En caso no se envíe este parámetro la firma no será representada con una estampa gráfica en el PDF, y en este caso tampoco será necesario enviar los demás datos de la persona o la imagen que tendrían que ir en la estampa gráfica.
  • position_x: Entero correspondiente a la posición X de la hoja en la que irá la estampa de la firma, desde la parte inferior de la hoja.
  • 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

Nota 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".

  • sign_username: (Opcional) En caso el tipo de firma sea digital es posible enviar el nombre de usuario del certificado en el mismo request o registrarlo con el API "updateSignCredentials".
  • sign_password: (Opcional) En caso el tipo de firma sea digital es posible enviar la contraseña del certificado en el mismo request o registrarlo con el API "updateSignCredentials".
  • sign_pin: (Opcional) En caso el tipo de firma sea digital es posible enviar el pin del certificado en el mismo request. Este solo es un valor obligatorio si el tipo de firma es "digital".
  • 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/v3/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=HeAG5mOp9BKSeEvFXLyxaHrlkANuHl6zEfcuxqGQdFbtR28VS4InEnHeSa1JYb9O" \
  -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/v3/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": "HeAG5mOp9BKSeEvFXLyxaHrlkANuHl6zEfcuxqGQdFbtR28VS4InEnHeSa1JYb9O"
}

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/v3/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/v3/getSignedPDF?
        toc_token=HeAG5mOp9BKSeEvFXLyxaHrlkANuHl6zEfcuxqGQdFbtR28VS4InEnHeSa1JYb9O \
  -H "Accept: application/json" \
  -H "Authorization: Bearer tbx2XFgUKCbQs1iz0spaxe0NT…SBE5ymHrRPHIL30QeP9bWXhr1n" \
  -H "Content-Type: application/json

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

Consumo de API UpdateSignCredentials (Firma Digital)

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

https://www.dactilar.toc.pe/api/v3/updateSignCredentials

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:

  • sign_username: String correspondiente al nombre de usuario registrado para el certificado a utilizar en la firma digital.
  • sign_password: String correspondiente a la contraseña registrada para el certificado a utilizar en la firma digital.

Formato de la respuesta

UpdateSignCredentials 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.

Ejemplos de consumo

Ejemplo de consumo de UpdateSignCredentials en modo con cURL:

curl -X POST https://www.dactilar.toc.pe/api/v3/updateSignCredentials \
  -H "Accept: application/json" \
  -H "Authorization: Bearer tbx2XFgUKCbQs1iz0spaxe0NT…SBE5ymHrRPHIL30QeP9bWXhr1n" \
  -H "Content-Type: application/json

{
  "success": true,
  "message": "Credenciales registradas correctamente"
}

Consumo de API SignTimeStamp (Solo sello de tiempo)

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

https://www.dactilar.toc.pe/api/v3/signTimeStamp

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:

  • tsq_file: Archivo en crudo (binary) correspondiente al archivo en formato ".tsq" (solicitud de sello de tiempo). Este archivo corresponde a una solicitud de creación de sello de tiempo para adjuntar en un archivo PDF que se desee firmar y se puede generar desde un servidor o computadora utilizando openssl. Ejm:
openssl ts -query -data <nombre_archivo>.pdf -no_nonce -sha256 -out request.tsq

Formato de la respuesta

UpdateSignCredentials 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.
  • `tsr_file: String correspondiente al archivo en formato ".tsr" (respuesta de sello de tiempo), codificado en Base 64.

Ejemplos de consumo

Ejemplo de consumo de SignTimeStamp en modo con cURL:

curl -X POST https://www.dactilar.toc.pe/api/v3/signPDF \
  -H "Accept: application/json" \
  -H "Authorization: Bearer tbx2XFgUKCbQs1iz0spaxe0NT…SBE5ymHrRPHIL30QeP9bWXhr1n" \
  -H "Content-Type: multipart/form-data \
  -F "tsq_file=@ request.tsq" \

{
  "success": true,
  "message": "OK",
  "toc_token": "HeAG5mOp9BKSeEvFXLyxaHrlkANuHl….GQdFbtR28VS4InEnHeSa1JYb9O",
  "tsr_file": "MIINWDADAgEAMIINTwYJKoZIhvcNAQcCoIINQDCCDTwCAQMxDzANBglghkgBZQMEAgEFADCCAVYGCyqGSIb3DQEJEAEEoIIBRQSCAUEwggE9AgEBBgYEAI9nAQEwMTANBglghkgBZQMEAgEFAAQgolpkQ2m8wbgmEM9u+i09Y2ks38hHtxcp9y1tA8mv2XsCDqINg/+VuAAweDI0OGJlGA8yMDIzMTEyNTA0MTQ0M…"
}

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 PDFError: Página ## no encontrada En caso se envíe un número de página fuera de la cantidad de páginas del PDF.
false Ocurrió un error, consulta con el administrador Otros errores.
false Error al firmar el PDF. Otros errores.