API de Comunicación

DFVA 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 DFVA: una institución (institution) con el uuid proporcionado en dfva y una persona (person) con su número de identificación (ver formato).

DFVA 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
  • sign_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
  • sign_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

AuthenticatePersonRequestViewSet.person(request, *args, **kwargs)[fuente]
POST /authenticate/person/

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
AuthenticatePersonRequestViewSet.person_show(request, *args, **kwargs)[fuente]
POST /authenticate/{code}/person_show/

Solicita un estado de la solicitud 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

Firma

SignPersonRequestViewSet.person(request, *args, **kwargs)[fuente]
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
  • sign_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
SignPersonRequestViewSet.person_show(request, *args, **kwargs)[fuente]
POST /sign/{code}/person_show/

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
  • sign_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

Validación

ValidatePersonViewSet.person_certificate(request, *args, **kwargs)[fuente]
POST /validate/person_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”

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.

ValidatePersonViewSet.person_document(request, *args, **kwargs)[fuente]
POST /validate/person_document/

Solicita una verificación de firma de un documento xml

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
  • warnings: Lista de advertencias
  • errors: Lista de errores encontrados en el documento del tipo [ {“codigo”: “codigo”,”descripcion”: “descripción”}, … ]
  • signers: Lista con la información de los firmantes [ {“identification”: “08-8888-8888”, “full_name”: “nombre del suscriptor”, “signature_date”: timezone.now()}, … ]
  • was_successfully: Si la verificación del certificado fue exitosa

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

ValidateSubscriptorPersonViewSet.person_suscriptor_connected(request, *args, **kwargs)[fuente]
POST /validate/person_suscriptor_connected/

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

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.create(request, *args, **kwargs)[fuente]

Nota

Esta vista no está encriptada.

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.

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
  • sign_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”