Pular para o conteúdo principal

Atualizando o Signer da versão 2.x para 3.x

Antes de atualizar sua instância on-premises da versão 2.x para a 3.x, é preciso seguir alguns passos adicionais.

observação

Se a sua instância ainda está na versão 1.x, siga primeiro a página Atualizando para 2.x.

aviso

É fortemente recomendado fazer a atualização em um horário de pouco uso. Depois da atualização, jobs em segundo plano podem aumentar temporariamente a carga e o consumo do banco de dados, principalmente em tabelas grandes.

Sumário​

Parte 1: Como atualizar​

Siga os passos abaixo na ordem.

1. Instalar o ASP.NET Core Runtime 10.0​

A versão 3.0.0 migrou a plataforma do .NET 8 para o .NET 10. Instale o ASP.NET Core Runtime 10.0 na plataforma que você utiliza:

  • Windows: instale o Hosting Bundle do .NET 10.0
  • Linux
    • Ubuntu Server: instale o pacote aspnetcore-runtime-10.0 no lugar do aspnetcore-runtime-8.0
dica

Não é necessário desinstalar versões prévias do ASP.NET Core Runtime, pois múltiplas versões podem coexistir no mesmo ambiente sem problemas.

observação

No Docker, esse passo não é necessário pois as versões 3.x da imagem já vêm com o ASP.NET Core Runtime 10.0 embutido.

2. Fazer backup e revisar as mudanças​

Faça um backup do banco de dados antes de atualizar e leia a Parte 2. Se você integra com o Signer por API ou Webhooks, revise suas integrações antes de atualizar. Para manter o comportamento anterior da pausa de documentos, defina General:EnableDocumentPause como false.

3. Update Signer​

Após seguir os passos acima, proceda com as instruções de atualização normais.

Solucionando erros de timeout do banco de dados após o update​

Se você enfrentar erros durante o primeiro início da aplicação após a atualização e o log indicar que ocorreu um timeout ao aplicar as migrações de banco de dados, você deverá executar o utilitário de linha de comando para iniciar as migrações de maneira manual usando um parâmetro de timeout com valor maior que o padrão:

  1. Pare a aplicação.

  2. Navegue até a pasta aonde se encontram os binários da aplicação.

  3. Execute o comando:

    dotnet Lacuna.Signer.Site.dll -- update-db EventUserAgent --timeout 6000

  4. Reinicie a aplicação.

Azure App Services​

Se sua instância está hospedada no Azure App Services:

  1. No portal do Azure, acesse as configurações do App Service.
  2. Selecione Configuration, e depois selecione a aba General settings
  3. Na seção Stack settings:
    1. A configuração de Stack deve estar definida como .NET
    2. A configuração .NET version, deve estar definida como .NET 10 (LTS)
dica

A seção Stack settings mencionada acima só aparece para App Service Plan de plataforma Windows. Para planos baseados em plataforma Linux, nenhuma mudança é necessária.

Parte 2: Breaking changes e mudanças de banco de dados​

As mudanças mais importantes da 3.0.0 para quem atualiza a partir da 2.x.

Mudanças de banco de dados​

A versão 3.0.0 aplica as migrações AddDocumentsReportIndex, Spa8, SignerPositioningAndSignatureSheet, SignatureSheetBounds e EventUserAgent na primeira inicialização.

  • O índice Documents (SubscriptionId, CreationDateUtc), usado pelos relatórios de documentos, é criado por um job em segundo plano após a atualização, e não durante a migração. Veja Índice de Documents: o que ele melhora, como é criado e o que fazer se a criação automática falhar.
  • Se você está atualizando de uma versão anterior à 2.21.0, a atualização também aplica a desnormalização de DocumentUsers com índice (SIG-780), o que pode causar um período de maior lentidão e maior consumo de banco de dados na instância. Veja Índice de DocumentUsers: o que ele melhora, como é criado e o que fazer se a criação automática falhar. Instâncias que já estão na 2.21.0 ou superior não são afetadas.
  • A atualização do Hangfire para a versão 1.8 não altera o esquema das tabelas do Hangfire no banco de dados: o esquema permanece na versão 7 e não há nenhuma ação necessária. Por isso, é seguro voltar para a versão 2.x caso seja preciso reverter a atualização.

