Descripción de APIS

Iniciar proceso de firma

Datos generales
Descripción		Permite a los sistemas externos generar un proceso de firma a partir de uno o más archivos y otros datos.
Método HT		POST
Path		/api/externos/proceso1
Entrada		application/json
Salida		application/json
Parámetros de entrada
archivos		Lista de archivos	Obligatorio; debe contener al menos un archivo.
			nombre	Texto	Obligatorio; nombre del archivo.
			contenido	Bytes	Obligatorio; contenido del archivo, en formato Base64.
nombre_sistema		Texto	Obligatorio; nombre del sistema que inicia el proceso, para mostrar al usuario y para auditoría.
firma_longev		Si/No	onal; indicador de si se requiere utilizar firma longeva o no. Si no se es especifica se asume que no se utiliza firma longeva.
cantidad_firmante		Entero	pcional; cantidad de firmas que deben efectuarse sobre el archivo. Si no se proporciona, se asume “1”. Si se proporciona elvalor “0”, no se limita la cantidade firmantes.
detalles_firmante		Lista defirmantes	Opcional; detalles sobre los firmantes, para mostrar antes deproceder a la firma de cada uno de los usuarios. Si el largo de lalista es menor a la cantidad de firmantes, los firmantes en exce-so serán tratados como anónimos, con los valores asumidos paratodas las variables. Si el largo de la lista es mayor a la cantidad de firmantes, se ignoran los firmantes en exceso. Para cada firmante se debe especificar:
			documento_numero	Texto	Opcional; número de documento de la persona que debe firmar. Sise proporciona, el API debe validar que la persona que firma el archivo pueda ser identificada con el mismo número en el certificado digital que usa para firmar.
			documento_pais	Texto	Opcional; código ISO2 del país emisor del documento de la persona que debe firmar. Si se proporciona el parámetro documento_numero pero no se proporciona este parámetro, se asume “UY”(Uruguay).
			documento_tipo	Texto	Opcional; tipo de documento, según el catálogo de tipos de documentos que determine AGESIC. Sise proporciona el parámetro documento_numero pero no se proporciona este parámetro, se asume el valor que corresponda a la cédula de identidad.
			forzar_cedula	Sí/No	Opcional; indicador de si se debe forzar que la firma de los archivos sea realizada utilizando una cédula de identidad electrónica o no. Si se omite, se asume “No”.
			validar_firmante	Sí/No	Opcional; indicador de si se debe validar que la persona que firma puede identificarse mediante el certificado digital. Si se omite, se asume “No”.
fecha_limite		Fecha yhora	Opcional; fecha y hora límites para que el proceso de firma seacompletado. Si se proporciona, el API puede limitarlo a un período menor, según configuración. Si no se proporciona, el API debe asignarle un valor, según configuración.
url_notificación		URL	Opcional; URL a donde la plataforma de firma debe notificar queel proceso de firma fue completado. El recurso detrás de esta URL debe aceptar el método POST, incluyendo en el cuerpo (body) del mensaje los siguientes parámetros en formato JSON:identificador: idenƟficador del proceso de firma finalizado (UUID).estado: estado del proceso de firma (‘FINALIZADO’, ‘RECHAZADO’). Si se omite, el sistema externo no podrá ser noƟficado cuando elproceso de firma se complete, debiendo hacer polling constante utilizando el método de consulta de estado.
url_retorno		URL	Opcional; URL a la cual la plataforma de firma debe redirigir alusuario luego de que éste complete la firma de los archivos. (seespera que el sistema externo pueda continuar con su proceso,ya sea incluyendo un identificador en la propia URL o tomandolos datos de la sesión, o de otra manera, a su criterio). Si no seespecifica, al finalizar el proceso de firma el usuario quedaráviendo una pantalla de confirmación propia de la plataforma.
Parámetros de salida
200	identificador	UUID	Identifica unívocamente a un proceso de firma.
	Clave_seguridad	Texto	Clave de seguridad que deberá ser proporcionada para consultarel estado del proceso de firma y obtener los archivos firmados.
	fecha_expiracion	Fecha y hora	Fecha y hora de expiración del proceso de firma. Esta fecha escalculada por la plataforma, de la siguiente manera:Si la invocación no incluye el parámetro “fecha_limite”, se calcu-la como (ahora + N minutos), donde N es un parámetro de configuración denominado “PLAZO_EXPIRACION”. Si la invocación incluye el parámetro “fecha_limite”, y el mismoes válido (la diferencia entre ahora y dicha fecha es menor oigual a un parámetro de configuración denominado “PLAZO_MAXIMO_EXPIRACION”), entonces es la misma fecha.Si la invocación incluye el parámetro “fecha_limite”, pero el nomismo es válido (la diferencia entre ahora y dicha fecha es ma-yor a un parámetro de configuración denominado “PLAZO_MAXIMO_EXPIRACION”), entonces se calcula como (ahora + N minutos), donde N es un parámetro de configuración denominado“PLAZO_MAXIMO_EXPIRACION”.
