Manual del Servicio de Sobres (Envelopes) para Kuenta

Este documento explica cómo funciona el servicio de sobres (envelopes) en Kuenta, detallando las variables disponibles, las funciones que se pueden utilizar y el flujo de trabajo para la gestión de documentos y firmas.

Descripción General

El servicio de sobres (Envelope Service) es un componente central para la gestión de documentos y firmas en Kuenta. Permite:

Crear sobres con documentos a firmar
Gestionar destinatarios (recipients) y sus solicitudes de firma
Notificar a los destinatarios por email y SMS
Procesar documentos antes y después de las firmas
Validar firmas y verificar a los firmantes
Generar y verificar hashes de documentos para garantizar su integridad

Estructura de Datos Disponibles

Envelope (Sobre)

type Envelope struct {
    ID               uuid.UUID
    Title            string
    Order            bool                  // Indica si los documentos deben firmarse en orden específico
    FillBeforeSign   bool                  // Indica si se debe completar el perfil antes de firmar
    ProfilesComplete bool                  // Indica si todos los perfiles están completos
    ParseBeforeSign  bool                  // Indica si se debe analizar el documento antes de firmar
    Status           domain.EnvelopeStatus // Estado del sobre
    Hash             string                // Hash para integridad
    OwnerID          uuid.UUID             // ID de la organización propietaria
    SenderID         uuid.UUID             // ID del usuario remitente
    Templates        []*domain.Template    // Plantillas asociadas
    Recipients       []*domain.Recipient   // Destinatarios
    Documents        []*domain.Document    // Documentos generados
}

Recipient (Destinatario)

type Recipient struct {
    ID                 uuid.UUID
    EnvelopeID         uuid.UUID
    EntityID           uuid.UUID
    PartyProfileID     uuid.UUID
    Entity             *domain.Entity
    Order              uint8                // Orden para firmar (si Order=true en Envelope)
    RecipientStatus    domain.PartieStatus  // Estado del destinatario
    Notify             domain.NotifyMethods // Métodos de notificación (email, sms)
    EnvelopeSignature  bool                 // Si ha firmado todos los documentos
    Code               string               // Código para destinatarios no registrados
    SignatureRequests  []*domain.SignatureRequest // Solicitudes de firma
    PartyProfile       *domain.Profile      // Perfil del destinatario
    TargetProfile      *domain.TargetProfile // Datos de contacto
    LRRestriction      bool                 // Restricción para representantes legales
}

Document (Documento)

type Document struct {
    ID              uuid.UUID
    TemplateID      uuid.UUID
    SenderID        uuid.UUID
    CreditorID      uuid.UUID
    Status          domain.DocumentStatus
    Hash            string
    EnvelopeHash    string
    PDFFileID       uuid.UUID
    ParseBeforeSign bool
    SignatureRequests []*domain.SignatureRequest
    Template        *domain.Template
    Creditor        *domain.Entity
}

SignatureRequest (Solicitud de Firma)

type SignatureRequest struct {
    ID                  uuid.UUID
    DocumentID          uuid.UUID
    RecipientID         uuid.UUID
    TemplateID          uuid.UUID
    PartyNumber         uint8
    Status              uint8
    SignatureRestriction domain.SignatureRestriction // Métodos permitidos para firmar
    Document            *domain.Document
    Template            *domain.Template
    Recipient           *domain.Recipient
}

Signature (Firma)

type Signature struct {
    ID               uuid.UUID
    DocumentID       uuid.UUID
    PartyProfileID   uuid.UUID
    ProxyProfileID   uuid.UUID
    CodeMethod       domain.CodeMethod     // Método para enviar código (SMS, Email, Call)
    SignatureMethod  domain.SignatureMethod // Método de firma (TOTP, PhoneEmail)
    Code             string                // Código de verificación
    SecretKey        string                // Clave secreta para TOTP
    Phone            string                // Teléfono para enviar código
    CodeDate         time.Time             // Fecha de generación del código
    CodeDateUnix     int64                 // Fecha en unix para verificación
    PartyProfile     *domain.Profile       // Perfil del firmante
    ProxyProfile     *domain.Profile       // Perfil del apoderado (si aplica)
}

Flujo de Trabajo del Servicio de Sobres

Creación de un Sobre

Se inicia con una llamada a CreateFromForm o Create
Se validan los destinatarios y sus emails
Se crean plantillas temporales si es necesario
Se valida el número de partes en los documentos
Se crea el sobre en la base de datos
Se crean los destinatarios asociados al sobre
Se generan los documentos a partir de las plantillas
Se crean las solicitudes de firma
Se actualiza el estado del sobre

Notificación a Destinatarios

El servicio puede notificar a los destinatarios por email y SMS:

Si FillBeforeSign es true y ProfilesComplete es false, solo se notifica a destinatarios con perfiles incompletos
Si Order es true, solo se notifica al primer destinatario en la secuencia
Para entidades legales, se notifica a todos los representantes autorizados

Proceso de Firma

El destinatario recibe la notificación con un enlace al sobre
Si es necesario, completa su perfil (FillBeforeSign)
Si ParseBeforeSign es true, los documentos se procesan justo antes de firmar
Se genera un código de verificación para la firma (TOTP)
El destinatario ingresa el código para confirmar su firma
Si Order es true, al completar una firma se notifica al siguiente destinatario
Cuando todos los documentos están firmados, el sobre se marca como completado

Variables Disponibles en Plantillas de Notificación