Integrações por API e Webhooks: pausa de documentos​

A pausa de documentos (SIG-1937) introduz mudanças que podem quebrar integrações existentes. Revise suas integrações antes de atualizar, ou defina General:EnableDocumentPause como false para manter o comportamento anterior.

API

  • O status do documento (DocumentStatus) ganhou o novo valor Paused. Um documento pausado passa a ser retornado com status Paused em vez de Pending. Integrações que tratam o status de forma exaustiva (por exemplo switch sem caso padrão) ou que desserializam o enum de forma estrita podem falhar. Trate Paused como um documento em andamento, igual a Pending.
  • O filtro de status Pending na listagem de documentos continua incluindo os documentos pausados. Use o novo valor Paused para listar apenas os pausados.
  • A listagem de documentos retorna os novos campos IsPaused e CanResume, e os endpoints públicos retornam IsDocumentPaused. Em documentos pausados a ação pendente do participante (PendingFlowAction) não é preenchida.
  • Novos endpoints: POST /api/documents/{id}/pause (com o motivo opcional Reason, de até 500 caracteres) e POST /api/documents/{id}/resume. Ambos exigem a permissão PauseDocument.
  • Enquanto o documento está pausado, as operações abaixo falham com novos códigos de erro (ErrorCodes) em vez de serem executadas: assinar, aprovar e recusar (CannotSignPausedDocument, CannotApprovePausedDocument, CannotRefusePausedDocument), editar o fluxo, editar as informações, adicionar versão, reiniciar o fluxo, remover assinatura, enviar arquivos, editar e-mails notificados, enviar lembretes e gerar link de compartilhamento. Cancelar o documento continua permitido. Integrações que assinam, aprovam ou editam documentos em lote devem tratar esses erros.
  • Os lembretes automáticos não são enviados para documentos pausados.

Webhooks

  • Dois novos tipos de webhook, DocumentPaused (10) e DocumentResumed (11), são enviados para todos os endpoints de webhook já cadastrados, sem necessidade de configuração. Endpoints que rejeitam ou falham ao receber um tipo desconhecido devem ser ajustados antes da atualização, para ignorar os novos tipos.
  • O Data do DocumentPaused traz o documento e os campos PausedBy e Reason. O do DocumentResumed traz o documento e ResumedBy.
  • Enquanto o documento está pausado, os webhooks de assinatura, aprovação ou conclusão do fluxo não são disparados, pois nenhuma dessas ações pode ocorrer.

Outras mudanças na API​

