Resposta curtaA API REST do WS Sign cria documentos, envia para assinatura, acompanha e baixa o PDF assinado, e os webhooks avisam o seu sistema quando algo acontece. Disponível no plano Empresa.
Autenticação
Crie uma chave em Configurações > API e webhooks e envie em todas as chamadas:
Authorization: Bearer wss_live_xxxxxxxx_...
- Acesso: "leitura e envio" ou "só leitura", escolhido na criação.
- Validade: 90 dias, 180 dias ou 1 ano. Vencida, a chave para de funcionar.
- Onde usar: só no seu servidor. A API não aceita chamadas de navegador de outros sites, para a chave nunca ficar exposta em página ou aplicativo.
- Segurança: a chave aparece uma única vez. Criar uma chave exige a senha de um administrador, e o dono da conta é avisado por e-mail. Quem deixa de ser administrador tem as chaves que criou revogadas.
Limites
- Por chave: 10 chamadas por minuto e 200 por dia no plano Empresa (30 e 1.000 no Corporativo). Um documento enviado pela API leva cerca de 7 chamadas: o limite diário comporta cerca de 28 documentos completos, 4 vezes a média diária do plano. Acima dele, a resposta é
429com o cabeçalhoRetry-After. - Para acompanhar a situação dos documentos, use os webhooks em vez de consultar a API repetidamente.
- PDF: até 10 MB por arquivo e 20 MB por documento; até 30 participantes por documento.
- Os documentos enviados pela API contam na franquia do plano, como os enviados pelo painel.
O que a API faz
Base: https://wssign.com.br. Corpo e respostas em JSON, exceto o envio de PDF e os downloads.
| Método | Caminho | O que faz |
|---|---|---|
GET | /api/v1/me | Conta e plano da chave (teste de conexão). |
GET | /api/v1/envelopes | Lista documentos, do mais novo ao mais antigo. Filtros: status, folder, tag, q (busca). Páginas: page e per (até 100). |
POST | /api/v1/envelopes | Cria um rascunho: title, message, deadline_days, reminders, folder_id, tags. |
GET | /api/v1/envelopes/{id} | Documento com arquivos, participantes, campos e situação. |
PATCH | /api/v1/envelopes/{id} | Altera título, mensagem, prazo e lembretes (só no rascunho); pasta e etiquetas a qualquer momento. |
DELETE | /api/v1/envelopes/{id} | Exclui um rascunho. |
POST | /api/v1/envelopes/{id}/documents | Envia um PDF (multipart/form-data, campo file; até 10 MB por arquivo e 20 MB por documento). |
DELETE | /api/v1/envelopes/{id}/documents/{doc} | Remove um PDF do rascunho. |
PUT | /api/v1/envelopes/{id}/participants | Define os participantes: name, email, cpf, action (sign, approve, witness, cc), stage (ordem), role_label e, em nome de empresa, on_behalf, company, cnpj, capacity. |
PUT | /api/v1/envelopes/{id}/fields | Posiciona os campos: document_id, participant_id, page, x, y, w, h (de 0 a 1, proporcionais à página) e type (signature, initials, name, cpf, date, text, checkbox). |
POST | /api/v1/envelopes/{id}/send | Envia para assinatura. Cada participante recebe o convite por e-mail. |
POST | /api/v1/envelopes/{id}/cancel | Cancela um documento em andamento (reason). |
POST | /api/v1/envelopes/{id}/extend | Prorroga o prazo (days, de 1 a 90). |
POST | /api/v1/envelopes/{id}/participants/{pid}/resend | Reenvia o convite a um participante. |
PATCH | /api/v1/envelopes/{id}/participants/{pid}/contact | Corrige o e-mail de quem ainda não assinou (email, reason). |
POST | /api/v1/envelopes/{id}/new-version | Cria um novo rascunho a partir de um documento. |
GET | /api/v1/envelopes/{id}/documents/{doc}/file | Baixa um PDF original. |
GET | /api/v1/envelopes/{id}/final | Baixa o PDF assinado, com o Termo de Evidências. |
GET | /api/v1/envelopes/{id}/evidence | Histórico de eventos do documento. |
GET · POST | /api/v1/folders | Lista e cria pastas. |
Ficam só no painel, e a API responde 403: usuários, chaves de API, webhooks, plano e cobrança, exportação em ZIP, auditoria e dados da conta.
Exemplo: do PDF ao envio
K="Authorization: Bearer $WSSIGN_KEY"
# 1. cria o rascunho
curl -s -X POST https://wssign.com.br/api/v1/envelopes -H "$K" -H "Content-Type: application/json" \
-d '{"title":"Contrato de locação","deadline_days":15}'
# 2. envia o PDF
curl -s -X POST https://wssign.com.br/api/v1/envelopes/ID/documents -H "$K" -F "file=@contrato.pdf"
# 3. participantes
curl -s -X PUT https://wssign.com.br/api/v1/envelopes/ID/participants -H "$K" -H "Content-Type: application/json" \
-d '{"participants":[{"name":"Maria Silva","email":"maria@exemplo.com.br","cpf":"00000000000","action":"sign"}]}'
# 4. envia para assinatura
curl -s -X POST https://wssign.com.br/api/v1/envelopes/ID/send -H "$K"
Sem campos posicionados, cada participante assina no Termo de Evidências. Para assinar sobre o PDF, defina os campos antes do envio.
Webhooks
Cadastre o endereço em Configurações > API e webhooks. Eventos: envelope.sent, envelope.completed, envelope.refused, envelope.canceled, envelope.expired, participant.signed e participant.refused.
- Endereço
httpsde um domínio público; endereços internos ou reservados são recusados. - Cada chamada traz
X-WSSign-Event,X-WSSign-Delivery(identificador único, use para ignorar repetições),X-WSSign-TimestampeX-WSSign-Signature. - A assinatura é
sha256=seguida do HMAC-SHA256 detimestamp + "." + corpo, com o segredo do webhook. Confira sempre e recuse horários com mais de 5 minutos de diferença. - Responda
2xxem até 10 segundos. Sem resposta, o envio é repetido em 1, 5, 15, 60, 360 e 720 minutos.
// Node.js
const crypto = require("crypto");
function valido(req, corpoBruto, segredo) {
const ts = req.headers["x-wssign-timestamp"];
const esperado = "sha256=" + crypto.createHmac("sha256", segredo).update(ts + "." + corpoBruto).digest("hex");
const recebido = req.headers["x-wssign-signature"] || "";
return Math.abs(Date.now() / 1000 - Number(ts)) < 300 &&
recebido.length === esperado.length && crypto.timingSafeEqual(Buffer.from(recebido), Buffer.from(esperado));
}
Erros
Os erros vêm como {"error": "...", "message": "..."}: 400 dado inválido, 401 chave inválida ou vencida, 403 operação fora da API, chave só de leitura ou plano sem API, 404 não encontrado, 409 o documento mudou de situação, 422 arquivo recusado, 429 limite de chamadas.