API de Comunicación

SIFVA es una aplicación RESTFull por lo que usa JSON como modelo de representación de objetos, los objetos son enviados vía POST sobre un canal de comunicación HTTPS. Las peticiones tienen el siguiente formato:

  • data_hash: Suma hash de datos de tamaño máximo 130 caracteres, usando el algoritmo especificado

  • algorithm: Algoritmo con que se construye data_hash, debe ser alguno de los siguientes: sha256, sha384, sha512

  • public_certificate: Certificado de autenticación

  • data: Datos de solicitud de autenticación encriptados usando AES con la llave de sesión encriptada con PKCS1_OAEP.

  • encrypt_method: (opcional, por defecto: «aes_eax») Método de encripción del contenido («aes_eax», «aes-256-cfb»)

Además se envía un atributo identificador que depende del tipo de conversación que se quiera entablar, actualmente se pueden comunicar con SIFVA: una institución (institution) con el uuid proporcionado en dfva y una persona (person) con su número de identificación (ver formato).

SIFVA verifica que data_hash sea igual al generado a partir de data utilizando el algoritmo indicado.

Las respuestas tienen el siguiente formato:

  • data_hash: Suma hash de datos de tamaño máximo 130 caracteres, usando el algoritmo especificado

  • algorithm: Algoritmo con que se construye data_hash, debe ser alguno de los siguientes: sha256, sha384, sha512 por defecto sha515

  • data: Datos de respuesta encriptados usando AES Modo EAX con la llave de sesión encriptada con PKCS1_OAEP.

Instituciones

Autenticación

AuthenticateRequestViewSet.institution(request, *args, **kwargs)[fuente]
POST /authenticate/institution/

Solicita una petición de autenticación para un usuario

Los valores a suministrar en el parámetro data son:

  • institution: uid de la institucion ver code en detalles de institución,

  • notification_url: URL para la notificación (debe estar inscrita) o N/D si marca falso en not_webapp,

  • identification: Identificación de la persona a autenticar,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

  • encrypt_method: (opcional, default: «aes_eax») Método de encripción de segunda fase. («aes_eax», «aes-256-cfb»)

Data es un diccionario, osea un objeto de tipo clave -> valor

Los valores devueltos son:

  • expiration_datetime: hora final de validez

  • request_datetime: Hora de recepción de la solicitud

  • id_transaction: Id de trasnacción en el FVA del BCCR

  • status: Código de error de la transacción

  • status_text Descripción para humanos del código de error

  • identification: Identificador del suscriptor

  • code: Código para mostrar al usuario

  • received_notification: True si la autenticación ha sido procesada, False si está esperando al usuario

  • resume: Resumen de la transacción.

  • hash_docsigned: Normalmente Null, Base64 hash del documento firmado si el documento existe

  • hash_id_docsigned: 0- no se ha firmado 1- Sha256, 2- Sha384, 3- Sha512

AuthenticateRequestViewSet.institution_show(request, *args, **kwargs)[fuente]
POST /authenticate/{id_transaction}/institution_show/

Solicita el estado de una petición de autenticación para un usuario

Los valores a suministrar en el parámetro data son:

  • institution: uid de la institucion ver code en detalles de institución,

  • notification_url: URL para la notificación (debe estar inscrita) o N/D si marca falso en not_webapp,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

Data es un diccionario, osea un objeto de tipo clave -> valor

id_transaction Corresponde al id de la trasnacción del BCCR

Los valores devueltos son:

  • expiration_datetime: hora final de validez

  • request_datetime: Hora de recepción de la solicitud

  • id_transaction: Id de trasnacción en el FVA del BCCR

  • status: Código de error de la transacción

  • status_text Descripción para humanos del código de error

  • identification: Identificador del suscriptor

  • code: Código para mostrar al usuario

  • received_notification True si la autenticación ha sido procesada, False si está esperando al usuario

  • resume: Resumen de la transacción.

  • hash_docsigned: Base64 hash del documento firmado si el documento existe

  • hash_id_docsigned: 0- no se ha firmado 1- Sha256, 2- Sha384, 3- Sha512

