SDK Node.js

Cliente oficial ForSign para Node.js e TypeScript — ESM + CJS, com tipos incluídos.

Pacote @forsigndigital/sdk no npm. Distribui ESM, CJS e tipos TypeScript em um único bundle. Construído sobre axios e form-data.

npm

@forsigndigital/sdk · v2.0.0

Compatibilidade

Node.js 18+
TypeScript 4.5+ (opcional — tipos incluídos no pacote)
Importável como ESM (import) ou CommonJS (require)

Instalação

npm install @forsigndigital/sdk

pnpm add @forsigndigital/sdk

yarn add @forsigndigital/sdk

Configurando o cliente

O construtor aceita um baseURL opcional (padrão https://api.forsign.digital). A autenticação é feita com ApiKeyCredential.

import { ForSignClient, ApiKeyCredential } from '@forsigndigital/sdk';

// Padrão
const client = new ForSignClient();

// Override do baseURL (raro — staging)
// const client = new ForSignClient('https://api-staging.forsign.digital');

client.setCredential(new ApiKeyCredential(process.env.FORSIGN_API_KEY!));

Apenas server-side. Não exponha a API Key em código que roda no navegador. Em frameworks como Next.js, use o SDK em route handlers, server actions ou endpoints de API — nunca em componentes client-side.

Métodos disponíveis

uploadFile envia o PDF (Buffer, Stream ou URL via FileRequest)

createOperation cria operação com assinantes, anexos e formulários

completeOperation finaliza manualmente uma operação

cancelOperation cancela com motivo obrigatório

getMemberAttachments lista anexos enviados por um membro

approveAttachments / rejectAttachments aprova ou rejeita com motivo

downloadOperationZip PDF assinado + trilha de auditoria

downloadAttachment baixa um anexo individual

Também: setOperationManualCompletion, setOperationAutomaticCompletion.

1. Upload + criação da operação

import {
  ForSignClient,
  ApiKeyCredential,
  FileRequest,
  Signer,
  EmailNotification,
  EmailDoubleAuthentication,
  DefaultSignatureType,
  SignatureType,
  OperationBuilder,
  Language,
} from '@forsigndigital/sdk';

const client = new ForSignClient();
client.setCredential(new ApiKeyCredential(process.env.FORSIGN_API_KEY!));

// 1. Upload — três fontes suportadas
const fileRequest = await FileRequest.fromUrl(
  'https://exemplo.com/contrato.pdf',
  'contrato.pdf',
);
// ou: FileRequest.fromBuffer(await fs.readFile('./contrato.pdf'), 'contrato.pdf')
// ou: FileRequest.fromStream(createReadStream('./contrato.pdf'), 'contrato.pdf')

const upload = await client.uploadFile(fileRequest);
const fileInfo = { id: upload.data.id, description: upload.data.fileName };

// 2. Assinante com 2FA por email
const signer = new Signer({
  name: 'João Silva',
  email: '[email protected]',
  notificationType: new EmailNotification('[email protected]'),
  doubleAuthenticationMethod: new EmailDoubleAuthentication('[email protected]'),
  signatureType: new DefaultSignatureType(SignatureType.UserChoice),
});
signer.addSignatureInPosition(fileInfo, 1, '70%', '80%');

// 3. Builder fluente
const operationRequest = OperationBuilder
  .initializeWithName('Contrato de prestação de serviços')
  .setLanguage(Language.Portuguese)
  .setExpirationDate(new Date(Date.now() + 15 * 24 * 60 * 60 * 1000))
  .withExternalId('CRM-12345')
  .withRedirectUrl('https://app.exemplo.com/sucesso/{operationId}')
  .addSigner(signer)
  .build();

const response = await client.createOperation(operationRequest);

for (const member of response.members) {
  console.log(`${member.name}: ${member.signUrl}`);
}

2. Aprovar (ou rejeitar) anexos

Depois que o assinante envia documentos solicitados, sua aplicação inspeciona e decide. O memberId vem de response.members[i].id ou do webhook AttachmentFilled.

const attachments = await client.getMemberAttachments(memberId);

const uploaded = attachments.filter((a) => a.isUploaded);

// Aprovar todos
await client.approveAttachments(
  operationMemberId,
  uploaded.map((a) => a.id),
);

// Ou rejeitar com motivo (motivo obrigatório por anexo)
await client.rejectAttachments(operationMemberId, [
  { id: 4321, reason: 'Documento ilegível, reenvie em alta resolução' },
]);

3. Download após a operação concluída

import { writeFile } from 'node:fs/promises';

const zip = await client.downloadOperationZip(operationId);
await writeFile(`${zip.name}.zip`, zip.content);

// Anexo individual
const file = await client.downloadAttachment(attachmentId);
await writeFile(file.fileName, file.content);

Tratamento de erros

O SDK lança ForSignApiError em respostas HTTP de erro. A exceção carrega statusCode e messages: ValidationMessage[].

import { ForSignApiError } from '@forsigndigital/sdk';

try {
  await client.createOperation(operationRequest);
} catch (err) {
  if (err instanceof ForSignApiError) {
    if (err.statusCode === 402) {
      // Créditos insuficientes
    } else if (err.statusCode === 422) {
      for (const m of err.messages) {
        console.error(`${m.key}: ${m.value}`);
      }
    } else {
      console.error(`${err.statusCode}: ${err.message}`);
    }
  } else {
    throw err;
  }
}

Códigos comuns: 401 (API key inválida), 402 (sem créditos), 403 (sem permissão), 404 (operação/membro não encontrado), 422 (validação).

Versões

2.0.0 — release atual no npm. Cobre o ciclo completo (upload → criação → anexos → finalização → download) e expõe os mesmos primitivos do SDK .NET: OperationBuilder, Signer, TagPosition, TextFormField, etc.