Crear una petición

Método para la creación de una nueva petición.

• Tipo: POST
• URL: url-inbox/api/v3/requests
• Tipo de entrada: application/json
• Tipo de salida: application/json

Json de entrada

El json de entrada está compuesto por los siguientes campos:

• publicAccessId: Código de la petición. En caso de no indicarse de autogenerará uno.
• sender: Remitente de la petición. En caso de no indicarse se tomará el usuario genérico para el web service como usuario remitente. Los datos a indicar son:
  • userCode: Código de usuario.
  • entityCode: Código de la entidad del remitente. En caso de no indicarse se tomará la entidad por defecto del usuario.
• addresseeWorkflow: Código público de un workflow de usuarios definido en viafirma inbox. Campo obligatorio a no ser que se indique los destinatarios en el campo addresseeLines.

• addresseeLines: Sólo para peticiones en las que no se ha indicado del campo addresseeWorkflow, en cuyo caso es un campo obligatorio. Líneas de los destinatarios de la petición. Cada línea de destinatarios está compuesto por una lista de grupos de destinatarios (addresseeGroups). Cada uno de estos grupos tiene los siguientes campos:

  • isOrGroup: true si sólo uno de los usuarios del grupo tiene que realizar la acción. Por defecto false.
  • userEntities: Lista de usuarios que componen el grupo. Cada uno de estos elementos puede venir dado por tres diferentes criterios: a través de su código de usuario y de entidad, o a partir de un código de cargo o de grupo. Los cargos o grupos indicados se reemplazarán por todos los usuarios que los componen.
    • userCode: Person ID del usuario. En caso de usuarios de firma desatendida debe indicarse el alias, si es firma con viafirma platform, o el código del certificado, si es firma con viafirma fortress.
    • entityCode: Código de la entidad del destinatario. En caso de no indicarse se tomará la entidad por defecto del usuario.
    • jobCode: Código del cargo
    • groupCode: Código del grupo
    • userName: Nombre del usuario si se trata de un usuario externo que no existe y debe darse de alta en el sistema.
    • userSurname1: Primer apellido del usuario si se trata de un usuario externo que no existe y debe darse de alta en el sistema.
    • userSurname2: Segundo apellido del usuario si se trata de un usuario externo que no existe y debe darse de alta en el sistema.
    • userPhone: Teléfono del usuario si se trata de un usuario externo que no existe y debe darse de alta en el sistema.

  También se puede indicar el tipo de acción a realizar en el campo action cuyos posibles valores son SIGN y APPROVAL, siendo SIGN el valor por defecto en caso de no indicarse ninguno.

• internalNotification: Listado de usuarios que formarán parte de la comunicación interna asociada a la petición. Se indicará el código de usuario de cada uno de estos usuarios.
• subject: Asunto de la petición. Campo obligatorio.
• message: Mensaje de la petición.
• reference: Referencia.
• initDate: Fecha de inicio de la petición.
• expirationDate: Fecha de caducidad de la petición.
• verificationAccess: Tipo de acceso a la verificación de la petición. Se deben indicar los siguientes campos:
  • type: Tipo de acceso. Por defecto ANONYMOUS. Los posibles valores son:
    • NOTAVAILABLE: La petición no está accesible desde el apartado de verificación.
    • ANONYMOUS: Cualquier usuario tiene acceso a la petición.
    • USERPASSWORD: Acceso mediante usuario y contraseña.
    • CERTIFICATE: Requiere autenticación con certificado. Y debe tratarse de uno de los usuarios que forman parte de la petición. Es decir que sea el remitente o uno de los destinatarios.
    • PRIVATE: Tan sólo el remitente tiene acceso a la verificación.
  • username: Usuario para el acceso a la petición para el tipo USERPASSWORD.
  • password: Contraseña para el acceso a la petición para el tipo USERPASSWORD.
• senderNotificationLevel: Nivel de notificaciones para el remitente de la petición. Los valores permitidos son:
  • NO: El remitente no recibe notificaciones para esta petición.
  • ALL: El remitente recibe notificaciones cada vez que un destinatario lee, firma, da visto bueno o rechaza. También recibirá una notificación cuando finalice la petición.
  • MEDIUM: El remitente recibe notificaciones cada vez que un destinatario firma, da visto bueno o rechaza. También recibirá una notificación cuando finalice la petición.
  • FINISH: EL remitente recibirá una notificación cuando finalice la petición.