AuthenticateRequestViewSet.institution_delete(request, *args, **kwargs)[fuente]
POST /authenticate/{id_transaction}/institution_delete/

Elimina una petición de autenticación para un usuario

Los valores a suministrar en el parámetro data son:

  • institution: uid de la institucion ver code en detalles de institución,

  • notification_url: URL para la notificación (debe estar inscrita) o N/D si marca falso en not_webapp,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

Data es un diccionario, osea un objeto de tipo clave -> valor

id_transaction Corresponde al id de la trasnacción del BCCR

Los valores devueltos son:

  • result True/False si se eliminó la petición o no

Firma

SignRequestViewSet.institution(request, *args, **kwargs)[fuente]
POST /sign/institution/

Solicita una firma de un documento xml, odf o msoffice para un usuario

Los valores a suministrar en el parámetro data son:

  • institution: uid de la institucion ver code en detalles de institución,

  • notification_url: URL para la notificación (debe estar inscrita) o N/D si marca falso en not_webapp,

  • document: Archivo en base64,

  • format: tipo de archivo (xml_cofirma, xml_contrafirma, odf, msoffice, pdf),

  • algorithm_hash: algoritmo usado para calcular hash,

  • document_hash: hash del documento,

  • resumen: Información de ayuda acerca del documento,

  • identification: Identificación de la persona a autenticar,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

  • reason: Razón de firma PDF (obligatorio solo en PDF)

  • place: Lugar de firma en PDF (obligatorio solo en PDF)

Data es un diccionario, osea un objeto de tipo clave -> valor

Los valores devueltos son:

  • expiration_datetime: hora final de validez

  • request_datetime: Hora de recepción de la solicitud

  • id_transaction: Id de trasnacción en el FVA del BCCR

  • signed_document: Normalmente None, es un campo para almacenar el documento, pero no se garantiza que venga el documento firmado

  • status: Código de error de la transacción

  • status_text Descripción para humanos del código de error

  • identification: Identificador del suscriptor

  • code: Código para mostrar al usuario

  • received_notification True si la autenticación ha sido procesada, False si está esperando al usuario

  • resume: Resumen de la transacción.

  • hash_docsigned: Normalmente Null, Base64 hash del documento firmado si el documento existe

  • hash_id_docsigned: 0- no se ha firmado 1- Sha256, 2- Sha384, 3- Sha512

SignRequestViewSet.institution_show(request, *args, **kwargs)[fuente]
POST /sign/{id_transaction}/institution_show/

Verifica la firma dado un código y si respectiva identificación

Los valores a suministrar en el parámetro data son:

  • institution: uid de la institucion ver code en detalles de institución,

  • notification_url: URL para la notificación (debe estar inscrita) o N/D si marca falso en not_webapp,

  • identification: Identificación de la persona a autenticar,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

Data es un diccionario, osea un objeto de tipo clave -> valor

id_transaction Corresponde al id de la trasnacción del BCCR

Los valores devueltos son:

  • expiration_datetime: hora final de validez

  • request_datetime: Hora de recepción de la solicitud

  • id_transaction: Id de trasnacción en el FVA del BCCR

  • signed_document: Normalmente None, es un campo para almacenar el documento, pero no se garantiza que venga el documento firmado

  • status: Código de error de la transacción

  • status_text Descripción para humanos del código de error

  • identification: Identificador del suscriptor

  • code: Código para mostrar al usuario

  • received_notification True si la autenticación ha sido procesada, False si está esperando al usuario

  • resume: Resumen de la transacción.

  • hash_docsigned: Normalmente Null, Base64 hash del documento firmado si el documento existe

  • hash_id_docsigned: 0- no se ha firmado 1- Sha256, 2- Sha384, 3- Sha512

SignRequestViewSet.institution_delete(request, *args, **kwargs)[fuente]
POST /sign/{id_transaction}/institution_delete/

