Integração da API

Integre o Chaindoc nas suas aplicações com a nossa poderosa API REST e SDKs. Automatize fluxos de trabalho de documentos, recolha assinaturas e sincronize eventos em tempo real.

Visão geral

O Chaindoc oferece uma API REST abrangente que permite criar fluxos de trabalho personalizados para assinatura de documentos, automatizar processos e integrar com os seus sistemas existentes. A API foi projetada para programadores com suporte total ao TypeScript e tentativas automáticas.

Introdução

1. Obtenha acesso à API

2. Escolha o método de integração

O Chaindoc oferece três abordagens de integração:

• REST API - Solicitações HTTP diretas para máxima flexibilidade
• Server SDK - SDK Node.js seguro com tentativas automáticas (@chaindoc_io/server-sdk)
• SDK incorporado - Interface de assinatura front-end para aplicações web (@chaindoc_io/embed-sdk)

3. Exemplo rápido

curl -X POST https://api.chaindoc.io/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contract",
    "description": "Service agreement",
    "status": "published",
    "hashtags": ["#contract"],
    "meta": []
  }'

Conceitos básicos da API

Autenticação

Todas as solicitações de API exigem autenticação usando chaves de API no cabeçalho de autorização:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

• Chaves públicas (pk_) - Acesso somente leitura para aplicações front-end
• Chaves secretas (sk_) - Acesso total de leitura/gravação para servidores backend
• Chaves de teste (pk_test_, sk_test_) - Para preparação/desenvolvimento
• Chaves ao vivo (pk_live_, sk_live_) - Para produção

Limites de taxa

Os pontos finais da API têm limites de taxa para garantir uma utilização justa:

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640000000

• Pontos finais gerais: 3 pedidos por 10 segundos
• Upload de mídia: 3 solicitações a cada 10 segundos
• Operações de leitura: 10 pedidos por 60 segundos
• Criação de assinatura: 20 pedidos a cada 3 segundos

Tratamento de erros

A API retorna códigos de status HTTP padrão com mensagens de erro detalhadas:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "name must be a string"
    }
  ]
}

Padrões comuns de integração

Fluxo de carregamento e assinatura de documentos

Fluxo de trabalho apenas no backend

Para cenários em que os signatários não usam a tua interface:

// Create signature request with email notifications
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Signers use Chaindoc email links
  message: 'Please review and sign this document',
});

// Chaindoc sends emails to recipients
// Track status via webhooks or API polling

Processamento em massa de documentos

// Process multiple documents in batch
const documents = ['doc1.pdf', 'doc2.pdf', 'doc3.pdf'];

for (const file of documents) {
  const buffer = await readFile(file);
  const blob = new Blob([buffer], { type: 'application/pdf' });
  
  const { media } = await chaindoc.media.upload([blob]);
  
  await chaindoc.documents.create({
    name: file,
    description: 'Batch processed document',
    media: media[0],
    status: 'published',
    hashtags: ['#batch'],
    meta: [{ key: 'batch', value: 'import-2024' }],
  });
}

Recursos avançados

Webhooks

Receba notificações em tempo real sobre eventos relacionados a documentos:

// Configure webhook endpoint
app.post('/webhooks/chaindoc', async (req, res) => {
  const event = req.headers['x-webhook-event'];
  
  switch (event) {
    case 'document.verified':
      await handleBlockchainVerification(req.body);
      break;
    case 'signature.request.completed':
      await notifyAllParties(req.body);
      break;
  }
  
  res.status(200).send('OK');
});

Integração KYC

Integre a verificação de identidade para fluxos de trabalho de alta segurança:

// Create signature request with KYC required
const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Optional: pre-verified KYC
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true, // Enforce identity verification
});

Controlo de acesso

Gerencie as permissões do documento com controle de acesso granular:

// Update document access rights
await chaindoc.documents.updateRights(documentId, {
  accessType: 'restricted',
  accessEmails: [
    { email: 'viewer@company.com', level: 'read' },
    { email: 'editor@company.com', level: 'write' },
  ],
  accessRoles: [
    { roleId: 1, level: 'read' }, // Team role
  ],
});

Melhores práticas

• Armazene as chaves API em variáveis de ambiente, nunca em código
• Use chaves de teste para desenvolvimento e chaves ativas para produção
• Implementa o backoff exponencial para o tratamento do limite de taxa
• Verifique as assinaturas do webhook para evitar ataques de repetição
• Armazene as respostas da API em cache quando for apropriado
• Carregue os ficheiros antes de criar documentos para um melhor desempenho
• Use paginação para grandes conjuntos de dados
• Monitore os cabeçalhos de limite de taxa e ajuste a frequência das solicitações

Exemplos de integrações

Plataforma de comércio eletrónico

Gere e assine automaticamente contratos de compra para encomendas de alto valor.

Sistema de RH

Integre com o HRIS para automatizar a assinatura do contrato de trabalho durante a integração.

Integração com CRM

Crie pedidos de assinatura diretamente a partir dos registos dos clientes no Salesforce, HubSpot ou CRM personalizado.

Sistema de Gestão de Documentos

Adicione verificação de blockchain ao DMS existente para trilhas de auditoria à prova de adulteração.

Recursos

• Documentação da API - Referência completa da API REST com todos os pontos finais
• SDKs - Documentação do SDK do servidor e do SDK incorporado com exemplos de estrutura
• Webhooks - Guia de configuração de notificações de eventos em tempo real
• Início rápido - Coloque a sua primeira integração em funcionamento em 10 minutos
• Exemplos do GitHub - Integrações de amostra e trechos de código