API do DocuSafe

API REST para criar integrações: consulte solicitações de assinatura, receba eventos por webhook e conecte o DocuSafe ao seu sistema. Base: https://<sua-região>-<projeto>.cloudfunctions.net/api2 (ou o domínio do seu Hosting, via /api).

Autenticação

Gere uma chave de API em Configurações → Integrações → Chaves de API. O segredo (ds_live_…) aparece uma única vez — guarde-o com segurança. Envie a chave em todas as chamadas /api/v1/*:

curl https://SEU_HOST/api/v1/signature-requests \
  -H "Authorization: Bearer ds_live_xxxxxxxxxxxxxxxxxxxx"

Alternativa: header X-API-Key: ds_live_…. Cada chave tem escopos (signatures:read, signatures:write, templates:read, webhooks:read) e um limite de requisições por hora.

O segredo nunca é armazenado em claro — o servidor guarda apenas o hash SHA-256. Se perder a chave, revogue-a e gere outra. Revogar é imediato.

Endpoints

GET`/api/v1/signature-requests`

Lista as solicitações de assinatura da sua conta. Requer escopo signatures:read.

{
  "data": [
    {
      "id": "abc123",
      "documentName": "Contrato.pdf",
      "status": "pending",
      "verificationCode": "DS-1234-5678-9012",
      "signerCount": 2,
      "signedCount": 1,
      "createdAt": "2026-07-19T12:00:00.000Z",
      "completedAt": null,
      "deadline": "2026-07-26T12:00:00.000Z"
    }
  ]
}

GET`/api/v1/signature-requests/{id}`

Detalha uma solicitação, incluindo os signatários (sem tokens/segredos). Requer signatures:read.

{
  "data": {
    "id": "abc123",
    "documentName": "Contrato.pdf",
    "status": "completed",
    "signers": [
      { "id": "s1", "name": "Ana", "email": "ana@x.com", "status": "signed", "signedAt": "…" }
    ]
  }
}

Webhooks

Cadastre endpoints em Configurações → Integrações → Webhooks. O DocuSafe faz um POST assinado a cada evento:

signature_request.created — solicitação criada
signature.signed — um signatário assinou
signature_request.rejected — recusada
signature_request.completed — concluída por todos
signature_request.expired — prazo expirado

Cada entrega traz os headers:

X-DocuSafe-Signature: sha256=<hmac> — HMAC-SHA256 do corpo cru.
X-DocuSafe-Id — id estável do evento: use-o para deduplicar (a mesma entrega pode ser reenviada; o corpo inclui esse id).
X-DocuSafe-Timestamp — época (segundos) do evento; rejeite entregas muito antigas (anti-replay).
X-DocuSafe-Event — o tipo do evento.

Verifique a assinatura com o segredo do endpoint (mostrado uma vez na criação) sobre o corpo cru:

const crypto = require('crypto');
function verify(rawBody, header, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const got = String(header).replace(/^sha256=/, '');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(got));
}

Responda 2xx rapidamente. Entregas com falha são reentregues uma vez; o resultado de cada tentativa fica no seu log de entregas.

Erros & limites

401 chave ausente/inválida/revogada · 403 escopo insuficiente · 404 recurso de outra conta · 429 limite de requisições.
Erros seguem o padrão RFC 9457 (Problem Details): Content-Type: application/problem+json com { "type", "title", "status", "detail" } (o campo error é mantido por compatibilidade).
No 429 respeitamos Retry-After (segundos) e enviamos o header RateLimit.

← Voltar ao painel