Elimina una petición de firma dado un código de transacción del BCCR

Los valores a suministrar en el parámetro data son:

  • institution: uid de la institucion ver code en detalles de institución,

  • notification_url: URL para la notificación (debe estar inscrita) o N/D si marca falso en not_webapp,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

Data es un diccionario, osea un objeto de tipo clave -> valor

id_transaction Corresponde al id de la trasacción del BCCR

Los valores devueltos son:

  • result True/False si se eliminó la petición o no

Validación

ValidateInstitutionViewSet.institution_certificate(request, *args, **kwargs)[fuente]
POST /validate/institution_certificate/

Solicita una de un certificado de autenticación para un usuario

Los valores a suministrar en el parámetro data son:

  • institution: uid de la institucion ver code en detalles de institución,

  • notification_url: URL para la notificación (debe estar inscrita) o N/D si marca falso en not_webapp,

  • document: Archivo en base64 del certificado,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

Data es un diccionario, osea un objeto de tipo clave -> valor

Los valores devueltos son:

  • identification: Identificación del suscriptor

  • request_datetime: Hora de recepción de la solicitud

  • code: Código de identificación de la transacción (no es el mismo que el que se muestra en al usuario en firma)

  • status: Estado de la solicitud

  • status_text: Descripción en texto del estado

  • full_name: Nombre completo del suscriptor

  • start_validity: Inicio de la vigencia del certificado

  • end_validity: Fin de la vigencia del certificado

  • was_successfully: Si la verificación del certificado fue exitosa

Nota: Si la validación del certificado no fue exitosa, entonces los campos de identificación, full_name, start_validity, end_validity deben ignorase o son nulos.

ValidateInstitutionViewSet.institution_document(request, *args, **kwargs)[fuente]
POST /validate/institution_document/

Solicita una verificación de firma de un documento xml

Los valores a suministrar en el parámetro data son:

  • institution: uid de la institucion ver code en detalles de institución,

  • notification_url: URL para la notificación (debe estar inscrita) o N/D si marca falso en not_webapp,

  • document: Archivo en base64 del certificado,

  • format: Formato de documento a validar disponibles (cofirma, contrafirma, msoffice, odf)

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

Data es un diccionario, osea un objeto de tipo clave -> valor

Los valores devueltos son:

  • identification: Identificación del suscriptor

  • request_datetime: Hora de recepción de la solicitud

  • code: Código de identificación de la transacción (no es el mismo que el que se muestra en al usuario en firma)

  • status: Estado de la solicitud

  • status_text: Descripción en texto del estado

  • was_successfully: Si la verificación del certificado fue exitosa

  • warnings: Lista de advertencias

  • errors: Lista de errores encontrados en el documento del tipo [ {“code”: “codigo”,”description”: “descripción”}, … ]

  • signers: Lista con la información de los firmantes

    [ {“identification_number”: “08-8888-8888”, “full_name”: “nombre del suscriptor”, “signature_date”: timezone.now()}, … ]

Nota: Si la validación del documento no fue exitosa, entonces los campos de firmantes deben ignorase o son nulos.

ValidateSubscriptorInstitutionViewSet.institution_suscriptor_connected(request, *args, **kwargs)[fuente]
POST /validate/institution_suscriptor_connected/

Verifica si una persona está conectada (es contactable por el BCCR).

Los valores a suministrar en el parámetro data son:

  • institution: uid de la institucion ver code en detalles de institución,

  • notification_url: URL para la notificación (debe estar inscrita) o N/D si marca falso en not_webapp,

  • identification: Identificación de la persona a buscar,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

Data es un diccionario, osea un objeto de tipo clave -> valor

Retorna:

is_connected: True si la persona está conectada, false si no lo está

Personas

Autenticación

class person.authenticator.views.AuthenticatePersonView(**kwargs)[fuente]

Solucitud de autenticación de una persona

POST /person/authenticate/

