Integração com API

A API REST do Chaindoc permite automatizar fluxos de documentos, coletar assinaturas e sincronizar eventos em tempo real. Aqui está o truque: você pode fazer tudo isso sem que os usuários saiam do seu aplicativo.

O que você consegue fazer com a API

A API oferece acesso programático a tudo o que o Chaindoc faz: enviar documentos, criar solicitações de assinatura, gerenciar equipes e escutar eventos via webhooks. Honestamente, é a mesma API que mantém o aplicativo web funcionando.

Três formas de integrar

Escolha a que funciona melhor para sua stack. Na prática, a maioria dos apps em produção usa o Server SDK no backend e o Embed SDK no frontend.

• REST API — requisições HTTP diretas, funciona com qualquer linguagem. Flexibilidade máxima.
• Server SDK — wrapper Node.js com tipos e tratamento automático de erros (`@chaindoc_io/server-sdk`)
• Embed SDK — incorpora uma interface de assinatura no seu app para que os usuários não saiam do site (`@chaindoc_io/embed-sdk`)

Se ainda não instalou os SDKs, o guia de instalação cobre a configuração npm para React, Vue, Angular e Next.js.

Exemplo rápido

Aqui está a mesma chamada "criar documento" em três sabores. A versão com SDK é a mais concisa, mas a chamada REST pura mostra exatamente o que acontece na rede.

curl -X POST https://api.chaindoc.io/api/v1/documents \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contrato",
    "description": "Acordo de serviço",
    "status": "published",
    "hashtags": ["#contrato"],
    "meta": []
  }'

Autenticação

Cada requisição precisa de uma chave de API no header de autorização:

Authorization: Bearer sk_live_xxxxxxxxxxxxx

Existem dois tipos de chaves, e confundi-las é o erro de integração mais comum:

• Chaves públicas (`pk_`) — apenas leitura, seguras para código frontend
• Chaves secretas (`sk_`) — leitura/escrita completa, apenas backend. Nunca exponha essas no lado do cliente.
• Ambas vêm em variantes de teste (`_test_`) e produção (`_live_`). As chaves de teste usam o sandbox.

Limites de requisição

A API retorna informações de limite nos headers de resposta. Se atingir o limite, você receberá uma resposta 429. Aguarde e tente novamente.

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

• Endpoints gerais: 3 requisições por 10 segundos
• Upload de mídia: 3 requisições por 10 segundos
• Operações de leitura: 10 requisições por 60 segundos
• Criação de assinaturas: 20 requisições por 3 segundos

O Server SDK lida com retries automaticamente usando backoff exponencial. Se estiver usando HTTP direto, implemente a lógica de retry você mesmo.

Tratamento de erros

Erros retornam como JSON com código de status, mensagem e (para erros de validação) uma lista de problemas específicos de campos:

{
  "statusCode": 400,
  "message": "Falha na validação",
  "error": "Bad Request",
  "details": [
    {
      "field": "name",
      "message": "o nome deve ser uma string"
    }
  ]
}

Códigos de status comuns: 400 (requisição inválida), 401 (chave inválida), 403 (plano não inclui API), 404 (não encontrado), 429 (limite atingido), 500 (erro do servidor). Para erros 5xx, tente novamente com backoff.

Padrões comuns de integração

Fluxo completo de assinatura (embedado)

O padrão mais comum: envie um documento, solicite assinaturas e mostre a interface de assinatura dentro do seu app.

O guia de início rápido tem o código completo para esse fluxo.

Assinatura por email (sem embed)

Se os signatários não usam seu app, defina `embeddedFlow: false`. O Chaindoc envia um email com link de assinatura. Você ainda recebe notificações webhook quando assinam.

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ email: 'signer@example.com' }],
  deadline: new Date('2024-12-31'),
  embeddedFlow: false, // Signatários recebem links por email
  message: 'Por favor, revise e assine este documento',
});

Processamento em lote de documentos

Para importações em lote, percorra seus arquivos e envie cada um. Fique de olho nos limites de requisição. Se estiver processando centenas de documentos, adicione um pequeno atraso entre as requisições ou use a lógica de retry do SDK.

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: 'Documento processado em lote',
    media: media[0],
    status: 'published',
    hashtags: ['#lote'],
    meta: [{ key: 'lote', value: 'importacao-2024' }],
  });
}

Integração KYC

Para fluxos de alta segurança, exija verificação de identidade antes da assinatura. O Chaindoc integra com Sumsub para KYC. Defina `isKycRequired: true` na solicitação de assinatura, e os signatários passarão pela verificação de identidade antes de poderem assinar.

const sigRequest = await chaindoc.signatures.createRequest({
  versionId: documentVersionId,
  recipients: [{ 
    email: 'signer@example.com',
    shareToken: 'sumsub_token_here' // Opcional: pré-verificado
  }],
  deadline: new Date('2024-12-31'),
  isKycRequired: true,
});

Controle de acesso via API

Você pode definir permissões de documentos programaticamente. Restrinja o acesso a emails específicos ou cargos da equipe:

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' },
  ],
});

Boas práticas

• Mantenha as chaves de API em variáveis de ambiente. Nunca as commit no controle de versão.
• Use chaves de teste (`sk_test_`) para desenvolvimento. Chaves de produção (`sk_live_`) acessam o ambiente real.
• Implemente backoff exponencial para respostas 429. O SDK faz isso automaticamente.
• Verifique assinaturas de webhooks com HMAC para prevenir ataques de repetição.
• Envie arquivos antes de criar documentos. A API precisa do ID de mídia da etapa de upload.
• Use paginação para endpoints que retornam listas. Não busque tudo de uma vez.
• Consulte o guia de segurança antes de entrar em produção.

Casos de uso de exemplo

Alguns padrões do mundo real que as equipes constroem com a API:

• E-commerce — gere automaticamente acordos de compra para pedidos de alto valor e envie para assinatura no checkout
• Onboarding de RH — crie contratos de trabalho a partir de templates e envie para novos funcionários na data de início
• Integração com CRM — dispare solicitações de assinatura a partir de registros de negócios no Salesforce ou HubSpot
• Arquivamento de documentos — adicione verificação blockchain a documentos no seu sistema de armazenamento existente

O que fazer em seguida

• Documentação da API — referência completa de endpoints com exemplos de requisição/resposta
• SDKs — Server SDK e Embed SDK com guias específicos por framework
• Webhooks — configure notificações de eventos em tempo real
• Início rápido — coloque sua primeira integração para funcionar em 10 minutos
• Instalação — configuração npm para todos os frameworks suportados