• notificationUrl (deprecated): URL a la que notificaremos tras cada acción realizada en una petición de firma (creación, firma, visto bueno, rechazo, caducidad y borrado).
• callbackCode: Código del callback definido en el sistema al que notificaremos tras cada acción realizada en una petición de firma (creación, firma, visto bueno, rechazo, caducidad y borrado). Esta opción sustituye a notificationUrl.
• stampName: Nombre o código del sello a emplear.
• useDefaultStamp: Indica si se una el sello por defecto.
• metadatas: Listado de metadatas de la petición. Para cada metadata se indican:
  • key
  • value

• documentsToSign: Listado de documentos a firmar. Campo obligatorio. Los documentos pueden venir dados de 3 formas distintas, dependiendo de cual se emplee se deberán indicar unos campos u otros.

  • csv: Código seguro de verificación personalizado para el documento. En caso de no indicarse se generará uno automáticamente. Se emplea para la generación de la url de verificación dependiendo de la configuración del sello.
  • verificationUrl: Url para la verificación del documento. Se emplea dependiendo de la configuración del sello.

  Para documentos generados a partir de plantillas existentes en viafirma inbox debe rellenar el campo template que está compuesto por los campos:

  • code: Código de la plantilla.
  • vars: Lista de variables para crear la plantilla. Para cada variable se indicas los campos:
    • key
    • value

  Para documentos en base 64 se deben indicar los siguientes campos:

  • filename: Nombre del documento.
  • base64: Contenido del documento en base64.

  Para documentos disponibles en una url externa se deben indicar los siguientes campos:

  • filename: Nombre del documento.
  • url: Url para la descarga del documento.

  Además se se debe indicar las posiciones de las firmas para usuarios externos con firma web o para todo los usuarios si el sello de firma es de tipo sello individual. Para cada usuario, debe indicarse la posición del sello y el usuario al que corresponde. Los campos userCode y entityCode deben coincidir con los indicados en addresseeLines. Las posiciones de los sellos se hacen con una lista llamada stampPositions:

  • stampPositions: Array de posiciones del sello de firma en el caso de firmas web. Cada posición viene dada por los campos:
    • page: Página en la que se ubicará la firma.
    • height: Altura de la firma.
    • width: Anchura de la firma.
    • x: Posición x de la firma.
    • y: Posición y de la firma.
    • userCode: Código del usuario firmante.
    • entityCode: Código de la entidad del usuario firmante.

• documentsAnnexes: Listado de documentos anexos. Se rellenan de forma análoga a los documents a firmar.

• signWithCertificate: En caso de valer true la firma de la petición deberá realizarse usando un sistema de firma con certifiado. En caso contrario la petición puede ser firmada con cualquier sistema de firma (deprecado en favor del siguiente parámetro)
• signatureLevel: Nivel de firma admitido para la petición. Los valores permitidos son:
  • ALL: Cualquier tipo (certificado, OTP SMS, firma web...). Valor por defecto.
  • CERTIFICATE_OTP_SMS: Se admite solo certificado y OTP SMS.
  • CERTIFICATE_ONLY: Solo firma con certificado digital.
• autoReminderPeriodicity: En el caso de que esté activada por configuración la opción "Activar el envío de recordatorios automáticos a los destinatarios", este parámetro permite indicar cada cuántos días se envía por email un recordatorio al firmante que todavía no ha hecho su acción.
• autoReminderAttempts: Número máximo de recordatorios que se enviarán al usuario firmante. Si se da un valor a autoReminderPeriodicity debe informarse también éste, ya que no toma un valor por defecto (si solo se informa un valor, no se guarda ninguna configuración de recordatorios para la petición).
• disableInboxEmailNotifications: Si se envía este parámetro opcional con valor "true", Inbox no enviará ningún email a los participantes de la petición: creador, destinatarios, comunicaciones internas... por lo que la aplicación cliente será la responsable de realizar las notificaciones por email.

Ejemplo de JSON de entrada

Json de salida

El json de salida será el mismo que el del servicio obtener datos de una petición

Ejemplo de JSON de salida