ForSign.Sdk 2.0.1

.NET 5.0 This package targets .NET 5.0. The package is compatible with this framework or higher. .NET Core 3.0 This package targets .NET Core 3.0. The package is compatible with this framework or higher. .NET Standard 2.0 This package targets .NET Standard 2.0. The package is compatible with this framework or higher. .NET Framework 4.5 This package targets .NET Framework 4.5. The package is compatible with this framework or higher.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package ForSign.Sdk --version 2.0.1
                    


                    

                
NuGet\Install-Package ForSign.Sdk -Version 2.0.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="ForSign.Sdk" Version="2.0.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="ForSign.Sdk" Version="2.0.1" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="ForSign.Sdk" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add ForSign.Sdk --version 2.0.1
                    


                    

                
#r "nuget: ForSign.Sdk, 2.0.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package ForSign.Sdk@2.0.1
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=ForSign.Sdk&version=2.0.1
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=ForSign.Sdk&version=2.0.1
                    


                            Install as a Cake Tool

Documentação Completa do SDK ForSign para .NET (v2)

🚀 1. Introdução ao SDK ForSign

Bem-vindo à documentação oficial do SDK ForSign para .NET! A ForSign oferece a integração mais simples do mercado de assinaturas eletrônicas digitais, fornecendo uma gama diversificada de soluções para tornar os processos de assinatura mais eficientes, seguros e amigáveis.

O SDK foi projetado para ser facilmente integrado à sua aplicação .NET, proporcionando uma experiência de assinatura digital sem complicações tanto para desenvolvedores quanto para usuários finais.

Principais Funcionalidades

  • Múltiplos Tipos de Assinatura: Suporte para vários estilos e métodos de assinatura (clique, desenho, rubrica, carimbo).
  • Segurança Reforçada: Inclui opções de duplo fator de autenticação (2FA) por e-mail e selfie para validar a identidade do signatário.
  • Workflows Flexíveis: Personalize o processo de assinatura para se adequar ao seu fluxo de trabalho, incluindo ordem de assinatura.
  • Formulários Dinâmicos: Crie formulários interativos para coletar informações adicionais durante o processo de assinatura.
  • Anexos: Solicite documentos e arquivos dos signatários de forma segura.
  • Gerenciamento de Operações: Controle total sobre o ciclo de vida das operações de assinatura (cancelar, finalizar, baixar).

🔧 2. Configuração Inicial (Getting Started)

Nesta seção, abordaremos os requisitos, a instalação do SDK e como configurar seu ambiente para começar a trabalhar.

Requisitos do Sistema

  • .NET Framework ou .NET Core/Standard: O SDK é compatível com uma vasta gama de versões do .NET (veja o .csproj para detalhes, incluindo .NET Framework 4.5+, .NET Standard 2.0+, e .NET 5 a 8).
  • IDE: Visual Studio, VS Code ou qualquer editor que suporte desenvolvimento .NET.

Instalação do SDK via NuGet

Para instalar o SDK, utilize o gerenciador de pacotes NuGet. Execute o seguinte comando no Console do Gerenciador de Pacotes ou no terminal:

dotnet add package ForSign.Sdk

Ou

Install-Package ForSign.Sdk

Configurando suas Credenciais de Acesso

Após a instalação, o primeiro passo é configurar suas credenciais. Você precisará de uma API Key, que pode ser obtida no painel de desenvolvedor da ForSign.

using ForSign.Sdk;

// 1. Crie uma instância do cliente ForSign
var forsignClient = new ForSignClient();

// 2. Substitua "SUA_API_KEY_AQUI" pela chave obtida no painel da ForSign
const string API_KEY = "SUA_API_KEY_AQUI";

// 3. Crie o objeto de credencial
var credential = new ApiKeyCredential(API_KEY);

// 4. Defina a credencial no cliente
forsignClient.SetCredential(credential);

// 5. (Opcional, mas recomendado) Autentique-se para obter um token de sessão
// O SDK gerencia o token automaticamente, mas esta chamada garante que suas credenciais estão corretas.
try
{
    await forsignClient.AuthenticateAsync();
    Console.WriteLine("Autenticação bem-sucedida!");
}
catch (Exception ex)
{
    Console.WriteLine($"Erro durante a autenticação: {ex.Message}");
    // Pare a execução se a autenticação falhar
    return;
}