400	Mensaje	Texto			Mensaje explicativo en el caso de fallo.

Iniciar proceso de firma (solo metadatos)

Datos generales
Descripción	Permite a un sistema externo cargar un único archivo, obteniendo un identificador para el mismo. Se debe tener en cuenta que aún no se generó un proceso de firma para este archivo, sino que se hará posteriormente cuando se hayan cargado todos los archivos correspondientes.
Método HTTP	POST
Path	/api/externos/archivo
Entrada	application/octet-stream
Salida	application/json
Parámetros de entrada
archivo	Archivo	Obligatorio; el archivo debe ser pasado en formato binario.
nombre	Texto	Obligatorio; debe ser pasado usando el header "Content-Disposition".
Parámetros de salida
200	identificado	UUID	Identifica unívocamente a un archivo.
400	mensaje	Texto	Mensaje explicativo en el caso de fallo.

Iniciar proceso de firma

Datos generales
Descripción		Permite a los sistemas externos generar un proceso de firma a partir de uno o más archivos cargados previamente utilizando el endpoint “Cargar archivo”.
Método HTTP		POST
Path		/api/externos/proceso2
Entrada		application/json
Salida		application/json
Parámetros de entrada
archivos		Lista de identifi- cadores	Obligatorio; debe contener al menos un identificador, y todos ellos deben corresponderse a archivos cargados previamente utilizando el endpoint “Cargar archivo” y que no estén asociados aún a ningún proceso de firma.
nombre_sistema		Texto	Obligatorio; nombre del sistema que inicia el proceso, para mos- trar al usuario y para auditoría.
firma_longeva		Sí/No	Opcional; indicador de si se requiere utilizar firma longeva o no. Si no se es especifica se asume que no se utiliza firma longeva.
		Entero	Opcional; cantidad de firmas que deben efectuarse sobre el ar- chivo. Si no se proporciona, se asume “1”. Si se proporciona el valor “0”, no se limita la cantidad de firmantes.
cantidad_firmantes		Entero	Opcional; cantidad de firmas que deben efectuarse sobre el ar- chivo. Si no se proporciona, se asume “1”. Si se proporciona el valor “0”, no se limita la cantidad de firmantes.
detalles_firmantes		Lista de firman- tes	Opcional; detalles sobre los firmantes, para mostrar antes de proceder a la firma de cada uno de los usuarios. Si el largo de la lista es menor a la cantidad de firmantes, los firmantes en exce- so serán tratados como anónimos, con los valores asumidos para todas las variables. Si el largo de la lista es mayor a la cantidad de firmantes, se ignoran los firmantes en exceso. Para cada firmante se debe especificar:
			documento_numero	Texto	Opcional; número de documento de la persona que debe firmar. Si se proporciona, el API debe validar que la persona que firma el archi- vo pueda ser identificada con el mismo número en el certificado digital que usa para firmar.
			documento_pais	Texto	Opcional; código ISO2 del país emisor del documento de la per- sona que debe firmar. Si se pro- porciona el parámetro documen- to_numero pero no se proporcio- na este parámetro, se asume “UY” (Uruguay).
			documento_tipo	Texto	Opcional; tipo de documento, se- gún el catálogo de tipos de docu- mentos que determine AGESIC. Si se proporciona el parámetro docu- mento_numero pero no se pro- porciona este parámetro, se asu- me el valor que corresponda a la cédula de identidad.
			forzar_cedula	Sí/No	Opcional; indicador de si se debe forzar que la firma de los archivos sea realizada utilizando una cédula de identidad electrónica o no. Si se omite, se asume “No”.
			validar_firmante	Sí/No	Opcional; indicador de si se debe validar que la persona que firma puede identificarse mediante el certificado digital. Si se omite, se asume “No”.
