Uso de clientes

Autenticador

Permite la autenticación de personas usando la identificación

class pyfva.clientes.autenticador.ClienteAutenticador(negocio=1, entidad=1, time_manager=None)

Permite autenticar una persona utilizando los servicios del BCCR

Note

Recuerde la política del banco es no nos llame, nosotros lo llamamos

Parameters:

• negocio – número de identificación del negocio (provisto por el BCCR)
• entidad – número de identificación de la entidad (provisto por el BCCR)

DEFAULT_ERROR = {'codigo_error': 1, 'codigo_verificacion': 'N/D', 'id_solicitud': 0, 'texto_codigo_error': 'Ha ocurrido algún problema al solicitar la firma o autenticación.', 'tiempo_maximo': 1}

get_now()

solicitar_autenticacion(identificacion, id_funcionalidad=-1)

Solicita al BCCR la autenticación de la identificacion, recuerde, la política del BCCR es: no nos llame, nosotros lo llamamos, por lo que los valores devueltos corresponden al estado de la petición y no al resultado de la firma

Parameters:

• identificacion – número de identificación de la persona ver Formato identificacion.
• id_funcionalidad – Identificación de la funcionalidad del programa externo, se usa para dar seguimiento a la operación, * No obligatorio

Retorna una diccionario con los siguientes elementos, en caso de error retorna DEFAULT_ERROR.

Returns:codigo_error: Número con el código de error 0 es éxito

texto_codigo_error: Descripción del error

codigo_verificacion: str con el código de verificación de la trasacción, se muestra al usuario

tiempo_maximo: Tiempo máximo de duración de la solicitud en segundos

id_solicitud: Número de identificación de la solicitud

validar_servicio()

Valida si el servicio está disponible.

Returns:True si lo está o False si ocurrió algún error contactando al BCCR o el servicio no está disponible

extrae_resultado(solicitud, resultado)

Convierte la infromación obtenida del servicio SOAP a python

Parameters:

• solicitud – Objeto de solicitud del tipo pyfva.soap.autenticador.SolicitudDeAutenticacion
• resultado – Objeto de respuesta del tipo pyfva.soap.autenticador.RecibaLaSolicitudDeAutenticacionResult

Retorna una diccionario con los siguientes elementos, en caso de error retorna DEFAULT_ERROR.

Returns:codigo_error: Número con el código de error 0 es éxito

texto_codigo_error: Descripción del error

codigo_verificacion: str con el código de verificación de la trasacción

tiempo_maximo: Tiempo máximo de duración de la solicitud en segundos

id_solicitud: Número de identificación de la solicitud

Firmador

Permite firmar documentos en formato xml, odf y Microsoft office usando los servicios del BCCR

class pyfva.clientes.firmador.ClienteFirmador(negocio=1, entidad=1, time_manager=None)

Permite firmar un documento utilizando los servicios del BCCR.

Los documentos que se pueden firmar son:

• XML: con cofirma y contrafirma
• MSOffice: .docx, .xlsx y .pptx
• ODF: .odt, .ods y .odp
• PDF: .pdf

Note

Recuerde la política del banco es no nos llame, nosotros lo llamamos

Parameters:

• negocio – número de identificación del negocio (provisto por el BCCR)
• entidad – número de identificación de la entidad (provisto por el BCCR)

DEFAULT_ERROR = {'codigo_error': 1, 'codigo_verificacion': 'N/D', 'id_solicitud': 0, 'texto_codigo_error': 'Ha ocurrido algún problema al solicitar la firma o autenticación.', 'tiempo_maximo': 1}

get_now()

firme(identidad, documento, formato, algoritmo_hash='Sha512', hash_doc=None, resumen='', id_funcionalidad=-1, lugar=None, razon=None)

Firma cualquier documento enviado distinguiendo por el parámtetro formato cual método de firma llamar

Parameters:

• identidad – Identidad del suscriptor a firmar
• documento – Documento a firmar en base64
• formato – Formato del documento, puede ser xml_cofirma, xml_contrafirma, odf, msoffice, pdf
• algoritmo_hash – Algoritmo utilizado para calcular el hash_doc, puede ser sha256, sha384, sha512
• hash_doc – hash del documento aplicando el algoritmo hash
• resumen – Información resumida para mostar al suscriptor que describe el documento
• id_funcionalidad – Identificación de la funcionalidad del programa externo, se usa para dar seguimiento a la operación, * No obligatorio
• lugar – Lugar donde se realizó la firma (solo PDF)
• razon – Razon de firma para PDF (solo PDF)

Retorna una diccionario con los siguientes elementos, en caso de error retorna DEFAULT_ERROR.

Returns:codigo_error: Número con el código de error 1 es éxito

texto_codigo_error: Descripción del error

codigo_verificacion: str con el código de verificación de la trasacción, se muestra al usuario

tiempo_maximo: Tiempo máximo de duración de la solicitud en segundos

id_solicitud: Número de identificación de la solicitud

firme_xml(identidad, documento, algoritmo_hash='Sha512', hash_doc=None, resumen='', id_funcionalidad=-1, _type='cofirma')

Firma un documento XML,

Note

Los parámetros exceptuando formato (no existe en este método) son idénticos que los de firme, además los resultados retornados son también idénticos.

firme_odf(identidad, documento, algoritmo_hash='Sha512', hash_doc=None, resumen='', id_funcionalidad=-1)

Firma un documento del tipo ODF.

Note

Los parámetros exceptuando formato (no existe en este método) son idénticos que los de firme, además los resultados retornados son también idénticos.

firme_msoffice(identidad, documento, algoritmo_hash='Sha512', hash_doc=None, resumen='', id_funcionalidad=-1)

Firma un documento del tipo Microsoft office.

Note

Los parámetros exceptuando formato (no existe en este método) son idénticos que los de firme, además los resultados retornados son también idénticos.

firme_pdf(identidad, documento, algoritmo_hash='Sha512', hash_doc=None, resumen='', id_funcionalidad=-1, lugar=None, razon=None)

Firma un documento del tipo PDF.

Note

Los parámetros exceptuando formato (no existe en este método) son idénticos que los de firme, además los resultados retornados son también idénticos.

suscriptor_conectado(identificacion)

Verifica si un suscriptor está conectado.

Parameters:identificacion – Identificación del suscriptor Returns:True si la tarjeta del suscriptor está conectada, False si no lo está.

validar_servicio()

Verifica si el servicio está disponible

Returns:True si el servicio está disponible, False si no lo está.

extrae_resultado(solicitud, resultado)

Convierte la infromación obtenida del servicio SOAP a python

Parameters:

• solicitud – Objeto de solicitud del tipo pyfva.soap.firmador.SolicitudDeFirma
• resultado – Objeto de respuesta del tipo pyfva.soap.firmador.RecibaLaSolicitudDeFirmaXmlEnvelopedCoFirmaResult

Retorna una diccionario con los siguientes elementos, en caso de error retorna DEFAULT_ERROR.

Returns:codigo_error: Número con el código de error 0 es éxito

texto_codigo_error: Descripción del error

codigo_verificacion: str con el código de verificación de la trasacción

tiempo_maximo: Tiempo máximo de duración de la solicitud en segundos

id_solicitud: Número de identificación de la solicitud

Sello Electrónico

Permite firmar documentos con sello electrónico en formato xml, odf y Microsoft office usando los servicios del BCCR

class pyfva.clientes.sellador.ClienteSellador(negocio=1, entidad=1, time_manager=None)

Permite firmar con sello electrónico un documento utilizando los servicios del BCCR.

Los documentos que se pueden firmar son:

• XML: con cofirma y contrafirma
• MSOffice: .docx, .xlsx y .pptx
• ODF: .odt, .ods y .odp
• PDF: .pdf

Note

El número de entidad no se usa en sello electrónico

Parameters:

• negocio – número de identificación del negocio (provisto por el BCCR)
• entidad – número de identificación de la entidad (provisto por el BCCR)

HASH_IDS = {1: 'sha256', 2: 'sha384', 3: 'sha512'}

