viafirma inbox :: manual de integración

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
      • jobCode
      • groupCode

    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.
  • senderNotificationsLevel: 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 recie 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 recie 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: URL a la que notificamos tras la finalización de cada acción de firma o visto bueno definida en el proceso de firma.
  • stampName: Nombre 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.

    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 la posición de las firmas para usuarios externos con firma web o para todo los usuarios si el sello de firma es de tipo sello individual. 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.

    • stampPosition: Posición del sello de firma en el caso de firmas web. La 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.

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