fecha_limite		Fecha y hora	Opcional; fecha y hora límites para que el proceso de firma sea completado. Si se proporciona, el API puede limitarlo a un perío- do menor, según configuración. Si no se proporciona, el API debe asignarle un valor, según configuración.
url_notificacion		URL	Opcional; URL a donde la plataforma de firma debe notificar que el proceso de firma fue completado. El recurso detrás de esta URL debe aceptar el método POST, incluyendo en el cuerpo (body) del mensaje los siguientes parámetros en formato JSON: identificador: identificador del proceso de firma finaliza- do (UUID). estado: estado del proceso de firma (‘FINALIZADO’, ‘RE- CHAZADO’). Si se omite, el sistema externo no podrá ser notificado cuando el proceso de firma se complete, debiendo hacer polling constante utilizando el método de consulta de estado.
url_retorno		URL	Opcional; URL a la cual la plataforma de firma debe redirigir al usuario luego de que éste complete la firma de los archivos. (se espera que el sistema externo pueda continuar con su proceso, ya sea incluyendo un identificador en la propia URL o tomando los datos de la sesión, o de otra manera, a su criterio). Si no se especifica, al finalizar el proceso de firma el usuario quedará viendo una pantalla de confirmación propia de la plataforma.
Parámetros de salida
200	identificador	UUID	Identifica unívocamente a un proceso de firma.
	clave_segu- ridad	Texto	Clave de seguridad que deberá ser proporcionada para consultar el estado del proceso de firma y obtener los archivos firmados.
	fecha_expi- racion	Fecha y hora	Fecha y hora de expiración del proceso de firma. Esta fecha es calculada por la plataforma, de la siguiente manera: Si la invocación no incluye el parámetro “fecha_limite”, se calcula como (ahora + N minutos), donde N es un pa- rámetro de configuración denominado “PLAZO_EXPIRA- CION”. Si la invocación incluye el parámetro “fecha_limite”, y el mismo es válido (la diferencia entre ahora y dicha fecha es menor o igual a un parámetro de configuración deno- minado “PLAZO_MAXIMO_EXPIRACION”), entonces es la misma fecha. Si la invocación incluye el parámetro “fecha_limite”, pero el no mismo es válido (la diferencia entre ahora y dicha fecha es mayor a un parámetro de configuración denominado “PLAZO_MAXIMO_EXPIRACION”), entonces se calcula como (ahora + N minutos), donde N es un pa- rámetro de configuración denominado “PLAZO_MAXI- MO_EXPIRACION”.
400	mensaje	Texto	Mensaje explicativo en el caso de fallo.

Consultar estado del proceso de firma.