DEFAULT_ERROR = {'codigo_error': 1, 'documento': None, 'fue_exitosa': False, 'hash_documento': None, 'id_algoritmo_hash': 'sha256', 'texto_codigo_error': 'Ha ocurrido algún problema al solicitar la firma.'}

get_now()

firme(documento, formato, algoritmo_hash='Sha512', hash_doc=None, id_funcionalidad=-1, lugar=None, razon=None)

Firma con sello electrónico cualquier documento enviado distinguiendo por el parámtetro formato cual método de firma llamar

Parameters:

• documento – Documento a firmar en base64
• formato – Formato del documento, puede ser xml_cofirma, xml_contrafirma, odf, msoffice, pdf
• algoritmo_hash – Algoritmo utilizado para calcular el hash_doc, puede ser sha256, sha384, sha512
• hash_doc – hash del documento aplicando el algoritmo hash
• id_funcionalidad – Identificación de la funcionalidad del programa externo, se usa para dar seguimiento a la operación, * No obligatorio
• lugar – Lugar donde se realizó la firma (solo PDF)
• razon – Razon de firma para PDF (solo PDF)

Retorna una diccionario con los siguientes elementos, en caso de error retorna DEFAULT_ERROR.

Returns:codigo_error: Número con el código de error 1 es éxito

texto_codigo_error: Descripción del error

fue_exitosa: Verdadero si se pudo sellar, falso si hay un error

documento: Documento en base64 si fue_exitosa True

hash_documento: hash del documento en base64 si fue_exitosa True

id_algoritmo_hash: algoritmo con el que se calculó la suma hash opciones: sha256, sha384, sha512

firme_xml(documento, algoritmo_hash='Sha512', hash_doc=None, id_funcionalidad=-1, _type='cofirma')

Firma un documento XML,

Note

Los parámetros exceptuando formato (no existe en este método) son idénticos que los de firme, además los resultados retornados son también idénticos.

firme_odf(documento, algoritmo_hash='Sha512', hash_doc=None, id_funcionalidad=-1)

Firma un documento del tipo ODF.

Note

Los parámetros exceptuando formato (no existe en este método) son idénticos que los de firme, además los resultados retornados son también idénticos.

firme_msoffice(documento, algoritmo_hash='Sha512', hash_doc=None, id_funcionalidad=-1)

Firma un documento del tipo Microsoft office.

Note

Los parámetros exceptuando formato (no existe en este método) son idénticos que los de firme, además los resultados retornados son también idénticos.

firme_pdf(documento, algoritmo_hash='Sha512', hash_doc=None, id_funcionalidad=-1, lugar=None, razon=None)

Firma un documento del tipo PDF.

Note

Los parámetros exceptuando formato (no existe en este método) son idénticos que los de firme, además los resultados retornados son también idénticos.

validar_servicio()

Verifica si el servicio está disponible

Returns:True si el servicio está disponible, False si no lo está.

extrae_resultado(solicitud, resultado)

Convierte la infromación obtenida del servicio SOAP a python

Parameters:

• solicitud – Objeto de solicitud del tipo pyfva.soap.firmador.SolicitudDeFirma
• resultado – Objeto de respuesta del tipo pyfva.soap.firmador.RecibaLaSolicitudDeSelladoElectronicoXmlEnvelopedCoFirmaResult

Retorna una diccionario con los siguientes elementos, en caso de error retorna DEFAULT_ERROR.

Returns:codigo_error: Número con el código de error 1 es éxito

texto_codigo_error: Descripción del error

fue_exitosa: Verdadero si se pudo sellar, falso si hay un error

documento: Documento en base64 si fue_exitosa True

hash_documento: hash del documento en base64 si fue_exitosa True

id_algoritmo_hash: algoritmo con el que se calculó la suma hash opciones: sha256, sha384, sha512

Validador Antiguo

class pyfva.clientes.validador.ClienteValidador(negocio=1, entidad=1)

Permite validar una firma o un documento utilizando los servicios del BCCR

Los documentos que se pueden validar son:

• Certificados digitales (CA nacional)
• XML: con cofirma y contrafirma
• MSOffice: .docx, .xlsx y .pptx
• ODF: .odt, .ods y .odp
• PDF: .pdf

Note

Los parámetros negocio y entidad de momento no son requeridos, pero puede que en un futuro cercano lo sean, por lo que se recomienda suministrarlos.

Parameters:

• negocio – número de identificación del negocio (provisto por el BCCR)
• entidad – número de identificación de la entidad (provisto por el BCCR)

DEFAULT_CERTIFICATE_ERROR = {'certificado': None, 'codigo_error': 1, 'exitosa': False, 'texto_codigo_error': 'Error interno al validar el certificado.'}

DEFAULT_DOCUMENT_ERROR(ERRORES_VALIDA)

validar_documento(documento, formato)

Valida si el documento está firmado correctamente.

NOTA: Esta versión está obsoleta y tiene problemas de validación de algunos documentos, usar la versión V2 disponible ene este paquete.

Parameters:

• documento – documento xml en base64
• formato – tipo de documento a validar (cofirma, contrafirma, msoffice, odf).

Retorna una diccionario con los siguientes elementos, en caso de error retorna DEFAULT_DOCUMENT_ERROR.

Note

Observe que en caso de no ser exitosa la operación los atributos ‘advertencias’, ‘errores_encontrados’ y ‘firmantes’ retornarán None

Returns:codigo_error: Número con el código de error 0 es éxito

texto_codigo_error: Descripción del error

exitosa: True si fue exitoso el verificado del documento, False si no lo fue

advertencias: Lista de advertencias encontradas durante el proceso de validadación, algo como: [“adv1”, “adv2”]

errores_encontrados: Lista de errores encontrados y su respectivo detalle, ej [(“código de error”, “Detalle del error”), …]

firmantes: Lista de información del los firmantes, ej [ {‘identificacion’: “8-0888-0888”, ‘fecha_firma’: datetime.now(), ‘nombre’: “Juanito Mora Porras”}, … ]

validar_certificado_autenticacion(certificado)

Valida si el certificado de autenticación es válido y no está revocado.

Parameters:certificado – Certificado en base64

Retorna una diccionario con los siguientes elementos, en caso de error retorna DEFAULT_CERTIFICATE_ERROR.

Returns:codigo_error: Número con el código de error 0 es éxito

texto_codigo_error: Descripción del error

exitosa: True si fue exitosa, False si no lo fue

certificado: Si la operación no fue exitosa retorna None, si lo fue retorna un diccionario con:

identificacion: Número de identificación del suscriptor dueño del certificado

nombre: Nombre completo del suscriptor dueño del certificado

inicio_vigencia: Fecha de inicio del vigencia del certificado

fin_vigencia: Fecha de finalización de la vigencia del certificado

validar_servicio(servicio)

Valida si el servicio está disponible.

Parameters:servicio – tipo de servicio a validar, puede ser ‘certificado’ o ‘documento’ Returns:True si lo está o False si ocurrió algún error contactando al BCCR o el servicio no está disponible

Validador

class pyfva.clientes.validadorv2.ClienteValidador(negocio=1, entidad=1)

Permite validar una firma o un documento utilizando los servicios del BCCR

Los documentos que se pueden validar son:

• Certificados digitales (CA nacional)
• XML: con cofirma y contrafirma
• MSOffice: .docx, .xlsx y .pptx
• ODF: .odt, .ods y .odp
• PDF: .pdf

Note

Los parámetros negocio y entidad de momento no son requeridos, pero puede que en un futuro cercano lo sean, por lo que se recomienda suministrarlos.

Parameters:

• negocio – número de identificación del negocio (provisto por el BCCR)
• entidad – número de identificación de la entidad (provisto por el BCCR)

DEFAULT_CERTIFICATE_ERROR = {'certificado': None, 'codigo_error': 1, 'exitosa': False, 'texto_codigo_error': 'Error interno al validar el certificado.'}

DEFAULT_DOCUMENT_ERROR(ERRORES_VALIDA)

