Guia de início rápido

Comece a usar o Chaindoc em menos de 10 minutos. Este guia aborda tanto a interface web quanto a API, para que você possa escolher o caminho que melhor se adequa.

Assinatura pela interface web

Você não precisa de código para enviar sua primeira solicitação de assinatura. O aplicativo web gerencia tudo: upload, destinatários, fluxo de assinatura e verificação blockchain.

Passo a passo: sua primeira assinatura

Quer entender os diferentes tipos de assinatura (simples, avançada, qualificada)? Isso importa para conformidade. A maioria dos contratos comerciais funciona bem com assinaturas eletrônicas simples, mas indústrias reguladas frequentemente precisam de avançadas ou qualificadas.

Integração via API

Se você está construindo assinaturas em seu próprio aplicativo, usará a REST API e os SDKs TypeScript. O fluxo é o mesmo da interface web, apenas automatizado.

1. Obtenha suas chaves de API

O acesso à API requer um plano Business. Vá em Configurações > Acesso à API no seu painel e crie duas chaves:

• Chave pública (`pk_`) para uso no frontend com o Embed SDK
• Chave secreta (`sk_`) para uso no backend com o Server SDK. Mantenha esta fora do código do lado do cliente.

2. Instale o SDK

Escolha o SDK que corresponde ao seu caso de uso. A maioria dos aplicativos precisa de ambos: o Server SDK para criar documentos e o Embed SDK para a interface de assinatura.

# Node.js 18+ required
npm install @chaindoc_io/server-sdk

Para configuração detalhada de frameworks (React, Vue, Angular, Next.js), consulte o guia de instalação.

3. Faça upload e crie um documento

import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

// Initialize SDK
const chaindoc = new Chaindoc({
  secretKey: process.env.CHAINDOC_SECRET_KEY!,
});

// 1. Upload document
const buffer = await readFile('./contract.pdf');
const file = new Blob([buffer], { type: 'application/pdf' });
const { media } = await chaindoc.media.upload([file]);

// 2. Create document record
const doc = await chaindoc.documents.create({
  name: 'Service Agreement',
  description: 'Q4 2024 Contract',
  media: media[0],
  status: 'published', // Triggers blockchain verification
  hashtags: ['#contract', '#2024'],
  meta: [{ key: 'client', value: 'Acme Corp' }],
});

console.log('Document created:', doc.documentId);

Definir `status: 'published'` aciona a verificação blockchain automaticamente. Se quiser adiar, use `'draft'` e publique depois.

4. Crie uma solicitação de assinatura

// Create signature request for multiple signers
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: doc.document.versions[0].uuid,
  recipients: [
    { email: 'signer1@example.com' },
    { email: 'signer2@example.com' },
  ],
  deadline: new Date('2024-12-31'),
  message: 'Please review and sign this agreement',
  embeddedFlow: true, // Enable for frontend integration
});

console.log('Signature request created:', sigRequest.signatureRequest.uuid);

Defina `embeddedFlow: true` se você for mostrar a interface de assinatura dentro do seu aplicativo. Sem isso, os signatários recebem um link para a página de assinatura hospedada do Chaindoc.

5. Mostre a interface de assinatura (frontend)

Isso é opcional. Se você definiu `embeddedFlow: true`, pode abrir a interface de assinatura diretamente no seu aplicativo. Primeiro, crie uma sessão no backend, depois passe o ID da sessão para o frontend.

// Create embedded session for signer
const session = await chaindoc.embedded.createSession({
  email: 'signer1@example.com',
  metadata: {
    documentId: doc.documentId,
    signatureRequestId: sigRequest.signatureRequest.uuid,
  },
});

// Return sessionId to frontend
res.json({ sessionId: session.sessionId });

6. Verifique o status e escute eventos

Você pode consultar o status, mas webhooks são uma opção melhor para produção. Eles notificarão seu servidor no momento em que algo acontecer.

// Poll approach (fine for testing)
const status = await chaindoc.signatures.getRequestStatus(
  sigRequest.signatureRequest.uuid
);