Solicita una petición de autenticación para un usuario

Los valores a suministrar en el parámetro data son:

  • person: identificación de la persona solicitante de autenticación,

  • identification: Identificación de la persona a autenticar,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

Data es un diccionario, osea un objeto de tipo clave -> valor

Los valores devueltos son:

  • expiration_datetime: hora final de validez

  • request_datetime: Hora de recepción de la solicitud

  • id_transaction: Id de trasnacción en el FVA del BCCR

  • status: Código de error de la transacción

  • identification: Identificador del suscriptor

  • code: Código para mostrar al usuario

  • received_notification True si la autenticación ha sido procesada, False si está esperando al usuario

  • signed_document Siempre es None puesto que el documento todavía no se ha firmado a este punto

  • duration Tiempo en segundos que dura la transacción

Solucitud de información de una transacción de autenticación

GET /person/authenticate/{transaction_id}/

Solicita un estado de la solicitud de autenticación para un usuario

Los valores a suministrar en el parámetro data son:

  • transaction_id: identificación de la transacción de autenticación de la que se requiere información

Data es un diccionario, osea un objeto de tipo clave -> valor

Los valores devueltos son:

  • expiration_datetime: hora final de validez

  • request_datetime: Hora de recepción de la solicitud

  • id_transaction: Id de trasnacción en el FVA del BCCR

  • status: Código de error de la transacción

  • identification: Identificador del suscriptor

  • code: Código para mostrar al usuario

  • received_notification True si la autenticación ha sido procesada, False si está esperando al usuario

  • signed_document Documento firmado en base64 o None si aún no se ha firmado la autenticación

  • duration Tiempo en segundos que dura la transacción

Elimina la información de la transacción de autenticación

DELETE /person/authenticate/{transaction_id}/

Los valores devueltos son:

No tiene valores devueltos

Firma

class person.signer.views.SignPersonView(**kwargs)[fuente]

Solucitud de Firma de documentos de una persona

POST /sign/person/

Solicita una firma de un documento xml, odf o msoffice para un usuario

Los valores a suministrar en el parámetro data son:

  • person: identificación de la persona solicitante de firma,

  • notification_url: URL para la notificación (debe estar inscrita) o N/D si marca falso en not_webapp,

  • document: Archivo en base64,

  • format: tipo de archivo (xml_cofirma,xml_contrafirma, odf, msoffice),

  • algorithm_hash: algoritmo usado para calcular hash,

  • document_hash: hash del documento,

  • resumen: Información de ayuda acerca del documento,

  • identification: Identificación de la persona a firmar,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

Data es un diccionario, osea un objeto de tipo clave -> valor

Los valores devueltos son:

  • expiration_datetime: hora final de validez

  • request_datetime: Hora de recepción de la solicitud

  • id_transaction: Id de trasnacción en el FVA del BCCR

  • signed_document: Normalmente None, es un campo para almacenar el documento, pero no se garantiza que venga el documento firmado

  • status: Código de error de la transacción

  • identification: Identificador del suscriptor

  • code: Código para mostrar al usuario

  • received_notification True si la autenticación ha sido procesada, False si está esperando al usuario

  • duration Tiempo en segundos que dura la transacción

Solucitud de información de una transacción de firmado

GET /person/sign/{transaction_id}/

Verifica la firma dado un código y su respectiva identificación

Los valores a suministrar en el parámetro data son:

  • person: identificación de la persona solicitante de firma,

  • identification: Identificación de la persona a autenticar,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

Data es un diccionario, osea un objeto de tipo clave -> valor

Los valores devueltos son:

  • expiration_datetime: hora final de validez

  • request_datetime: Hora de recepción de la solicitud

  • id_transaction: Id de trasnacción en el FVA del BCCR

  • status: Código de error de la transacción

  • identification: Identificador del suscriptor

  • code: Código para mostrar al usuario

  • received_notification True si la autenticación ha sido procesada, False si está esperando al usuario

  • signed_document Documento firmado en base64 o None si aún no se ha firmado la autenticación

  • duration Tiempo en segundos que dura la transacción

