Chaindoc logoChaindoc

Referência da API REST Chaindoc

Guia completo de endpoints da API REST Chaindoc. Aqui está o truque: você vai dominar autenticação, documentos, assinaturas, upload de mídia e verificação blockchain em poucos minutos.

Visão geral

A API oferece acesso programático a tudo no Chaindoc: documentos, assinaturas, verificação blockchain e gestão de equipes. Na prática, foi projetada para uso server-to-server e suporta tanto chaves públicas quanto secretas.

  • Documentos — crie, atualize e verifique documentos na blockchain
  • Assinaturas — envie solicitações de assinatura e acompanhe a conclusão
  • Mídia — faça upload de PDFs, imagens e vídeos (máximo 10 por requisição)
  • Sessões embedadas — crie sessões de assinatura para seu frontend (usa o Embed SDK)
  • KYC — compartilhe e verifique dados de identidade via integração Sumsub

Autenticação

Cada requisição precisa de uma API key no header Authorization. Existem dois tipos:

Tipos de chaves

  • Chave pública (`pk_`) — somente leitura, segura para código frontend
  • Chave secreta (`sk_`) — leitura/escrita completa, apenas backend. Nunca exponha em código client-side.

Obtendo suas chaves

1Assine o plano BusinessApenas usuários do plano Business podem criar API keys

2Navegue até API AccessVá em Configurações → API Access no seu dashboard

3Crie a API keyClique no botão Create API Key

4Armazene com segurançaGuarde a chave secreta em local seguro (exibida apenas uma vez)

Usando API keys

Inclua sua API key no header Authorization com autenticação Bearer:

terminal
curl -X GET https://api.chaindoc.io/api/v1/me \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxx"

Rate limiting

Os endpoints da API possuem limites de taxa para prevenir abuso. Os limites variam conforme o tipo de endpoint.

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

Quando o limite é excedido, você recebe uma resposta 429 Too Many Requests. Headers de rate limit são incluídos nas respostas:

terminal
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 2
X-RateLimit-Reset: 1640000000

Tratamento de erros

Códigos de status HTTP

  • 200 - Sucesso
  • 201 - Recurso criado com sucesso
  • 400 - Requisição inválida (erro de validação)
  • 401 - Não autorizado (API key inválida ou ausente)
  • 403 - Proibido (permissões insuficientes)
  • 404 - Recurso não encontrado
  • 429 - Muitas requisições (limite excedido)
  • 500 - Erro interno do servidor

Formato de resposta de erro

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

API Geral

Obter informações da API key

Obtenha informações sobre a API key atual.

GET /me

Authorization: Bearer sk_live_xxxxx

Health check

Verifique a conectividade da API e a validade da chave.

GET /health

Authorization: Bearer sk_live_xxxxx

API de Documentos

Criar documento

Crie um novo documento com verificação blockchain. Quando o status é 'published', o documento é automaticamente verificado na blockchain.

POST /documents

Headers:
Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Atualizar documento

Atualize um documento criando uma nova versão. Versões anteriores são preservadas para auditoria.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Atualizar permissões do documento

Atualize as configurações de controle de acesso do documento.

PUT /documents/:documentId/rights

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Verificar documento

Verifique a autenticidade do documento usando blockchain. Retorna o status de verificação com hash da transação e chain ID.

POST /documents/verify

{
  "versionHash": "0x123abc...",
  "certificateHash": "0x456def..."
}

Obter status de verificação

Obtenha o status de verificação blockchain para uma versão do documento.

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

API de Assinaturas

Criar solicitação de assinatura

Crie uma solicitação de assinatura para um ou mais destinatários. Habilite o fluxo embedado para integração com frontend.

curl -X POST https://api.chaindoc.io/api/v1/signatures/requests \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "versionId": "f0b7721f-0399-4035-9b69-7b95d3a367f0",
    "recipients": [{"email": "signer@example.com"}],
    "deadline": "2024-12-31T23:59:59Z",
    "embeddedFlow": true
  }'

Obter status da solicitação

Verifique o status de uma solicitação de assinatura e veja quais signatários completaram.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Assinar documento

Assine um documento (se o dono da API key for signatário).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Obter assinaturas do usuário

Obtenha todas as assinaturas do usuário autenticado.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Obter solicitações de assinatura

Obtenha todas as solicitações de assinatura do usuário autenticado com suporte a paginação.

GET /signatures/requests?pageNumber=1&pageSize=10

Authorization: Bearer sk_live_xxxxx

API de Upload de Mídia

Faça upload de arquivos para uso na criação de documentos. Suporta PDF, imagens e vídeos. Máximo de 10 arquivos por requisição.

curl -X POST https://api.chaindoc.io/api/v1/media/upload \
  -H "Authorization: Bearer sk_live_xxxxx" \
  -F "media=@contract.pdf"

API KYC

Compartilhar dados KYC

Compartilhe dados KYC (Know Your Customer) com destinatários para verificação de identidade.

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

API de Sessões Embedadas

Crie sessões embedadas para assinatura de documentos na sua aplicação frontend. As sessões são válidas por 10 minutos.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

O que fazer agora

  • Integração API — padrões comuns, boas práticas e exemplos completos de workflow
  • SDKs — Server SDK e Embed SDK com guias específicos por framework
  • Webhooks — configure notificações de eventos em tempo real
  • Instalação — setup npm para todos os frameworks suportados
  • Segurança — gestão de API keys e conformidade