¶ 1. Introducción
Este documento contiene la documentación de los mecanismos para que aplicaciones desarrolladas por las instituciones puedan realizar procesos de firma de documentos utilizando las firmas electrónicas avanzadas de autoridades o funcionarios custodiadas en el Repositorio Centralizado de Firmas.
En este documento es posible encontrar datos genéricos para que puedan realizar la firma de documentos en ambiente de pruebas.
¶ 1.1 Diagrama de secuencia
A continuación se presenta el diagrama correspondiente a las acciones a realizar con el objetivo de obtener uno o más documentos firmados.
- Cliente: Aplicación cliente que requiere firmar uno o más documentos.
- API Firma: Interfaz entre las aplicaciones externas (clientes) y las operaciones asociadas a la firma de uno o más documentos.
- RA (Autoridad de Registro): Contiene el registro de las aplicaciones externas habilitadas para realizar operaciones de firma. Las aplicaciones deben estar previamente registradas y cumplir con un conjunto de restricciones asociadas a la identificación del certificado de firma electrónica avanzada a utilizar (entidad, propósito y run del titular de la firma).
- Banco: Repositorio donde se custodian los certificados de firma electrónica avanzada habilitados para realizar operaciones de firma. El banco recibe los documentos a firmar y realiza la operación de firma, nunca un certificado será expuesto.
¶ 1.2 Firmar Documento
Con esta llamada, se puede firmar documentos Hash, utilizando un certificado de firma electrónica avanzada de propósito general (atendido) o desatendido, este formato permitirá contar con una mayor rapidez en la respuesta y un tráfico más liviano.
Además se cuenta con la alternativa de firmar documentos tipo PDF o XML.
Para utilizar su firma desatendida, previamente tendrá que haber solicitado su certificado por el “Sistema de Solicitud de Firma Electrónica” y habilitado la aplicación correspondiente.
Para la firma de documentos se deben tener las siguientes consideraciones
- El tamaño de la solicitud no puede exceder el tamaño máximo que son 5 MB.
- Los documentos firmados no son almacenados en la plataforma FirmaGob, por lo que la Institución que realiza la Integración de su sistema debe contar con su propio repositorio de documentos.
- El resultado que se obtiene de la firma de documentos no incluye un código de verificación o un link para la obtención del documento, esto debe ser incorporado por la Institución que realiza la Integración.
¶ Protocolo: HTTPS
URL: https://api.firma.digital.gob.cl/firma/v2/files/tickets', método = ['POST']
HTTP Headers
OTP: <Valor OTP> (Esta cabecera sólo es necesaria para la firma atendida, en caso de ser firma desatendida, no se debe enviar esta cabecera).
Validación de OTP
En caso de exceder el número de OTPs erróneos (5 intentos) se desplegará el error 429: “Ha excedido el número máximo de intentos de OTP. Intente más tarde”. Cuando esto ocurra se bloquearán sus solicitudes hasta que ingrese un OTP correcto.
HTTP Parámetros
| token |
Campo encriptado y firmado en JWT con una clave simétrica, esta clave es obtenida a partir del registro de la aplicación. El campo JWT encriptado en algoritmo HS256 y firmado con clave simétrica contiene los siguientes campos:
 |