⚠️ Dica de Segurança: Mantenha sua API Key segura! Nunca a exponha publicamente em código-fonte de front-end ou em repositórios públicos. Utilize variáveis de ambiente, cofres de segredos (como Azure Key Vault) ou outras ferramentas de gerenciamento de segredos.

✨ 3. As Funcionalidades Mais Importantes e Como Usá-las

O coração do SDK é a criação e gerenciamento de Operações de Assinatura. Uma operação engloba os documentos, os signatários e todas as regras do processo.

Fluxo Principal: Criando uma Operação de Assinatura

O processo de ponta a ponta para enviar um documento para assinatura envolve os seguintes passos:

Passo 1: Fazer o Upload do Documento

Primeiro, você precisa enviar o documento (em formato PDF) para a plataforma ForSign.

// Exemplo de upload a partir de uma URL
var arquivoRequest = await UploadFileRequest.AddFileFromUrlAsync(
    "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
    "contrato-exemplo.pdf"
);

// Faz o upload e obtém os detalhes do arquivo
var uploadResponse = await forsignClient.UploadFileAsync(arquivoRequest);

// O objeto 'FileInformation' é essencial para os próximos passos
var fileInfo = new FileInformation(uploadResponse.Data.Id, uploadResponse.Data.FileName);

Console.WriteLine($"Arquivo enviado com sucesso! ID do arquivo: {fileInfo.FileId}");

🔴 Importante: A plataforma aceita apenas arquivos no formato PDF. O tamanho máximo é de 10 MB.

Passo 2: Definir os Signatários (Signer) com Duplo Fator

Um Signer é a representação de uma pessoa que irá interagir com o documento. Sempre adicione um método de dupla autenticação para garantir a segurança.

using ForSign.Sdk.Enums;

var signatario = new Signer
{
    Name = "João da Silva",
    Email = "joao.silva@exemplo.com", // Usado para notificações e como identificador
    Phone = "11987654321", // Opcional
    
    // Como o signatário será notificado?
    NotificationType = new EmailNotification("joao.silva@exemplo.com"),
    
    // ✨ IMPORTANTE: Configurando a Dupla Autenticação por E-mail
    // Um código de segurança será enviado para este e-mail antes de assinar.
    DoubleAuthenticationMethod = new EmailDoubleAuthentication("joao.silva@exemplo.com"),
    
    // Que tipo de assinatura ele poderá usar?
    // SignatureType.UserChoice permite que o usuário escolha entre clique, desenho ou texto.
    SignatureType = new DefaultSignatureType(SignatureType.UserChoice)
};

🔒 Nota sobre 2FA: A propriedade DoubleAuthenticationMethod instrui a ForSign a exigir um passo extra de verificação. Quando o signatário acessar a URL, ele precisará inserir um código único enviado para o e-mail especificado em EmailDoubleAuthentication antes de prosseguir.

Passo 3: Configurar as Ações do Signatário

Agora, você precisa dizer ao SDK o que o signatário deve fazer e onde.

A. Adicionar Posições de Assinatura e Rubrica

// Adicionar um campo de assinatura na página 1, a 70% da largura e 80% da altura.
signatario.AddSignatureInPosition(fileInfo, 1, "70%", "80%");

// Adicionar uma rubrica na página 1, a 10% da largura e 90% da altura.
signatario.AddRubricInPosition(fileInfo, 1, "10%", "90%");

B. (Opcional) Adicionar Campos de Formulário

var campoTexto = TextFormField.WithName("Nome Completo")
    .IsRequired()
    .OnPosition(new FormFieldPosition(fileInfo, 1, "30%", "50%"));
signatario.AddFormField(campoTexto);

C. (Opcional) Solicitar Anexos

var anexoRg = new Attachment("Documento de Identidade", "Envie uma foto do seu RG", true);
anexoRg.PermitFileType(AttachmentFileType.PNG);
anexoRg.PermitFileType(AttachmentFileType.JPG);
signatario.RequestAttachment(anexoRg);
Passo 4: Construir e Criar a Operação

Use o OperationRequestBuilder para montar a operação.