Para Emails

.Organization - La organización propietaria del sobre
.Entity       - La entidad destinataria
.URL          - Enlace al sobre (con código de acceso si es necesario)
.Title        - Título del sobre como HTML

Para SMS

.Organization - Datos básicos de la organización
.URL          - Enlace al sobre
.Title        - Título del sobre

Funciones para Plantillas

Las plantillas usadas en las notificaciones por email y SMS tienen acceso a:

{{ if }}...{{ else }}...{{ end }}   - Condiciones
{{ range .Items }}...{{ end }}      - Ciclos
{{ with .Object }}...{{ end }}      - Establecer contexto
{{ date .SomeDate }}                - Formatear fecha
{{ currency .Amount }}              - Formatear moneda
{{ commonData .Profile "FieldName" }} - Acceder a datos comunes de perfil

Ejemplos de Uso

Notificación por Email para Firmar Documento

html

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>Documento para firmar</title>
    </head>
    <body>
        <h1>Documento para firmar: {{ .Title }}</h1>
        <p>Estimado/a {{ commonData .Entity.Profile "Name" }},</p>

        <p>
            Has recibido un documento para firmar de parte de {{ commonData
            .Organization.Profile "Name" }}.
        </p>

        <p>
            Para acceder al documento y firmarlo, haz clic en el siguiente
            enlace:
        </p>

        <a
            href="{{ .URL }}"
            style="display: inline-block; padding: 10px 20px; background-color: #007bff; color: white; text-decoration: none; border-radius: 5px;"
            >Ver y firmar documento</a
        >

        <p>
            Si tienes alguna pregunta, contacta directamente con el remitente.
        </p>

        <p>
            Saludos,<br />
            El equipo de Kuenta
        </p>
    </body>
</html>

Notificación SMS para Firmar Documento

{{.Organization.Name}} te ha enviado un documento para firmar: {{.Title}}. Accede aquí: {{.URL}}

Notificación de Código de Verificación

Tu código de verificación para firmar el documento es: {{.Code}}. Válido por 5 minutos.

Seguridad y Verificación

Generación de Hash

El servicio genera hashes para garantizar la integridad de los documentos:

Se genera un hash único para cada documento usando SHA-3
El sobre también tiene un hash general que incluye los hashes de todos sus documentos
Las firmas se validan contra estos hashes para prevenir manipulaciones

Verificación de Firmantes

Para entidades legales, el servicio verifica si el firmante es un representante legal autorizado mediante:

representants, err := envsrv.legalSrv.FindLegalRepresentants(ctx, recipient.PartyProfile.Legal)
if err != nil {
    return false, err
}

for _, rep := range *representants {
    if entity.ID == rep.EntityID {
        return true, nil
    }
}

Mejores Prácticas

Configuración adecuada de sobres:
- Utiliza Order = true cuando los documentos deben firmarse en un orden específico
- Usa FillBeforeSign = true cuando necesites información adicional de los destinatarios
- Activa ParseBeforeSign = true para documentos que necesitan procesarse justo antes de firmarse
Notificaciones efectivas:
- Incluye detalles claros del documento en las notificaciones
- Ofrece múltiples métodos de notificación (email y SMS)
- Personaliza los mensajes con el nombre del destinatario
Seguridad:
- Utiliza verificación TOTP para firmas importantes
- Verifica siempre la identidad de los firmantes en entidades legales
- Mantén los códigos de verificación con períodos cortos de validez

Solución de Problemas Comunes

Destinatarios que no reciben notificaciones

Verifica que el email y teléfono estén correctos en el perfil
Asegúrate de que los métodos de notificación estén configurados correctamente
Si Order = true, solo el destinatario actual en la secuencia recibirá notificaciones

Problemas con firmas

Verifica que el perfil del firmante esté completo si FillBeforeSign = true
Comprueba que el código de verificación no haya expirado
Para entidades legales, asegúrate de que el firmante sea un representante autorizado

Errores en el procesamiento de documentos

Verifica que las plantillas contengan los campos esperados
Asegúrate de que los PDF tengan los campos de formulario correctamente definidos
Comprueba que los perfiles de los destinatarios contengan toda la información necesaria

Limitaciones

El número máximo de destinatarios por sobre depende de la configuración del sistema
Los códigos de verificación TOTP tienen una validez limitada
El tamaño de los documentos PDF está limitado por la configuración del sistema
Las notificaciones SMS tienen un límite de caracteres

Manual del Servicio de Sobres (Envelopes) para Kuenta ​

Descripción General ​

Estructura de Datos Disponibles ​

Envelope (Sobre) ​

Recipient (Destinatario) ​

Document (Documento) ​

SignatureRequest (Solicitud de Firma) ​

Signature (Firma) ​

Flujo de Trabajo del Servicio de Sobres ​

Creación de un Sobre ​

Notificación a Destinatarios ​

Proceso de Firma ​

Variables Disponibles en Plantillas de Notificación ​

Para Emails ​

Para SMS ​

Funciones para Plantillas ​

Ejemplos de Uso ​

Notificación por Email para Firmar Documento ​

Notificación SMS para Firmar Documento ​

Notificación de Código de Verificación ​

Seguridad y Verificación ​

Generación de Hash ​

Verificación de Firmantes ​

Mejores Prácticas ​

Solución de Problemas Comunes ​

Destinatarios que no reciben notificaciones ​

Problemas con firmas ​

Errores en el procesamiento de documentos ​

Limitaciones ​