| api_token_key | Campo no encriptado de tipo string que contiene el código único generado a partir del registro de la aplicación. |
| files |
Array no encriptado que contiene información de él o los documentos sobre los cuales se realizarán operaciones de firma. Cada objeto del array según el formato de archivo a firmar debe contener:  A continuación se describe el tipo de dato asociado al parámetro requerido:
|
A continuación se presentan ejemplos de los parámetros:
| token |
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbnRpdHkiOiJTdWJzZWNyZXRhcsOtYSBHZW5lcmFsIGRlIGxhIFByZXNpZGVuY2lhIiwicnVuIjoiMjIyMjIyMjIiLCJleHBpcmF0aW9uIjoiMjAyMS0xMS0xNVQxNzozMTowMCIsInB1cnBvc2UiOiJEZXNhdGVuZGlkbyJ9.EqcNFArqasx_hlZSYTO2Tnuqa36dMn_qnmk90XEyhTA" Algoritmo: HS256, Secreto: 27a216342c744f89b7b82fa290519ba0 { "entity": "Subsecretaría General de la Presidencia", "run": "22222222", "expiration": "2021-11-15T17:31:00", "purpose": "Desatendido" } |
| api_token_key | sandbox |
| files |
[ { "content-type": "application/pdf", "content": "archivo en base64", "description": "str", "checksum": "hash en sha256" } ] |
| token |
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJlbnRpdHkiOiJTdWJzZWNyZXRhcsOtYSBHZW5lcmFsIGRlIGxhIFByZXNpZGVuY2lhIiwicnVuIjoiMjIyMjIyMjIiLCJleHBpcmF0aW9uIjoiMjAyMS0xMS0xNVQxNzozMTowMCIsInB1cnBvc2UiOiJEZXNhdGVuZGlkbyJ9.EqcNFArqasx_hlZSYTO2Tnuqa36dMn_qnmk90XEyhTA" Algoritmo: HS256, Secreto: 27a216342c744f89b7b82fa290519ba0 { "entity": "Subsecretaría General de la Presidencia", "run": "22222222", "expiration": "2021-11-15T17:31:00", "purpose": "Desatendido" } |
| api_token_key | sandbox |
| files |
[ { "content-type": "application/pdf", "content": "archivo en base64", "description": "str", "checksum": "hash en sha256" } ] |
¶
¶ Ejemplo del JSON BODY para firmar un documento PDF
Ejemplo del JSON BODY para el caso de hash
- Para obtener el content a firmar, se deben parsear el PDF según las indicaciones:
- Al firmar un hash, se debe tener en consideración que se debe agregar el content de respuesta (mensaje firmado en formato p7s) al diccionario de firma del PDF. Para hacer esto se recomienda el uso de la librería iText de Java o C#
¶ Ejemplo del JSON BODY para el caso de XML
- El content será el base64 del XML a firmar
- Se puede agregar información del firmante con el parámetro “xmlObject”. Quedará en el tag Object dentro de la firma con id “CustomObject_XXX”
- Se puede agregar las referencias a firmar con el parámetro “references” tipo Lista
- La respuesta tendrá dentro del content un XML firmado encodeado en base64
¶ Ejemplo del JSON BODY para el caso de JSON
- El content será el base64 del json a firmar por ejemplo: eyJrZXkxIjogInZhbHVlMSIsImtleTIiOiAidmFsdWUyIn0=
- La respuesta tendrá dentro del content un JSON encodeado en base64
¶ Response Json Schema Body
El resultado de este llamado corresponde a un JSON que contiene los documentos firmados.
{
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Recepción de documentos firmados",
"type": "object",
"required": [
"session_token",
"files"
],
"additionalProperties": false,
"properties": {
"session_token": {
"type": "string"
},
"metadata": {
"type": "object",
"properties": {
"OTP_expired": {
"type": "boolean"
},
"files_recived": {
"type": "number"
},
"files_signed": {
"type": "number"
},
"signed_failed": {
"type": "number"
}
},
"required": [
"OTP_expired",
"files_received",
"files_signed",
"signed_failed"
]
},
"files": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"required": [
"checksum_original",
"status"
],
"additionalProperties": false,
"properties": {
"type": {
"enum": [
"PDF",
"JSON",
"XML"
]
},
"content": {
"type": "string"
},
"checksum_original": {
"type": "string"
},
"checksum": {
"type": "string"
},
"description": {
"type": "string"
},
"status": {
"type": "string"
}
}
}
}
}
}
Un ejemplo de respuesta es la siguiente:
{
"files": [
{
"content": "eyJqd3MiOiAiZXlKaGJHY2lPaUpTVXpJMU5pSXNJbU4wZVNJNkltcHpiMjRpTENKMGVYQWlPaUpLVjFNaUxDSjROV01pT2xzaUxTMHRMUzFDUlVkSlRpQkRSVkpVU1VaSlEwRlVSUzB0TFMwdFhHNU5TVWxGTjJwRFEwRTVZV2RCZDBsQ1FXZEpTVXRzYTBocE1rVlJhVzFaZDBSUldVcExiMXBKYUhaalRrRlJSVXhDVVVGM1RGUkZjazFEYTBkQk1WVkZRWGQzYVZGWE1XbGhWMVoxWkVkVloxcEhWV2RSTWxaNVpFZHNiV0ZYVG1oWk1tNUVjekkwWjFVeVZtNVZTRXBzWTNwQlpVWjNNSGxOVkVWNFRVUlZlRTFxUlRWTlJGSmhSbmN3ZVU1RVJYaE5SRlY0VFdwRk5VMUVVbUZOU1VkNFRWTnJkMHAzV1VwTGIxcEphSFpqVGtGUmEwSkdhSEJyV2xoT2FHUkhWblZhUjJ4cllqQkNhMXBZVG1oa1IxWjFXa2RzYTJKNU5XcGlSRVZPVFVGelIwRXhWVVZCZDNkRlltNVdjMkpFUlZSTlFrVkhRVEZWUlVKU1RVdE5ha2w1VFdwSmVVMXFTWFJOYWtWWlRVSlpSMEV4VlVWRVFYZFFVVEpHZVZveU9HZGFSMVZuWTBoS01WcFhTbWhOVkd0M1RuZFpSRlpSVVV0RVJFSk9ZVmMxY0dNelVteGpiV3gyU1VaT2JGa3pTbXhrUjBaNWR6WXhhRWxGWkd4aWJWWjVXVmQzWjFwSFZXZGlSMFZuVlVoS2JHTXliR3RhVnpWcVlWZEZlRU42UVVwQ1owNVdRa0ZaVkVGclRrMU5TVWxDU1dwQlRrSm5hM0ZvYTJsSE9YY3dRa0ZSUlVaQlFVOURRVkU0UVUxSlNVSkRaMHREUVZGRlFYUTBiSFppVUhaRk5WcGhaa3NyVm1ORVpYRnJRbWhETjA1eVkydHhLMk5pVkRkcWNIZHJXa1pzZWtONk1FTkJTSFJEVWtSeVVYbzJaV3R3Y1ZaWWQzaFZNVnBEVkV4YVZFY3lZV0ZwWkVkdGVreHlhbXczYm1JMVJIbHpVa2RZVlVkeU1HZHNaaTl4V0U1c1ExZFVlbWcyVmpsQ2QyaGpTM0JNUkV0YWRUTkNORm8yU3pkQ1FXcFhXbWR5VUVwM0x6TmhUSEoxZGxoNEwybFpTVFZRVG0xNllYTkRRVTVwVms5NmQycEpWemxVY1RkNWFtOU9ialIwYTNORWJVMW5WQ3RTZGpJM1NraFhVRWhIWlhnM2FsVTVUSGxCUTJwc1lXaE9SR1E0TVVkS1NEaDVhbmhtVlZoTWVETlhjRk41YkhCS2NYaHdhVEpvTkVOT2ExQjZiVFpRTm1oTFVUTmplR2N3VjBReFkwOVNObVpJZFhOS2EwdEVWbHAzVlN0cGRtZEpPRFU1ZW5sQ2FtMUNkMk5pVDJOd09FUlpVbE5GWWtGaFkxcHNkMEoyUm1KVlpVdDRibVoyVW14elZXOWtZVGt5TTJKdmQwbEVRVkZCUW04MFNVSnBla05EUVZsamQxQkJXVWxMZDFsQ1FsRlZTRUZSUlVWTlJFRjFUVU4zUjBORGMwZEJVVlZHUW5wQlFtaHBRbTlrU0ZKM1QyazRkbHB0YkhsaVYwVjFXa2RzYm1GWVVtaGlRelZ1WWpKSmRWa3lkM1ppTWs1NlkwUkJaRUpuVGxaSVVUUkZSbWRSVlVsWGFXMHZPRzF5SzJSeVNYcE9hM0kyWkU5SFpHODBSRnBoYjNkRVFWbEVWbEl3VkVGUlNDOUNRVWwzUVVSQlprSm5UbFpJVTAxRlIwUkJWMmRDVVhWbFFsbFRiRWRsWVROUVUyRlFZVlJqWnl0eU5sQnlhVWxvUkVGeFFtZE9Wa2hTU1VWSmVrRm9iMEk0UjBORGMwZEJVVkZDZDFGRlEyOUNUVmRGVmtwV1ZrWTVSRkpXU2xWVFZWcEtVVEJHUkZOVk9VOU5SVzlIUVRGVlpFbEJVa1JOUlVWM1VIZFpSMWxKUlZsb01tdEVUVVJWZDAxM1dVbExkMWxDUWxGVlNFRm5SVmRLTW1nd1pFaENlazlwT0haYWJXeDVZbGRGZFZwSGJHNWhXRkpvWWtNMWJtSXlTWFZaTW5kMldrYzVhbVJYTVd4aWJsSjJZM3BCZDBKblRsWklVamhGUzFSQmJrMURWMmRKTmtGb2FHZzViMlJJVW5kUGFUaDJXVEpXZVdSRE5XMWFWMUYxV2pJNWFVeHRUbk5NTWs1c1kyNVJkVmt6U25OTlFYTkhRVEZWWkVSM1VVVkJkMGxHTkVSQlpFSm5UbFpJVTFWRlJtcEJWVUpuWjNKQ1owVkdRbEZqUkVGbldVbExkMWxDUWxGVlNFRjNVWGRKZDFsRVZsSXdVa0pDZDNkSGNVRlpRbWRuY2tKblJVVkJZMFZDUVdGQlRVWm5iM2xOYWtsNVRXcEplVTFwTUhsTlFUQkhRMU54UjFOSllqTkVVVVZDUTNkVlFVRTBTVUpCVVVKaU0yRnBhVlZRZUVGUldIaEZTMVpMYkRSVWIweExUbk41VDJ0SVJsbHlWbGxSWjNFNVRsaEVjRzB5WlVweVR6ZE9lblJWTm1NemFqTXZWVXBITVU5c1JuZHRlbEI0U201dFYwcFBjRTVvYm0wM1JYTkNNMHAyVkdnM01qRmliR05YVDAxRGJ5OHdXbkZ5Y3pWME5ITklia2hoYkhkMk0wSnBSSFl2WlRoWGRVWkhWVFZLVURGa1FTc3ZVVEpwWXpCbmVYSjRVelZGV210TVRHZzJVWG80WVZWVk5HZGlLMHRGUW0wM1ZGZHVPRXBtVmpWdmVtTmlWazU1YkhkM2FYVmxlSFYzTTJKRlNWSXdSVEZ5VDJ4UWRrNTVhWFZOYWtKalJqTk9hVE5RWW0xUmNHaG9hM2RhTTNsT1FVeHNielJRUW5kSlMzbFRja3RMUlVReVVVNUpjMUpZTW01eGJWUTRhMDV5VTBaclRIb3habXMwWVVKT1VFSjRlRE0xVFZBNFNpdENUWE15U0dZNFVURkdXbUl6Tms1WUsybGtZVk5TSzFnM04wVlVRM0J3VW14M2VYRlVibVZ2Y2tWbWJXRlFUVE4xV0Z4dUxTMHRMUzFGVGtRZ1EwVlNWRWxHU1VOQlZFVXRMUzB0TFNJc0lpMHRMUzB0UWtWSFNVNGdRMFZTVkVsR1NVTkJWRVV0TFMwdExWeHVUVWxKUldsRVEwTkJNME5uUVhkSlFrRm5TVWxoVVVGelVXRlNTRmxzWjNkRVVWbEtTMjlhU1doMlkwNUJVVVZNUWxGQmQxUkVSV05OUW05SFExTnhSMU5KWWpORVVVVktRVkpaVGxVd09VNVNWVUpHVkZWR1NsUkROVVJVUkVWelRVTnZSMEV4VlVWQmQzZHFVbFUxVlZOVlVrSlNRMEpUVkRBNVZVbEZSazVSYTJ4R1ZHeFNSa2xGVGtaVmJGSktVbXRzUkZGVlRrcFVNRFIzU0doalRrMVVaM2hOYWtVelRWUk5NRTVxVFROWGFHTk9UV3BuZUUxcVFUTk5WRlV3VG1wUk5GZHFRWFJOVTNOM1MxRlpSRlpSVVVSRVEwcENZbGRLY0ZwWE5UQmFVMEpyV2xOQ1JGcFlTakJoVjFwd1dUSkdhbUZqVDNwaWFVSlVXbGRrVVdOdFZucE5TVWxDU1dwQlRrSm5hM0ZvYTJsSE9YY3dRa0ZSUlVaQlFVOURRVkU0UVUxSlNVSkRaMHREUVZGRlFXcEdiRVJQYUU1NmVXVjJVMko0UXk5Nk1EQm9hUzlLUm5rd2IxZDJZMUUxU0VwNGVsSTRka3AyWTNoNlRpdDJjV00zTmpJMmRpOW5TVVZCVkZaMFFuaHFOR05CVkhWTk1XTnJMMnBUV1UxbloxTm5iVXB0UlVWc2JVWXliek5MZUhwSFJIUjRlSFk1ZURCVVRXbEJZemh0Vkdkc04xSkRVMU0zV0VaVFMxbFVhRVJQYlRCVlJHZzBRMVJ3TWsxTVkxTlJiMmcxVkd4clVXdE5ia1Y1YTFCQlUzYzBPVkJ5Um10QlNUVm5WV0l3YUZBek5sQlpVbFpyVXpoSE15dDFXbVZxZUhKdFVDOXVZMUpJUXl0RE9GWTFUMlk1Tmt0eE9XWXhUVlZMTUc0MmNYbFFXbXN5VVhvM1dGRnpWVEo0TDFkcFZWTktPV1pCY0U1NWVWcDVUekYzYlV0VFoxVkRhVWx0U0dOQ1RsYzRSekJTYVcxSWFHaHpSRFUyTVZVd0wybG5TblExWjJobGJsTktTRTlQYlV4QldXSjBPVE40V1hWTldrdEpjSGhPTWsxYVlqRmtZMGd2YldWbFdsTndPRUpoVFRadmQwbEVRVkZCUW04MFNVSnBla05EUVZsamQxSlJXVWxMZDFsQ1FsRlZTRUZSUlVWUFZFRXpUVVJWUjBORGMwZEJVVlZHUW5wQlFtaHBiRzlrU0ZKM1kzcHZka3d5VG14amJsSndXbTFzYWxsWFRuQmlNalIxV2tkc2JtRllVbWhpUXpWdVlqSkpkVmt5ZDNaaU1rNTZZMFJCWkVKblRsWklVVFJGUm1kUlZVeHVaMWRGY0ZKdWJYUjZNRzFxTW1zelNWQnhLMm8yTkdsSlVYZEVkMWxFVmxJd1ZFRlJTQzlDUVZWM1FYZEZRaTk2UVdaQ1owNVdTRk5OUlVkRVFWZG5RbEpTVTNWbFlXOHlVSEI0TDJSWk9WSndaWHBqVFZoM05Vb3lTR3BCYUVKblRsWklVa2xGUjJwQldXOUNXVWREUTNOSFFWRlJRbmRSUlVOdlFXOVhRMFpLVmxaR09WTlVNRGxWVFVWdlIwRXhWV1JKUVZKRVRVVkZkMUIzV1VkWlNVVlphREpyUkUxRVZYZE5kMWxKUzNkWlFrSlJWVWhCWjBWWFNqSm9NR1JJUW5wUGFUaDJXbTFzZVdKWFJYVmFSMnh1WVZoU2FHSkROVzVpTWtsMVdUSjNkbHBIT1dwa1Z6RnNZbTVTZG1ONlFrTkNaMDVXU0ZJNFJVOTZRVFZOUkdWblRtRkJlbWhxUm05a1NGSjNZM3B2ZGt3eVRteGpibEp3V20xc2FsbFhUbkJpTWpSMVdrZHNibUZZVW1oaVF6VnVZakpKZFZreWQzWlpNMHB6V0ROS2RtSXpVWFZaTTBwelRVRTBSMEV4VldSRWQwVkNMM2RSUlVGM1NVSkNha0Z4UW1kT1ZraFNSVVZKZWtGb2IwSTRSME5EYzBkQlVWRkNkMUZGUW05Q1RWZEZWa3BXVmtZNVJGSldTbFZUVlZwS1VUQkdSRk5WT1U5TlFUQkhRMU54UjFOSllqTkVVVVZDUTNkVlFVRTBTVUpCVVVOWFNGVTJMMUJhYlc1SlIwTjBkMHRQTUM5dlpHNXNTbG8zYWpScmFYbFBTVk4zT0RGb2VFOVpUREl2ZVhoMGRUTnFPV1owTW5aNk5rTlBVVU5QYldwdmRuUm9jekJGY0VkdVZqWTJRVkVyV1U4elRFZ3ljR1V6VjJZNFZreHlUWEZyUzJoek4zcGtlVXgxTVUwcmNIQnZSblJZT0hneE5HaEhkbEJPZGxWSU5USnFOWGQwYWxWc1pWYzRZWGhGVTJsdE5uRlFPVEp3ZGpFMWEwbHlPR2hKU0RkbGRXRjNXa3RXZWxwS1NqWjVTMHRQVTNWd2VVTlhWM28yTjFnek1ERmtPWGREYm1sQlRXOXhRVTAxYlVOemRsazJZMkZWVFdsRVFtc3JWMlI2Tkd4bE9XNVRNSFphTURkSkwzSnlSeXRoT0ZkelVsUmhUVVJKWTFGQ2FXbE9kRVExU1VkaGIwc3ZkMnRPTnpGMVMzTlVLMkphZFRFd2RsZE1WSGRIYjNFMFJ6aE1LMGQwWW1wT2JFRndNRVowYUc1SlRXTlNUWFJGVERSeE9WcHZWVVJMZVd0SWVFbDRRMGd6TDBsbFVuRkVjamxEVkZ4dUxTMHRMUzFGVGtRZ1EwVlNWRWxHU1VOQlZFVXRMUzB0TFNJc0lpMHRMUzB0UWtWSFNVNGdRMFZTVkVsR1NVTkJWRVV0TFMwdExWeHVUVWxKUkRkVVEwTkJkRmRuUVhkSlFrRm5TVWxVV210S0wzSjJhVmhYZDNkRVVWbEtTMjlhU1doMlkwNUJVVVZNUWxGQmQxUkVSV05OUW05SFExTnhSMU5KWWpORVVVVktRVkpaVGxVd09VNVNWVUpHVkZWR1NsUkROVVJVUkVWelRVTnZSMEV4VlVWQmQzZHFVbFUxVlZOVlVrSlNRMEpUVkRBNVZVbEZSazVSYTJ4R1ZHeFNSa2xGVGtaVmJGSktVbXRzUkZGVlRrcFVNRFIzU0doalRrMVVaM2hOYWtFelRWUlZNRTVxVVRSWGFHTk9UV3BuZUUxcVFUTk5WRlV3VG1wUk5GZHFRazFOVW5kM1IyZFpTa3R2V2tsb2RtTk9RVkZyUWtabk1WUlVNREZHVVVWV1RsRlZiRTFNYTA1TlRWTjNkMHRuV1VSV1VWRkVSRU5PUmxSc1VrcFNSVVpGU1VaS1VGUXhVV2RSVlRGRFUxVldUMVpGVldkUk1GWlRWa1ZzUjFOVlRrSlJNR3hRVkdwRFEwRlRTWGRFVVZsS1MyOWFTV2gyWTA1QlVVVkNRbEZCUkdkblJWQkJSRU5EUVZGdlEyZG5SVUpCU21oeWNtaEVXR1J3VERkdFdDOXRTbHB3VHpkTE4zVjVUVkoyY1VreWVFMXlWV2hPU25CR1YwNTZNMVE0TkdGblZVY3lkV3R6YzAxV2FFRTRXazE1YmpoTmJ6ZHhRbmczVkVac1lqTjBNM2RuUkRSd2VsSTJUVmhLY2pkYVlTOXhTWFp4VEdKSU1rdFZWV0pRU3k5b2VHdEhSSEIxWlRNcmNuaFBVa0ZvUzJkU1RsWXJORk40ZFdaMVRtTmtTalEwY20xV1IzWlZVbEJHZVZaRlVVMURVVnB0WVZZd2QwOVJPU3RhV1VSM09EWm1OazUzTVVKdWQyRlhSWFJUU1cxU09EaEdkazl4ZUhkSlZVUlRTVlZhTm1GSlVITlJNMFJ3TDFCQ05WcFZNVVZGUVhCQlEzUndjVUUxV1hKMlJWQXdjMUo1WkdaaWNXdFRNM0psYnpOdlUzb3dRVkZDTkdFeWJrdFpOMmxpV0RCUWEya3lPRzl6ZW5oeGNFSk9VbHAwVEVoalpFeFhZMlZNUzBoR1ltdElNMGt6U2xSV2IxcE5jMkphWld0Sk5XaGxaMEY2Y21WWk1FVTNVR0UzU2pkcFN6VnRUMjlGUTBGM1JVRkJZVTlDTUdwRFFucDZRV1JDWjA1V1NGRTBSVVpuVVZWVlZYSnViWEZPYWpaalpqTlhVRlZoV0hNelJFWTRUMU5rYURSM1JIZFpSRlpTTUZSQlVVZ3ZRa0ZWZDBGM1JVSXZla0ZtUW1kT1ZraFRUVVZIUkVGWFowSlNVbE4xWldGdk1sQndlQzlrV1RsU2NHVjZZMDFZZHpWS01raHFRa3BDWjA1V1NGTkJSVkZxUWtGTlJEUkhRbTFEUWtkSlpIQkJla0V3VFVSSlIwTkRjMGRCVVZWR1FuZEpRa1pwV205a1NGSjNZM3B2ZGt3eVduQmpiVEZvV2xkNGJGa3pVbmxpTWpWd1dUSkZkVm95T1dsTWJVNXpUREpPZDJNeE9XNU5WRUZQUW1kT1ZraFJPRUpCWmpoRlFrRk5RMEZSV1hkSlVWbEVWbEl3VWtKQ2IzZEhTMEZYUW1kbmNrSm5SVVZCWTBWQ1FXRkJTMFpuYUZOV1ZsSm1WV3M1VUZaRVFVNUNaMnR4YUd0cFJ6bDNNRUpCVVhOR1FVRlBRMEZSUlVGVkwwbGlZMnN5TWtKelJubG9RWEZZVXpkUWFIaFRObGxuY1d4YWVETTNiSHBYUnpGNE5Va3ljVXB1UzJrMlEyZGxTRFJUUVdkYVMzQkdRMWQyU25aWEx6WmpTV05WVHpnME1VVXZibnBrUjNGdGFVWkNORVY0V1hscGMzQjVlbGRrWmpGaVdXNXpTMkZ6WTBVNVduWnhMM0ZRTDB4T1RIRXdkRnBsYms4dmFHUXZSRkI1VkU5SmRtVm5ZU3M1YTBGNWR6VkxWRlF3Vld0U05FdzBUakJyT1hSV1FWWnZVV3cwTDNCcGFtcE1SMUJpT1VkbVYwRlZUR1poV25OWlJWWm5kMnhRU1VaU2NsbEpWVFptVVRSb1MzSndNMWhvZUhWT1IwNHhURkUyUjBsWlZFRlFZV2RSZFZKNk5GUnFNV05PWVRKQmNIbE5Oa2RNZFZCb2QwVjNibGMzYlc5NVpqbEdjV2REUldaSGNrTnpWVmxUTW5WdVVERktabmRCVHpjek9FazNNRmRPTkROamF6YzRUWEJJTXpOT1JYaFJkM04zUzNKaWNXNTFWV3BKVjNKQmNWZFVla1poTVRKelFWSlpNV3hqTTNjOVBWeHVMUzB0TFMxRlRrUWdRMFZTVkVsR1NVTkJWRVV0TFMwdExTSmRmUS5leUp6ZFdJaU9pSkViMk4xYldWdWRHOGdabWx5YldGa2J5QndiM0lnTWpJeU1qSXlNakl0TWlJc0lrUnZZM1Z0Wlc1MGIwWnBjbTFoWkc4aU9pSjdYQ0pyWlhreFhDSTZJRndpZG1Gc2RXVXhYQ0lzWENKclpYa3lYQ0k2SUZ3aWRtRnNkV1V5WENKOUluMC5ScjFPZG8zZHhqclBnLWZhOWF5blZxbDJCR25GQldES1dLWGRsQVhSb3ZJQWt6dEczdS0xV3JTemVjblAzUWtIdnZNcW1lcndXcTU3Y0dIV3JUT3JGekpqal81YnVuODJQcG8tSnlEdm5McUNmTVFMYmFZOXl5OWZsRGZBbTYxdW9qTXZlaEowTFQyN2hmRXl4d2dxS2V6VDRjbHkyTF9jZE1VRm5GMHljOWZ1eVpKMXNUTy1YRWxMN2FkQTNfR1dWYlRESUtMSFBFZGRIMkxFRE1wSnY1NmhFQ2wtMExka3lsMnp2WW0wNTlCRG40TjAyX05iaEx3LXF6WHB4dWtuMXlEaTlqSERxVUlGSmhZc1I3LWNsME5HSUNoTUR6NmZMQnZqRnptS1NxZ1J0MHJ3aXZmQS1SWVU1M3B6V2ExdjlydWlUOEdERkdPQ09lZUhCOUp5dGcifQ==",
"status": "OK",
"description": null,
"contentType": "application/json",
"documentStatus": "FIRMADO",
"checksum_original": "9971224dc8f574ec570ce9fa86f649e2fc26928f561d1649e16841432f9165ff"
}
],
"metadata": {
"otpExpired": false,
"filesSigned": 1,
"signedFailed": 0,
"objectsReceived": 1
},
"idSolicitud": 570880299954241865
}
En el campo files se recibe una lista de objetos, este contiene lo siguiente:
| checksum_original | SHA256 del archivo original. |
| status | error - no se concretó la firma |
| OK - transacción correcta | |
| content | base64 del archivo firmado |
En el campo metadata se recibe un objeto que contiene lo siguiente:
| signed_file | número de archivos firmados |
| OTP_expired | booleano que indica si el OTP se pudo usar de manera correcta con la totalidad de archivos |
| files_signed | Número de archivos que se pudieron firmar |
| files_recived | Número de archivos recibidos |
¶ 2. Ambiente de TEST
Las firmas generadas en este ambiente no son válidas, es sólo para facilitar la integración. Los datos entregados a continuación permiten realizar pruebas de firma de documentos.
URL: https://api.firma.cert.digital.gob.cl/firma/v2/files/tickets', método = ['POST']
¶ 2.1 Firma atendida
| api_token_key | sandbox |
| JWT |
{ "entity": "Subsecretaría General de la Presidencia", "run": "11111111", "expiration": "2021-11-15T17:31:00", "purpose": "Propósito General" } |
| secreto | 27a216342c744f89b7b82fa290519ba0 |
El código QR correspondiente a semilla para generar OTPs asociadas a este certificado es el siguiente:
En el Anexo A se detalla cómo realizar la instalación y configuración para la generación de OTPs.
¶ 2.2 Firma desatendida
| api_token_key | sandbox |
| JWT |
{ "entity": "Subsecretaría General de la Presidencia", "run": "22222222", "expiration": "2021-11-15T17:31:00", "purpose": "Desatendido" } |
| secreto | 27a216342c744f89b7b82fa290519ba0 |
En el caso de firma desatendida no debe enviarse el header OTP.
Una vez realizada las pruebas, la Institución puede solicitar el registro de su aplicación en el ambiente productivo en la siguiente url: Solicitud de Registros FirmaGob - opción registro de aplicación. Como resultado de dicha solicitud obtendrá los parámetros api_token_key y Secret que permitirán la integración con nuestra plataforma.
¶ 3. Códigos HTTP asociados a la API
|
Status code |
Tipo |
Response |
| 200 | Ok |
{ "files":[ { "content":"ARCHIVO BASE64 FIRMADO", "status":"OK", "contentType":"application/pdf", "description":"DESCRIPCION DE DOCUMENTO", "checksum_original":"CHECKSUM ENVIADO", "checksum_signed":"CHECKSUM FIRMANDO" } ], "metadata":{ "otpExpired":false, "filesSigned":1, "signedFailed":0, "objectsReceived":1 } } |
| 400 | Bad request |
{ "timestamp": "yyyy-MM-dd hh:mm:ss", "status": 400, "error": "Mensaje de Error*" } * Mensaje de Error, pueden ser los siguientes:
|
| 404 | Error de Recurso no Encontrado |
{ "timestamp": "yyyy-MM-dd hh:mm:ss", "status": 404, "error": "Mensaje de Error*" } *Mensaje de Error, pueden ser los siguientes:
|
| 412 | Error no autorizado |
{ "timestamp": "yyyy-MM-dd hh:mm:ss", "status": 401, "error": "Mensaje de Error*" } *Mensaje de Error, pueden ser los siguientes:
|
| 429 | Too Many Request |
{ "timestamp": "yyyy-MM-dd hh:mm:ss", "status": 429, "error": "Ha excedido el número máximo de intentos de OTP. Intente mas tarde" } |
| 500 | Error interno de servidor |
{ "timestamp": "yyyy-MM-dd hh:mm:ss", "status": 500, "error": "Internal Server Error" } |
| 502, 503, 504 | Error tiempo agotado de espera del Servidor |
{ "timestamp": "yyyy-MM-dd hh:mm:ss", "status": 504, "error": "Mensaje de Error" } Mensaje de Error, pueden ser los siguientes:
|
¶ Anexo A. Instalación aplicación móvil y configuración OTP
Es requisito habilitar una aplicación que permita generar un OTP válido al momento de realizar las pruebas al servicio. Por tal motivo, se ha habilitado una clave generadora de OTPs que permite utilizar un ambiente sandbox solo para la ejecución de pruebas.
A continuación se detallan los pasos a seguir para habilitar un generador de OTP en un smartphone.
¶ Aplicación OTP
Acceder a Google Play o App Store, descargar e instalar la aplicación Free OTP o Google Authenticator (para el ejemplo se ha utilizado un equipo con versión 5.1.1)
Abrir la aplicación ya instalada y habilitar la aplicación para la lectura de códigos QR.
Escanee el código QR.
¶ Anexo B. Configuración para incrustar firma a PDF
¶ Propiedad layout
La propiedad layout permite embeber una imagen asociada a la firma, análoga, de la persona que firma el documento electrónicamente. El siguiente XML muestra la estructura del layout.
<AgileSignerConfig>
<Application id=\"THIS-CONFIG\">
<pdfPassword/>
<Signature>
<Visible active=\"true\" layer2=\"false\" label=\"true\" pos=\"1\">
<llx></llx>
<lly></lly>
<urx></urx>
<ury></ury>
<page>LAST</page>
<image>BASE64</image>
<BASE64VALUE></BASE64VALUE>
</Visible>
</Signature>
</Application>
</AgileSignerConfig>
| Variable | Descripción | Tipo Valor |
| llx | Coordenada x de la esquina inferior izquierda de la imagen. | Número entero |
| lly | Coordenada y de la esquina inferior izquierda de la imagen. | Número entero |
| urx | Coordenada x de la esquina superior derecha de la imagen. | Número entero |
| ury | Coordenada y de la esquina superior derecha de la imagen. | Número entero |
| page | Número de página donde se incluirá la imagen con la firma. | Número entero. También es posible usar la palabra LAST para hacer referencia a la última hoja del documento. |
| image | Tipo de encoding utilizado para embeber la imagen | Texto. Valor constante a utilizar BASE64 |
| base64value | Contenido de la imagen con el formato y encoding definido anteriormente. |
Texto. Contenido del archivo en base64 |
Ejemplo:
Por restricciones de tamaño de archivo, el siguiente ejemplo no considera el contenido de la imagen. El ejemplo completo se encuentra publicado en RequestFirmaLayout.json
<AgileSignerConfig>
<Application id=\"THIS-CONFIG\">
<pdfPassword/>
<Signature>
<Visible active=\"true\" layer2=\"false\" label=\"true\" pos=\"1\">
<llx>250</llx>
<lly>300</lly>
<urx>350</urx>
<ury>450</ury>
<page>LAST</page>
<image>BASE64</image>
<BASE64VALUE></BASE64VALUE>
</Visible>
</Signature>
</Application>
</AgileSignerConfig>
¶
Anexo C. Definiciones y acrónimos
| Acrónimo | Definición |
| API | Application Programming Interface |
| APP | Aplicación |
| JSON | JavaScript Object Notation |
| JWT | JSON Web Token |
| SHA256 | hash criptográfico |
| OTP | One-Time Password |
| RA | Registration authority |
| XML | Extensible Markup Language |
| Término | Descripción |
| Firma atendida | Operación de firma en la cual se requiere la intervención del titular para la generación del OTP. |
| Firma desatendida | Operación de firma en la cual no se requiere la intervención del titular para la generación del OTP. |