Chaindoc logoChaindoc

Referência da API REST do Chaindoc

Referência completa para integrar a API REST do Chaindoc nas tuas aplicações. Gerencia documentos, assinaturas, verificação de blockchain e fluxos de trabalho de assinatura incorporados.

Visão geral

A API REST da Chaindoc fornece acesso programático à gestão de documentos, verificação de blockchain e funcionalidade de assinatura digital. A API foi concebida para integração servidor a servidor e suporta chaves API públicas e secretas.

Principais funcionalidades

  • Gestão de documentos - Crie, atualize e gerencie documentos com verificação por blockchain
  • Assinaturas digitais - Solicite e recolha assinaturas digitais de várias partes
  • Verificação de blockchain - Verifique a autenticidade do documento em redes de blockchain
  • Sessões incorporadas - Crie sessões seguras para fluxos de trabalho de assinatura front-end
  • Carregamento de mídia - Carregue ficheiros (PDF, imagens, vídeos) para a criação de documentos
  • Integração KYC - Partilhe e verifique dados de identidade com o Sumsub

Autenticação

A API Chaindoc usa chaves API para autenticação. Existem dois tipos de chaves com diferentes níveis de acesso.

Tipos de chaves API

  • Chave pública (pk_) - Acesso somente leitura para aplicações front-end e verificação
  • Chave secreta (sk_) - Acesso total de leitura e escrita para servidores backend

Obtenção de chaves API

1Inscreva-se no Plano de NegóciosSó os utilizadores do plano Business podem criar chaves API

2Navegue até Acesso à APIVá para Configurações → Acesso à API no seu painel

3Criar chave APIClique no botão Criar chave API

4Armazene com segurançaGuarde a chave secreta em segurança (mostrada apenas uma vez)

Usando chaves API

Inclua a sua chave API no cabeçalho de autorização com autenticação Bearer:

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

Limitação de taxa

Os pontos finais da API têm limites de taxa para evitar abusos. Os limites de taxa variam de acordo com o tipo de ponto final.

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

Quando o limite de taxa for excedido, receberá uma resposta 429 Too Many Requests (Demasiadas solicitações). Os cabeçalhos de limite de taxa estão incluídos nas respostas:

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

Tratamento de erros

Códigos de estado HTTP

  • 200 - Sucesso
  • 201 - Recurso criado com sucesso
  • 400 - Pedido inválido (erro de validação)
  • 401 - Não autorizado (chave API inválida ou ausente)
  • 403 - Proibido (permissões insuficientes)
  • 404 - Recurso não encontrado
  • 429 - Demasiados pedidos (limite de taxa 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 sobre a chave API

Obtenha informações sobre a chave API atual.

GET /me

Authorization: Bearer sk_live_xxxxx

Verificação de integridade

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 de blockchain. Quando o estado for definido como «publicado», 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. As versões anteriores são mantidas para fins de auditoria.

PUT /documents/:documentId

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Atualizar direitos de acesso ao documento

Atualize as configurações de controlo de acesso ao 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 da verificação com o hash da transação e o ID da cadeia.

POST /documents/verify

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

Obter o estado da verificação

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

GET /documents/versions/:versionId/verification

Authorization: Bearer sk_live_xxxxx

API de assinaturas

Criar pedido de assinatura

Crie um pedido de assinatura para um ou mais destinatários. Habilite o fluxo incorporado para integração com o front-end.

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 o estado do pedido de assinatura

Verifique o estado de um pedido de assinatura e veja quais signatários já concluíram a assinatura.

GET /signatures/requests/:requestId/status

Authorization: Bearer sk_live_xxxxx

Assinar documento

Assine um documento (se o proprietário da chave API for um signatário).

POST /signatures/sign

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

Obter assinaturas de utilizadores

Obtenha todas as assinaturas do utilizador autenticado.

GET /signatures

Authorization: Bearer sk_live_xxxxx

Obter pedidos de assinatura

Obtenha todas as solicitações de assinatura para o utilizador autenticado com suporte para paginação.

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

Authorization: Bearer sk_live_xxxxx

API de upload de mídia

Carregue ficheiros para usar na criação de documentos. Suporta PDF, imagens e vídeos. Máximo de 10 ficheiros por pedido.

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

API KYC

Partilhe dados KYC

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

POST /kyc/share

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json

API de sessões incorporadas

Crie sessões incorporadas para assinatura de documentos na sua aplicação front-end. As sessões são válidas por 10 minutos.

POST /embedded/sessions

Authorization: Bearer sk_live_xxxxx
Content-Type: application/json