Datos generales
Descripción		Permite al módulo frontend o sistemas externos consultar el es- tado de un proceso de firma (pendiente, completado, obsoleto).
Método HTTP		HEAD
Path		/api/externos/estado/{identificador}
Entrada		No tiene
Salida		application/json
Parámetros de entrada
identificador		UUID	Obligatorio; identificador del proceso de firma que se desea consultar.
clave_seguridad		Texto	Obligatorio; clave de seguridad correspondiente al proceso de firma; debe ser pasado utilizando el en- cabezado “Authorization”.
Parámetros de salida
200		json	Devuelve un json con la siguiente información: es- tadoProceso, nombreSistema, mensaje y url de re- torno.
304	mensaje	Texto	Sin Mensaje
403	mensaje	Texto	Mensaje indicando que la clave de seguridad no es correcta.
404	mensaje	Texto	Mensaje indicando que el proceso de firma no existe o ya está expirado.

Obtener Archivos firmados (todos juntos)

Datos generales
Descripción		Permite al módulo frontend obtener todos los archivos firmados corres- pondientes a un proceso de firma.
Método HTTP		GET
Path		/api/externos/archivos/{identificador}
Entrada		No tiene
Salida		application/json
Parámetros de entrada
identificador		UUID	Obligatorio; identificador del proceso de firma para el cual se desean obtener los archivos firmados.
clave_seguridad		Texto	Obligatorio; clave de seguridad correspondiente al proceso de firma; debe ser pasado utilizando el encabezado “Authoriza- tion”.
Parámetros de salida
200	archivo	Lista de archivos	Lista de archivos firmados. Para cada archivo se proporicionan los siguientes datos:
			nombre	Texto	Nombre original del archivo.
			contenido	Bytes	Contenido del archivo, en formato Ba- se64.
304	mensaje	Texto	Sin mensaje.
403	mensaje	Texto	Mensaje indicando que la clave de seguridad no es correcta.
404	mensaje	Texto	Mensaje indicando que el proceso de firma no existe o ya está expirado.

Obtener archivo firmado(forma individual)

Datos generales
Descripción		Permite al modulo frontend obtener unos archivos firmados correspondietes a un proceso de firma
Método HTTP		GET
Path		/api/externos/archivos/{identificador}
Entrada		No tiene
Salida		application/octet-stream
Parámetros de entrada
identificador		UUID	Obligatorio; identificador del archivo para el cual se desea obtener su correspondiente archivo firmado.
clave_seguridad		Texto	Obligatorio; clave de seguridad correspondiente al proceso de firma al cual pertenece el archivo; debe ser pasado utilizando el encabezado “Authoriza- tion”.
Parámetros de salida
200	archivo	Archivo	Archivo firmado. El contenido del archivo se de- vuelve en formato binario, mientras que el nombre del mismo se informa a través del header “Content-Disposition”.
304	mensaje	Texto	Sin Mensaje
403	mensaje	Texto	Mensaje indicando que la clave de seguridad no es correcta.
404	mensaje	Texto	Mensaje indicando que el proceso de firma no existe o ya está expirado.

Obtener Información sobre las firmas de un archivo.

Datos generales
Descripción		Permite al módulo frontend obtener un archivos firmados co- rrespondiente a un proceso de firma.
Método HTTP		GET
Path		/api/externos/archivo/{identificador}
Entrada		No tiene
Salida		application/octet-stream
Parámetros de entrada
identificador		UUID	Obligatorio; identificador del archivo para el cual se desea obtener su correspondiente archivo fir- mado.
clave_seguridad		Texto	Obligatorio; clave de seguridad correspondiente al proceso de firma al cual pertenece el archivo; debe ser pasado utilizando el encabezado “Authoriza- tion”.
Parámetros de salida
200	archivo	Archivo	Archivo firmado. El contenido del archivo se devuelve en formato binario, mientras que el nombre del mismo se informa a través del header “Con- tent-Disposition”.
304	mensaje	Texto	Sin mensaje
403	mensaje	Texto	Mensaje indicando que la clave de seguridad no es correcta.
404	mensaje	Texto	Mensaje indicando que el proceso de firma no existe o ya está expirado.

Etiquetas

Agencia de Gobierno Electrónico y Sociedad de la Información y del Conocimiento

Manual de integración para consumo de APIs de Firma.gub.uy

Descripción de APIS

Etiquetas