validar_documento(documento, formato)

Valida si el documento está firmado correctamente.

Parameters:

• documento – documento xml en base64
• formato – tipo de documento a validar (cofirma, contrafirma, msoffice, odf).

Retorna una diccionario con los siguientes elementos, en caso de error retorna DEFAULT_DOCUMENT_ERROR.

Note

Observe que en caso de no ser exitosa la operación los atributos ‘advertencias’, ‘errores_encontrados’ y ‘firmantes’ retornarán None

Returns:codigo_error: Es 0 si el resultado fue exitoso, 1 si existe algún error.

texto_codigo_error: Texto de información sobre el código de error.

exitosa: La transacción fue exitosa.

firmas: Listado de firmas en el documento.

• es_valida: La firma encontrada es válida.
• es_avanzada: Es una firma avanzada.
• error: Ha ocurrido un error al validar la firma.
• detalle_de_error: Texto de detalle del error encontrado si existe.
• garantia_de_integridad_y_autenticidad: La firma garantiza la integridad y autenticidad del documento
• garantia_de_validez_tiempo: Datos de la garantía del tiempo.
• detalle: Detalle de la firma.
• autoria_del_firmante: La firma garantiza la autoría del firmante

resumen: Resumen de resultados de validación del documento, contiene los elementos

’integridad’, ‘jerarquia_de_confianza’, ‘vigencia’, ‘tipo_de_certificado’, ‘revocacion’, ‘fecha_de_firma’ Cada uno de los elementos tiene los siguientes campos (‘estado’, ‘se_evalua’, ‘respuesta’, ‘codigo’)

errores: Errores encontrados al validar el documento

validar_certificado_autenticacion(certificado)

Valida si el certificado de autenticación es válido y no está revocado.

Parameters:certificado – Certificado en base64

Retorna una diccionario con los siguientes elementos, en caso de error retorna DEFAULT_CERTIFICATE_ERROR.

Returns:codigo_error: Número con el código de error 0 es éxito

texto_codigo_error: Descripción del error

exitosa: True si fue exitosa, False si no lo fue

certificado: Si la operación no fue exitosa retorna None, si lo fue retorna un diccionario con:

identificacion: Número de identificación del suscriptor dueño del certificado

nombre: Nombre completo del suscriptor dueño del certificado

inicio_vigencia: Fecha de inicio del vigencia del certificado

fin_vigencia: Fecha de finalización de la vigencia del certificado

validar_servicio(servicio)

Valida si el servicio está disponible.

Parameters:servicio – tipo de servicio a validar, puede ser ‘certificado’ o ‘documento’ Returns:True si lo está o False si ocurrió algún error contactando al BCCR o el servicio no está disponible

Verificador

class pyfva.clientes.verificador.ClienteVerificador(negocio=1, entidad=1)

Verifica si una firma ha sido completada

Note

Los parámetros negocio y entidad de momento no son requeridos, pero puede que en un futuro cercano lo sean, por lo que se recomienda suministrarlos.

Parameters:

• negocio – número de identificación del negocio (provisto por el BCCR)
• entidad – número de identificación de la entidad (provisto por el BCCR)

DEFAULT_ERROR = {'codigo_error': 1, 'existe_firma': False, 'fue_exitosa': False, 'texto_codigo_error': 'Ha ocurrido algún problema al verificar el estado de la firma.'}

existe_solicitud_de_firma_completa(identificacion)

Verifica si una solicitud de firma ha sida completada por el usuario en el sistema del BCCR

Parameters:identificacion – número de identificación de la persona

Retorna una diccionario con los siguientes elementos, en caso de error retorna DEFAULT_ERROR.

Returns:codigo_error: Número con el código de error 0 es éxito

texto_codigo_error: Descripción del error

exitosa: True si fue exitosa, False si no lo fue

existe_firma: Retorna True si hay un proceso de firma activo o False si no.

validar_servicio()

Valida si el servicio está disponible.

Returns:True si lo está o False si ocurrió algún error contactando al BCCR o el servicio no está disponible