API de Integração SD Sign | Documentação para Desenvolvedores

Visão geral

A API SD Sign segue o padrão REST, com requisições e respostas em JSON e autenticação via chave de API. Ela foi desenhada para que empresas conectem seus sistemas (CRM, ERP, ERP jurídico, intranet, portal do cliente) ao ciclo completo de assinatura de documentos.

Envio de documentos em PDF (ou conversão automática) para assinatura eletrônica ou digital.
Definição de signatários e da modalidade de validação exigida em cada processo.
Acompanhamento de status por consulta (polling) ou por notificações via webhook.
Download do documento assinado com trilha de evidências e certificado x509.

⚠️ Estrutura de referência: os endpoints abaixo seguem a estrutura padrão da API SD Sign e devem ser conferidos/ajustados conforme a especificação oficial (Swagger) do ambiente contratado.

Fluxo de integração

Autentique

Obtenha sua API Key no painel da SD Sign e inclua no cabeçalho de todas as requisições.

Crie o envelope

Envie o documento (Base64 ou multipart) junto com os dados dos signatários e as validações desejadas.

A SD Sign processa

Notificamos os signatários (e-mail/WhatsApp), aplicamos as validações (ex.: Datavalid, Liveness 3D) e coletamos as assinaturas.

Acompanhe o status

Consulte o endpoint de status ou receba o evento de conclusão via webhook.

Receba o documento final

Faça o download do PDF assinado com o protocolo de assinaturas e evidências completas.

Autenticação

Todas as chamadas exigem o cabeçalho de autenticação com sua chave de API:

Authorization: Bearer sua_api_key
Content-Type: application/json

A chave de API é gerada no painel administrativo da SD Sign (Configurações → Integrações). Mantenha-a em segredo e nunca a exponha em código front-end.

Documentos / Envelopes

POST/api/v1/envelopes

Cria um envelope (documento + signatários) e dispara o processo de assinatura.

Corpo da requisição

{
  "documento": {
    "nome": "contrato.pdf",
    "conteudo_base64": "JVBERi0xLjQK..."
  },
  "signatarios": [
    {
      "nome": "Cliente Exemplo",
      "email": "cliente@empresa.com.br",
      "celular": "+5541999999999",
      "tipo_assinatura": "eletronica"  // eletronica | certificado_digital | datavalid | liveness3d
    }
  ],
  "notificar_por_whatsapp": true,
  "callback_url": "https://seusistema.com.br/webhooks/sdsign"
}

Resposta de sucesso — `201 Created`

{
  "envelope_id": "env_9f2c1a7b",
  "status": "aguardando_assinatura",
  "criado_em": "2026-09-10T14:32:11Z"
}

GET/api/v1/envelopes/{envelope_id}

Consulta o status de um envelope e o andamento de cada signatário.

{
  "envelope_id": "env_9f2c1a7b",
  "status": "concluido",  // aguardando_assinatura | em_andamento | concluido | recusado | expirado
  "signatarios": [
    {
      "nome": "Cliente Exemplo",
      "status": "assinado",
      "assinado_em": "2026-09-10T15:04:38Z"
    }
  ]
}

GET/api/v1/envelopes/{envelope_id}/documento

Retorna o PDF assinado (após conclusão) com o protocolo de assinaturas anexado.

Resposta: application/pdf (binário).

DELETE/api/v1/envelopes/{envelope_id}

Cancela um envelope ainda não concluído. Envelopes concluídos não podem ser cancelados.

Signatários

Cada signatário é definido na criação do envelope. Campos principais:

Campo	Tipo	Obrigatório	Descrição
`nome`	string	Sim	Nome completo do signatário.
`email`	string	Sim	E-mail para notificação e vínculo da assinatura.
`celular`	string	Recomendado	Necessário para notificação por WhatsApp e validações por celular.
`cpf`	string	Condicional	Obrigatório quando a validação exige Datavalid ou Liveness 3D.
`tipo_assinatura`	string	Sim	`eletronica`, `certificado_digital`, `datavalid` ou `liveness3d`.
`ordem`	integer	Não	Define a sequência de assinatura quando houver fluxo ordenado.

Validações avançadas

Dependendo da modalidade do plano, o envelope pode exigir camadas extras de validação por signatário:

Validação	Parâmetro	Descrição
Certificado Digital	`tipo_assinatura = certificado_digital`	Assinatura com certificado ICP-Brasil (x509).
Datavalid	`tipo_assinatura = datavalid`	Validação de dados em base oficial do Serpro.
Liveness 3D	`tipo_assinatura = liveness3d`	Prova de vida com biometria facial 3D (FaceTec).
WhatsApp	`notificar_por_whatsapp = true`	Notificação do link de assinatura via WhatsApp.

As evidências de cada validação são anexadas ao protocolo do documento e disponibilizadas no download final.

Webhooks

Informe um callback_url na criação do envelope para receber eventos em tempo real. A SD Sign envia um POST com o evento e o estado atual do envelope:

POST https://seusistema.com.br/webhooks/sdsign
Content-Type: application/json

{
  "evento": "envelope.concluido",  // envelope.criado | signatario.assinado | envelope.concluido | envelope.recusado
  "envelope_id": "env_9f2c1a7b",
  "status": "concluido",
  "timestamp": "2026-09-10T15:04:38Z"
}

Recomenda-se validar a origem do webhook (assinatura HMAC no cabeçalho) e responder com HTTP 200 em até 5 segundos. Em caso de falha, o evento é reenviado com backoff.

Códigos de erro

Código	Significado	Causa comum
`400`	Bad Request	Payload inválido, campo obrigatório ausente ou Base64 corrompido.
`401`	Unauthorized	API Key ausente, inválida ou revogada.
`403`	Forbidden	Recurso não disponível no plano contratado.
`404`	Not Found	Envelope inexistente ou já removido.
`409`	Conflict	Operação incompatível com o status atual (ex.: cancelar envelope concluído).
`429`	Too Many Requests	Limite de requisições excedido. Aguarde e tente novamente.
`500`	Internal Error	Erro interno. Se persistir, contate o suporte.

Boas práticas

Guarde o envelope_id no seu sistema para conciliação posterior.
Prefira webhooks a polling intensivo; se usar polling, respeite intervalo mínimo de 30 segundos.
Valide tamanho e formato do PDF antes do envio (máx. recomendado: 10 MB por arquivo).
Use ambiente de homologação antes de ir para produção.
Nunca exponha a API Key em front-end, repositórios públicos ou logs.

Pronto para integrar?

Solicite suas credenciais de API e o acesso ao ambiente de homologação com nossa equipe comercial.

Falar com especialista