Elimina la información de la transacción de firma

DELETE /person/authenticate/{transaction_id}/

Los valores devueltos son:

No tiene valores devueltos

Validación

class person.validator.views.ValidateCertificatePersonViewSet(**kwargs)[fuente]

Valida si un certificado de la jerarquía nacional es válido.

POST /person/validate_certificate

Solicita una de un certificado de autenticación para un usuario

Los valores a suministrar en el parámetro data son:

  • person: Identificación de la persona validante,

  • document: Archivo en base64 del certificado,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

  • format Debe ser siempre «certificate»

Data es un diccionario, osea un objeto de tipo clave -> valor

Los valores devueltos son:

  • identification: Identificación del suscriptor

  • request_datetime: Hora de recepción de la solicitud

  • code: Código de identificación de la transacción (no es el mismo que el que se muestra en al usuario en firma)

  • status: Estado de la solicitud

  • codigo_de_error: Códigos de error del certificado, si existen

  • full_name: Nombre completo del suscriptor

  • start_validity: Inicio de la vigencia del certificado

  • end_validity: Fin de la vigencia del certificado

  • was_successfully: Si la verificación del certificado fue exitosa

Nota: Si la validación del certificado no fue exitosa, entonces los campos de identificación, nombre_completo, inicio_vigencia, fin_vigencia deben ignorase o son nulos.

class person.validator.views.ValidateDocumentPersonViewSet(**kwargs)[fuente]

Solicita una verificación de firma de un documento

POST /person/validate_document/

Los valores a suministrar en el parámetro data son:

  • person: Identificación de la persona validante,

  • document: Archivo en base64 del certificado,

  • format: Formato del documento a validar disponibles (cofirma, contrafirma, msoffice, odf)

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

Data es un diccionario, osea un objeto de tipo clave -> valor

Los valores devueltos son:

  • identification: Identificación del suscriptor

  • request_datetime: Hora de recepción de la solicitud

  • code: Código de identificación de la transacción (no es el mismo que el que se muestra en al usuario en firma)

  • status: Estado de la solicitud

  • status_text: Descripción en texto del estado

  • was_successfully: Si la verificación del certificado fue exitosa

  • validation_data Contiene la información de la validación en un diccionario con los siguientes campos

firmas: Lista de firmas presentes en el documento, una firma de ejemplo podría ser algo así

 {'es_valida': True, 'es_avanzada': True, 'error': False, 'detalle_de_error': '',
'garantia_de_integridad_y_autenticidad': True,
'garantia_de_validez_tiempo': [0, 'Tiene Garantía'],
'detalle': {'integridad': {'estado': False, 'se_evalua': True, 'respuesta': 'ok', 'codigo': 1},
'jerarquia_de_confianza': {'estado': 0, 'se_evalua': True, 'respuesta': 'ok', 'codigo': 1},
'vigencia': {'estado': False, 'se_evalua': True, 'respuesta': 'ok', 'codigo': 1},
'tipo_de_certificado': {'estado': 0, 'se_evalua': True, 'respuesta': 'ok', 'codigo': 1},
'revocacion': {'estado': 0, 'se_evalua': True, 'respuesta': 'ok', 'codigo': 1},
'fecha_de_firma': {'estado': False, 'se_evalua': True, 'respuesta': 'ok',
                    'codigo': 1, 'fecha_de_estama': '2021-05-20T00:00:00Z'}},
 'autoria_del_firmante': {'nombre': 'Joan Lucas Arce', 'identificacion': '0408880888',
                           'tiene_autoria': True}}

resumen: Resumen de las firmas (una versión con menos campos de las firmas)

{'firmante': 'Luis Madrigal Viquez', 'identificacion': '0208880888',
'garantia_de_integridad_y_autenticidad': True, 'garantia_validez_en_el_tiempo': True,
'resultado': 0, 'fecha_estampa_de_tiempo': '2021-05-20T23:30:16Z',
'tipo_identificacion': 0, 'tiene_fecha_estampa_de_tiempo': True}