var operationRequest = OperationRequestBuilder.InitializeWithName("Contrato de Prestação de Serviços")
    .SetExpirationDate(DateTime.Now.AddDays(15))
    .WithExternalId("ID-INTERNO-456")
    .WithRedirectUrl("https://seusite.com/obrigado/{operationId}") // Redireciona após assinar
    .AddSigner(signatario)
    .Build();

// Envia a requisição para a API da ForSign
var operationResponse = await forsignClient.CreateOperationAsync(operationRequest);
Passo 5: Obter as URLs de Assinatura

A resposta da criação da operação contém as URLs exclusivas para cada signatário.

Console.WriteLine($"Operação criada com sucesso! ID da Operação: {operationResponse.Id}");

foreach (var member in operationResponse.Members)
{
    Console.WriteLine($"--- Signatário: {member.Name} ---");
    Console.WriteLine($"ID do Membro: {member.Id}");
    Console.WriteLine($"URL de Assinatura: {member.SignUrl}");
    Console.WriteLine("------------------------------------");
}

O que fazer com a URL? Você deve enviar esta URL para o respectivo signatário (por e-mail, SMS, ou integrando em um botão no seu sistema) para que ele possa acessar a tela de assinatura.

4. Gerenciando uma Operação Existente

Depois que uma operação é criada, você pode realizar diversas ações de gerenciamento usando o ID da operação.

4.1. Finalizar uma Operação Manualmente (CompleteOperationAsync)

Se uma operação foi configurada para finalização manual, você pode forçar sua conclusão para gerar os artefatos finais.

long operationId = operationResponse.Id;
await forsignClient.CompleteOperationAsync(operationId);
Console.WriteLine("Operação finalizada com sucesso!");
4.2. Cancelar uma Operação (CancelOperationAsync)

Você pode cancelar uma operação em andamento.

long operationId = operationResponse.Id;
await forsignClient.CancelOperationAsync(operationId, "Cancelamento solicitado pelo cliente.");
Console.WriteLine("Operação cancelada.");
4.3. Baixar os Documentos da Operação (DownloadOperationZipAsync)

Após a finalização, baixe um arquivo ZIP com o documento assinado e a trilha de auditoria.

long operationId = operationResponse.Id;
var zipResponse = await forsignClient.DownloadOperationZipAsync(operationId);

byte[] zipBytes = Convert.FromBase64String(zipResponse.Base64File);
File.WriteAllBytes($"operacao-{operationId}.zip", zipBytes);
Console.WriteLine($"Arquivo ZIP da operação salvo.");

5. Gerenciamento de Anexos

Se você solicitou anexos, pode usar o SDK para listar, aprovar, rejeitar e baixar esses arquivos.

5.1. Listar Anexos de um Membro (GetMemberAttachmentsAsync)
long memberId = operationResponse.Members.First().Id;
var anexos = await forsignClient.GetMemberAttachmentsAsync(memberId);
5.2. Aprovar Anexos (ApproveAttachmentsAsync)
long memberId = 12345;
var idsParaAprovar = new List<long> { 67890, 98765 };
await forsignClient.ApproveAttachmentsAsync(memberId, idsParaAprovar);
5.3. Rejeitar Anexos (RejectAttachmentsAsync)
long memberId = 12345;
var anexosParaRejeitar = new List<RejectedAttachment>
{
    new RejectedAttachment { Id = 67890, Reason = "Documento ilegível." }
};
await forsignClient.RejectAttachmentsAsync(memberId, anexosParaRejeitar);
5.4. Baixar um Anexo (DownloadAttachmentAsync)
long attachmentId = 67890;
var downloadResponse = await forsignClient.DownloadAttachmentAsync(attachmentId);
File.WriteAllBytes(downloadResponse.FileName, downloadResponse.Content);

6. Monitoramento com Webhooks

A forma mais eficiente de acompanhar o status das suas operações em tempo real é através de Webhooks.

Como funciona?

  1. Você configura uma URL (um endpoint na sua aplicação) no painel de desenvolvedor da ForSign.
  2. A ForSign enviará uma notificação (POST) para essa URL sempre que um evento importante ocorrer (ex: signatário assinou, operação finalizada).
  3. Sua aplicação recebe essa notificação e pode tomar ações automatizadas.

