API para acceso remoto

Firmador Libre posee un pequeño servidor web que permite registrar documentos en la aplicación de forma remota. Para eso se dispone de la siguiente API:

Creación de documento

Registra un documento para firmar.

POST /create/<nombre_de_archivo>

  • El cuerpo de la petición debe ser el archivo binario (content-type: application/octet-stream).

  • Para cargar varios documentos a la vez, usar multipart/form-data y cada campo debe tener el nombre del documento.

  • Si es multipart, se ignora el nombre de la URL y se toma el nombre del campo.

  • Retorna HTTP 200 si el documento fue recibido correctamente.

Detalle y descarga de documento

Permite descargar el documento firmado, usando el mismo nombre utilizado en la carga.

GET /detail/<nombre_de_archivo>

  • Devuelve HTTP 204 si el documento aún no está firmado.

  • Devuelve HTTP 200 y el archivo firmado si ya está disponible.

  • Devuelve HTTP 404 si no existe el documento.

Eliminar documento

Elimina el documento cargado en el servidor.

DELETE /<nombre_de_archivo>

  • Devuelve HTTP 200 si fue eliminado.

  • Devuelve HTTP 404 si no existe.

Limpiar lista de documentos

Elimina todos los documentos en la lista del servidor.

GET /clean

Cerrar la aplicación cliente

Permite cerrar la aplicación, útil para integración con applets o tests automáticos.

GET /close

Firmar un documento

Solicita la firma de un documento de forma remota utilizando un dispositivo conectado.

POST /sign

  • El cuerpo debe ser un JSON con la información del documento y el número de serie del certificado a usar.

  • El servidor solicita el PIN al usuario.

  • Respuesta: JSON con la firma en base64 y metadatos del proceso.

  • Ejemplo de cuerpo (simplificado):

{
    "documentName": "test.pdf",
    "documentid": "91e88f73-7862-40a6-98df-4a7ac69bcda2",
    "serialnumber": "446022984826570188563016292465943406351728476",
    "tobesigned": {"bytes": "<base64>"},
    "hostname": "firmador",
    "certificate": "MIIFuz..."
}

Firma múltiple de documentos

Permite firmar varios documentos en una sola operación.

POST /multipleSign

[
    {
        "documentName": "test.pdf",
        "documentid": "91e88f73-7862-40a6-98df-4a7ac69bcda2",
        "serialnumber": "446022984826570188563016292465943406351728476",
        "tobesigned": {"bytes": "<base64>"},
        "hostname": "firmador",
        "certificate": "MIIFuz..."
    }
]

  • El cuerpo debe ser un array JSON con la información de cada documento.

  • Respuesta: Array de firmas para cada documento.

Obtener certificados disponibles

Devuelve una lista de las tarjetas/certificados disponibles.

GET /certificates

  • Respuesta: JSON con información de cada certificado conectado.

Autenticación remota

Realiza una autenticación remota usando la tarjeta.

POST /authenticate

  • El cuerpo debe ser un JSON con los datos de autenticación requeridos.

  • Respuesta: JSON con el resultado.

Registro/autorización de host

Permite registrar (autorizar) un nuevo origen (host) para poder interactuar con la API.

GET /doRegister

  • Si el origen no está autorizado, el usuario deberá autorizarlo manualmente en la interfaz.

  • Puede ser autorizado de forma permanente o temporal.

Control de CORS y orígenes permitidos

  • Todos los endpoints validan el header Origin.

  • Solo orígenes autorizados pueden interactuar con la API. Si el origen no está permitido, la respuesta será 403 y el error aparecerá en la interfaz gráfica.

Manejo de errores

  • Todos los endpoints pueden devolver códigos de error HTTP (400, 403, 404, 406, 500).

  • Los errores se notifican automáticamente en el panel de conexiones.