Comparação do Swagger da versão 2.22.2 com o da 3.0.0. Todas são aditivas (nenhum endpoint, campo ou schema foi removido), com as ressalvas indicadas.

  • Posicionamento da assinatura pelo signatário (SIG-1936):
    • Novo endpoint PUT /api/documents/{id}/signer-positioning, que define signerPositioningEnabled e automaticSignaturePositioning (Disabled, Footnote ou SignatureSheet) para o documento. null usa a configuração atual da organização. Só é possível alterar até a primeira assinatura (SignerPositioningLockedAfterSignature).
    • CreateDocumentRequest aceita signerPositioningEnabled e automaticSignaturePositioning; DocumentModel retorna esses campos e signatureSheetFirstPage.
    • FlowActionModel retorna visualRepresentationOnFootnote e DocumentMarkModel retorna isAutoPositioned.
    • POST /api/documents/{id}/flow aceita o parâmetro acceptFootnoteVisualRepresentation. Em um documento já assinado cuja folha de assinaturas não tem mais espaço, a edição é rejeitada com SignatureSheetFull, a menos que o parâmetro seja true.
    • Novos códigos de erro: SignerPositioningNotAllowed, SignerPositioningIncompatibleWithAutomaticPositioningDisabled, SignatureSheetFull e SignerPositioningLockedAfterSignature.
    • Atenção: o modo padrão de posicionamento automático (VisualRepresentation:AutomaticSignaturePositioning) é Footnote. Assinaturas sem posição definida passam a ser colocadas em um espaço livre do rodapé.
  • Listagem de documentos: novo parâmetro ParticipantSituation (Completed ou Pending) em GET /api/documents, para filtrar pela situação do participante pesquisado (SIG-1951).
  • Evidências: EvidencesModel retorna userAgent e consent (versão dos termos, data de aceite e hash SHA-256 dos termos), conforme as evidências de assinatura (SIG-1898) e o consentimento clickwrap (SIG-1899).
  • Identificadores: IdentifierTypes ganhou Ssn, Itin e Ein (SIG-1949). Integrações que desserializam o enum de forma estrita devem aceitar os novos valores.
  • Validações mais estritas. Requisições que antes eram aceitas podem passar a ser rejeitadas. Revise integrações que enviam estes dados:
    • E-mail: endereços com pontos consecutivos (por exemplo a..b@x.com) são rejeitados, pois o .NET 10 não consegue enviá-los. A validação vale para participantes de fluxos, e-mail de suporte da organização, campos de e-mail de modelos e contatos (por isso o schema de CreateContactRequest e UpdateContactRequest deixou de declarar o formato email). Endereços já armazenados não são alterados.
    • Telefone: a validação e a normalização de números passaram a usar a mesma leitura. Números sem o prefixo internacional (+ e código do país) são interpretados na região padrão (Brasil); envie números de outros países, como Paraguai e Equador, com o + e o código do país. Números rejeitados pelo Grant ID agora retornam erro de validação em vez de erro 500 (SIG-1923).
    • CNPJ: CNPJs alfanuméricos são gravados em maiúsculas (signatários, regras de assinatura, organizações, dados de cobrança e perfis de autenticação), e a edição de uma organização passou a validar o identificador como na criação.
    • Identificadores do Paraguai e do Equador: espaços no início e no fim são removidos e o formato é validado na criação de usuários com múltiplos identificadores, retornando erro de validação em vez de erro 500 (SIG-1942). O tamanho dos identificadores do Equador (RUC e demais) passou a ser realmente verificado, e valores com a quantidade de dígitos errada são rejeitados.
    • Identificadores dos EUA (SSN, ITIN e EIN): só aceitam os 9 dígitos ou o layout oficial com hífens; espaços e hífens fora de posição são rejeitados. Os endpoints de inclusão e alteração de identificador também validam os tipos permitidos em AllowedIdentifierTypes.
    • Anexos e modelos: a geração de documentos (GenerateDocumentsRequest) valida os anexos contra a lista de tipos MIME de anexos, e os arquivos de modelos são validados contra a lista de modelos. Espaços ao redor das entradas das listas de tipos MIME são ignorados (SIG-1948).
    • Conclusão pública de assinatura digital: o ticket enviado deve ser da ação de fluxo e do usuário que estão sendo concluídos; caso contrário a conclusão falha com InvalidTicket.
    • Reaproveitamento de conta por e-mail (hotfix 2.22.2): não é uma quebra, mas muda o resultado de um cenário. Em instâncias com identificador único (CPF como claim) no modo NullableUnique, adicionar um participante cujo e-mail já pertence a uma conta do Grant ID sem claim de CPF retornava EmailAlreadyBeingUsed; agora a conta existente é reaproveitada. O reaproveitamento só ocorre quando há exatamente uma conta com o e-mail, seu nome de usuário é o próprio e-mail, ela não tem CPF no Grant e nenhum CPF diferente está associado a ela ou ao CPF informado no Signer. Fora dessas condições o erro EmailAlreadyBeingUsed continua sendo retornado, e o modo Unique não foi alterado. O CPF não é gravado no Grant ID nesse reaproveitamento. Integrações que dependiam desse erro para detectar e-mails já cadastrados devem considerar o novo resultado.
    • Páginas das marcas: números de página negativos são resolvidos a partir da última página (-1) e páginas além do fim do documento são ajustadas à última página. A página 0 continua aceita (SIG-453).
Ver em Markdown