if (status.signatureRequest.status === 'completed') {
  console.log('All signatures collected!');
}

7. Configure webhooks (recomendado)

Webhooks enviam eventos para seu servidor em tempo real, então você não precisa ficar verificando. Aqui está um manipulador Express básico:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', (req, res) => {
  const event = req.headers['x-webhook-event'];
  const payload = req.body;
  
  switch (event) {
    case 'document.verified':
      console.log('Document verified on blockchain:', payload.txHash);
      break;
    case 'signature.request.completed':
      console.log('All signatures collected!');
      // Send notifications, update status, etc.
      break;
  }
  
  res.status(200).send('OK');
});

Em produção, você deve verificar as assinaturas de webhook com HMAC para garantir que o payload realmente veio do Chaindoc. O guia de webhooks cobre isso em detalhes.

Exemplo completo de fluxo de trabalho

Isso junta tudo: upload, criação, assinatura, verificação. Copie, substitua suas chaves de API, e você terá um protótipo funcional.

import { Chaindoc } from '@chaindoc_io/server-sdk';
import { readFile } from 'fs/promises';

async function createSigningWorkflow() {
  const chaindoc = new Chaindoc({
    secretKey: process.env.CHAINDOC_SECRET_KEY!,
  });
  
  // Step 1: Upload document
  const buffer = await readFile('./contract.pdf');
  const file = new Blob([buffer], { type: 'application/pdf' });
  const { media } = await chaindoc.media.upload([file]);
  
  // Step 2: Create document
  const doc = await chaindoc.documents.create({
    name: 'Service Agreement',
    description: 'Contract for consulting services',
    media: media[0],
    status: 'published',
    hashtags: ['#contract'],
    meta: [],
  });
  
  // Step 3: Create signature request
  const sigRequest = await chaindoc.signatures.createRequest({
    versionId: doc.document.versions[0].uuid,
    recipients: [{ email: 'signer@example.com' }],
    deadline: new Date('2024-12-31'),
    embeddedFlow: true,
  });
  
  // Step 4: Create session for frontend
  const session = await chaindoc.embedded.createSession({
    email: 'signer@example.com',
    metadata: {
      documentId: doc.documentId,
      signatureRequestId: sigRequest.signatureRequest.uuid,
    },
  });
  
  return {
    documentId: doc.documentId,
    sessionId: session.sessionId,
  };
}

// Usage
const { documentId, sessionId } = await createSigningWorkflow();
console.log('Ready for signing:', { documentId, sessionId });

Para onde ir em seguida

Agora que você dominou o básico, aqui está o que aprofundar dependendo do que está construindo:

• Instalação — configuração específica para React, Vue, Angular e Next.js
• Documentação da API — referência completa de endpoints com exemplos de requisição/resposta
• SDKs — Server SDK e Embed SDK, com guias de integração por framework
• Webhooks — notificações de eventos em tempo real para aplicativos em produção
• Boas práticas de segurança — o que proteger antes de lançar

Perguntas frequentes

Quanto tempo leva a verificação blockchain?

Normalmente 1-5 minutos, dependendo da rede. Seu documento fica disponível imediatamente. A verificação roda em segundo plano e você receberá um evento de webhook quando estiver concluída.

Posso testar a API sem pagar?

O plano gratuito dá acesso à interface web. O acesso à API precisa de um plano Business, mas o ambiente sandbox permite testar tudo sem afetar dados reais ou usar a cota.

Essas assinaturas são legalmente vinculantes?

Sim. As assinaturas Chaindoc cumprem com o eIDAS na Europa, o ESIGN Act e UETA nos EUA, e regulamentações equivalentes na maioria das outras jurisdições. A verificação blockchain adiciona uma camada extra de evidência além disso, o que pode ser importante em disputas. Veja a documentação de assinaturas para detalhes sobre qual tipo de assinatura se adequa às suas necessidades de conformidade.

Quais formatos de arquivo posso fazer upload?

PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX, TXT, JPG, PNG, GIF, WEBP, SVG, MP4, AVI, MOV e WMV. O tamanho máximo do arquivo é 50MB.