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”