errores: Cadena de texto con mensajes de error presentes en las firmas del documento

class person.validator.views.ValidateSubscriptorPersonViewSet(**kwargs)[fuente]

Verifica si una persona está conectada (es contactable por el BCCR).

POST /person/validate_suscriptor/

Los valores a suministrar en el parámetro data son:

  • person: Identificación de la persona validante,

  • identification: Identificación de la persona a buscar,

  • request_datetime: Hora de petición en formato “%Y-%m-%d %H:%M:%S”, osea “2006-10-25 14:30:59”

Data es un diccionario, osea un objeto de tipo clave -> valor

Retorna:

is_connected: True si la persona está conectada, false si no lo está

Login

PersonLoginView.list(request, *args, **kwargs)[fuente]

Gestiona la operación de verdad, para la generación de token a firmar. En el flujo se solicita a esta vista 2 operadores y una función de operación, luego el cliente calcula el resultado y lo envía firmado a la vísta vía POST, SIFVA valida el resultado y lo compara con lo enviado, si ambos son iguales entonces autentica al usuario.

GET /login/

Parámetros GET

  • serial: Serial de la tarjeta con la cual autenticarse.

  • person: Identificación de la persona

Response:

  • transaction_id: ID del objeto de autenticación.

  • operatorA: Operadorador izquierdo

  • operand: Operadorador

  • operatorB: Operadorador derecho

PersonLoginView.create(request, *args, **kwargs)[fuente]

Autentica el usuario usando una prueba de verdad.

POST /login/

Permite a una persona autenticarse en DFVA, un token de sección es retornado y deberá ser usuado para encriptar la comunicación.

Los valores a suministrar son:

  • data_hash: Suma hash de datos de tamaño máximo 130 caracteres, usando el algoritmo especificado

  • algorithm: Algoritmo con que se construye data_hash, debe ser alguno de los siguientes: sha256, sha384, sha512

  • public_certificate: Certificado de autenticación del dispositivo pkcs11

  • person: Identificación de la persona,

  • code: Identificación de la persona firmada con la llave privada del certificado de autenticación.

  • transaction_id: Id de transacción usado para determinar la operación.

Los valores devueltos son:

  • identification: Identificación del suscriptor

  • token: Token de sección para encriptar atributo data posteriormente

  • expiration_datetime_token: Hora máxima para usar el token

  • last_error_code: Código de estado de la transacción

  • error_text: Descripción de los errores encontrados

Notififcación para Instituciones

receptor.notify.send_notification(data, serializer=None, request=None, encrypt_method='aes_eax')[fuente]

Envia notificación a la institución, cuando se recibe una respuesta por parte del BCCR, este método reenvía la respuesta a la URL especificada en la petición.

La estructura de envío es:

Params id_transaction

Id de transacción del BCCR

Params data

Es un diccionario con los siguientes atributos

  • code: Código de identificación de la transacción (no es el mismo que el que se muestra en al usuario en firma)

  • identification: Identificador del suscriptor

  • id_transaction: Id de trasnacción en el FVA del BCCR

  • request_datetime: Hora de recepción de la solicitud

  • signed_document: Almacena el documento, pero no se garantiza que venga el documento firmado, puede ser None

  • expiration_datetime: Hora de recepción de la solicitud

  • received_notification: True si la autenticación ha sido procesada, False si está esperando al usuario

  • duration: tiempo que duró entre que fue enviada y fue recibida

  • status: Código de error de la transacción

  • status_text: Descripción en texto del estado

Params hashsum

Suma hash realizada a data

Params algorithm

Algoritmo con el que se realizó la suma hash

Por defecto se utiliza el método de encripción seleccionado al realizar la petición por parte de la institución, pero en caso de no lograrse identificar el método se utiliza por defecto “aes_eax”