Esta abordagem é muito superior a ficar consultando o status de uma operação repetidamente (polling), pois é mais eficiente e fornece atualizações instantâneas.

📚 7. Exemplo de Código Completo

Este é um exemplo completo que une todos os passos do fluxo principal, incluindo o duplo fator de autenticação por e-mail.

using System;
using System.Collections.Generic;
using System.IO;
using System.Threading.Tasks;
using ForSign.Sdk;
using ForSign.Sdk.Enums;
using ForSign.Sdk.Forms;
using ForSign.Sdk.Requests;

public class Program
{
    private const string API_KEY = "SUA_API_KEY_AQUI";

    public static async Task Main(string[] args)
    {
        // 1. Configuração do Cliente
        var forsignClient = new ForSignClient();
        forsignClient.SetCredential(new ApiKeyCredential(API_KEY));
        await forsignClient.AuthenticateAsync();
        Console.WriteLine("Cliente autenticado.");

        // 2. Upload do Documento
        var fileRequest = await UploadFileRequest.AddFileFromUrlAsync(
            "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf", 
            "contrato-servicos.pdf"
        );
        var uploadResponse = await forsignClient.UploadFileAsync(fileRequest);
        var fileInfo = new FileInformation(uploadResponse.Data.Id, uploadResponse.Data.FileName);
        Console.WriteLine($"Documento '{fileInfo.FileName}' enviado com ID: {fileInfo.FileId}");

        // 3. Definição do Signatário com Duplo Fator
        var signer = new Signer
        {
            Name = "Maria Souza",
            Email = "maria.souza@exemplo.com",
            NotificationType = new EmailNotification("maria.souza@exemplo.com"),
            
            // ✨ HABILITANDO O DUPLO FATOR DE AUTENTICAÇÃO POR E-MAIL
            DoubleAuthenticationMethod = new EmailDoubleAuthentication("maria.souza@exemplo.com"),
            
            SignatureType = new DefaultSignatureType(SignatureType.UserChoice)
        };

        // Ações do signatário
        signer.AddSignatureInPosition(fileInfo, 1, "50%", "50%");
        var textField = TextFormField.WithName("CPF")
            .IsRequired()
            .OnPosition(new FormFieldPosition(fileInfo, 1, "50%", "60%"));
        signer.AddFormField(textField);
        Console.WriteLine("Signatário configurado com Duplo Fator.");

        // 4. Construção e Criação da Operação
        var operationRequest = OperationRequestBuilder.InitializeWithName("Contrato de Locação - Maria Souza")
            .WithExternalId($"LOC-{Guid.NewGuid()}")
            .SetExpirationDate(DateTime.Now.AddDays(7))
            .AddSigner(signer)
            .Build();
        
        var operationResponse = await forsignClient.CreateOperationAsync(operationRequest);
        Console.WriteLine("Operação criada com sucesso!");
        
        // 5. Exibição das URLs de Assinatura
        Console.WriteLine($"\nID da Operação: {operationResponse.Id}");
        foreach (var member in operationResponse.Members)
        {
            Console.WriteLine($"\nSignatário: {member.Name}");
            Console.WriteLine($"ID do Membro: {member.Id}");
            Console.WriteLine($"URL para Assinatura: {member.SignUrl}");
        }
    }
}
Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 was computed.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 is compatible.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net45 is compatible.  net451 is compatible.  net452 is compatible.  net46 is compatible.  net461 is compatible.  net462 is compatible.  net463 was computed.  net47 is compatible.  net471 was computed.  net472 is compatible.  net48 is compatible.  net481 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
2.0.2 191 9/19/2025
2.0.1 201 9/19/2025
2.0.0 201 9/19/2025
1.0.6 251 2/2/2024
1.0.5 147 1/26/2024
1.0.4 121 1/26/2024
1.0.3 138 1/19/2024
1.0.2 128 1/19/2024
1.0.1 128 1/18/2024
0.1.4 128 1/26/2024

Version 2.0.1 includes significant improvements to error handling, particularly for API responses. We've added specific handling for HTTP 402 (Payment Required) status codes, which now clearly indicates when operations fail due to insufficient credits. This update enhances the developer experience by providing more descriptive error messages and better exception handling, especially in the create operation endpoint.