--- title: "Atualizando o Signer da versão 2.x para 3.x" description: "Passos extras para atualizar o Signer on-premises de 2.x para 3.x, como instalar o ASP.NET Core Runtime 10.0 e acompanhar as migrações de banco de dados." canonical: "https://docs.lacunasoftware.com/articles/signer/on-premises/update-30" locale: "pt-BR" product: "Signer" last_updated: "2026-10-16" --- # Atualizando o Signer da versão 2.x para 3.x Antes de atualizar sua instância [on-premises](https://docs.lacunasoftware.com/articles/signer/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](https://docs.lacunasoftware.com/articles/signer/on-premises/update-20). > **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](https://docs.lacunasoftware.com/articles/signer/on-premises/update-30#parte-1): instalar o runtime, revisar as mudanças, configurar e atualizar. * [Parte 2: Breaking changes e mudanças de banco de dados](https://docs.lacunasoftware.com/articles/signer/on-premises/update-30#parte-2): o que pode afetar integrações e o banco de dados. ## 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](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) * Linux * [Ubuntu Server](https://docs.lacunasoftware.com/articles/signer/on-premises/linux/install-ubuntu#install-aspnet-core): 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](https://docs.lacunasoftware.com/articles/signer/on-premises/update-30#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: ```sh 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](https://docs.lacunasoftware.com/articles/signer/on-premises/update-30-documents-index): 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](https://docs.lacunasoftware.com/articles/signer/on-premises/documentusers-index): 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).