API de assinatura eletrônica para desenvolvedores
Com a API v1 o seu sistema cria documentos, envia para assinatura por e-mail ou WhatsApp e fica sabendo de cada assinatura na hora. Cada documento leva a mesma evidência do painel: certificado de auditoria e impressão digital SHA-256 do arquivo.
Endereço base: https://signsolu.com/api/v1
Chaves
As chaves são criadas no seu painel, em Desenvolvedores. Há dois tipos. As ssk_live_… criam documentos reais e as ssk_test_… servem para testar. A chave completa aparece uma única vez. Guarde no seu cofre de segredos, nunca no código do navegador nem num app de celular.
Cada requisição leva a chave no cabeçalho Authorization.
Authorization: Bearer ssk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXCada chave tem permissões: documents:read, documents:write, templates:read, account:read, webhooks:read, webhooks:write e exports:write. Escrever inclui ler. Dê a cada sistema só o que ele precisa. Se uma chave vazar, revogue no painel e ela para de valer na hora.
Seu primeiro documento
Envie o PDF em Base64, quem assina e enviar: true. O campo referencia é o seu número interno, como pedido, processo ou contrato de crédito. Ele não se repete dentro da sua equipe, então repetir a requisição não cria dois documentos. Os nomes dos campos são os mesmos em todos os idiomas.
curl https://signsolu.com/api/v1/documents \
-H "Authorization: Bearer $SIGNSOLU_CHAVE" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: pedido-1042" \
-d '{
"titulo": "Contrato de locação - Apto 3B",
"referencia": "pedido-1042",
"pdf_base64": "JVBERi0xLjcK...",
"firmantes": [
{ "nombre": "Ana Souza", "correo": "ana@exemplo.com.br", "canal": "email", "orden": 1,
"campos": [{ "pagina": 3, "x": 0.12, "y": 0.8, "w": 0.3, "h": 0.06 }] },
{ "nombre": "Luís Pereira", "telefono": "+5511912345678", "canal": "whatsapp", "orden": 2,
"campos": [{ "ancla": "Assinatura do locatário" }] }
],
"orden_estricto": true,
"vence_en_dias": 30,
"enviar": true
}'A resposta traz o id do documento, o status e o link de cada pessoa. As caixas de assinatura vão em frações da página, de 0 a 1, a partir do canto superior esquerdo. Também dá para posicionar por um texto do PDF com ancla, e a caixa nasce onde esse texto começa. Para criar a partir de um dos seus modelos, envie template_id e datos. Ou suba o arquivo como multipart/form-data, com file e datos.
| Rota | Para quê |
|---|---|
POST /v1/documents | Criar e, se quiser, já enviar |
GET /v1/documents | Listar, com filtros por status, referência e data |
GET /v1/documents/{id} | Status do documento e de cada pessoa |
POST /v1/documents/{id}/send | Enviar um rascunho |
POST /v1/documents/{id}/remind | Lembrar quem ainda não assinou |
POST /v1/documents/{id}/cancel | Cancelar |
GET /v1/documents/{id}/files | Links temporários para o PDF assinado e o certificado de auditoria |
GET /v1/templates | Os seus modelos |
GET /v1/account | Plano, documentos disponíveis e equipe |
POST /v1/exports | ZIP com os assinados de um período, os certificados e um índice com as impressões digitais |
Webhooks
Em vez de perguntar a cada minuto, cadastre um endereço https e avisamos cada mudança. Só aceitamos endereços públicos com https.
curl https://signsolu.com/api/v1/webhooks \
-H "Authorization: Bearer $SIGNSOLU_CHAVE" \
-H "Content-Type: application/json" \
-d '{ "url": "https://seu-sistema.com.br/signsolu/eventos",
"eventos": ["document.completed", "signer.declined"] }'A resposta traz o secreto (whsec_…) uma única vez. Sem eventos, você recebe todos. Com POST /v1/webhooks/{id}/test mandamos um evento de teste na hora.
| Evento | Quando chega |
|---|---|
document.sent | O documento saiu para assinatura |
signer.viewed | Alguém abriu o próprio link pela primeira vez |
signer.signed | Alguém assinou |
signer.declined | Alguém recusou assinar |
document.completed | Todos assinaram e o PDF assinado está pronto |
document.cancelled | O documento foi cancelado |
document.expired | O link venceu sem que todos assinassem |
nom151.issued | Saiu a constância NOM-151 (documentos sob a lei mexicana) |
nom151.failed | A constância NOM-151 não pôde ser emitida (traz o motivo) |
Cada aviso é um POST com este corpo. Ele traz o mínimo, então consulte o documento pelo id para ver o detalhe. Não inclui e-mails, telefones nem dados de identificação de quem assina.
{
"id": "evt_8f2c1a0e5b6d4c3a9e7f1b2d3c4a5e6f",
"tipo": "document.completed",
"creado": "2026-11-14T18:22:05.000Z",
"modo": "live",
"datos": {
"documento": { "id": "0b1c…", "estado": "completed", "referencia": "pedido-1042" },
"completado_at": "2026-11-14T18:22:04.913Z"
}
}Confira SEMPRE a assinatura antes de confiar no aviso. O cabeçalho SignSolu-Firma traz t (segundos Unix) e v1, o HMAC-SHA256 em hexadecimal de t + "." + corpo com o seu segredo. Use o corpo exatamente como chegou, sem serializar de novo, e rejeite o que tiver mais de 5 minutos.
// Node.js (Express): o corpo cru, sem JSON.parse antes de conferir
import crypto from "node:crypto";
function assinaturaValida(cabecalho, corpo, segredo, toleranciaSeg = 300) {
let t = null;
const assinaturas = [];
for (const parte of String(cabecalho ?? "").split(",")) {
const [k, v = ""] = parte.trim().split("=", 2);
if (k === "t" && /^\d{1,12}$/.test(v)) t = Number(v);
if (k === "v1" && /^[0-9a-f]{64}$/.test(v)) assinaturas.push(Buffer.from(v, "hex"));
}
// Fora da janela = repetição de um aviso antigo: rejeite.
if (t === null || assinaturas.length === 0 || Math.abs(Date.now() / 1000 - t) > toleranciaSeg) return false;
const esperada = crypto.createHmac("sha256", segredo)
.update(Buffer.concat([Buffer.from(`${t}.`), Buffer.from(corpo)])).digest();
// Sempre o mesmo tamanho (32 bytes): timingSafeEqual nunca falha.
return assinaturas.some((a) => crypto.timingSafeEqual(a, esperada));
}
app.post("/signsolu/eventos", express.raw({ type: "application/json" }), (req, res) => {
if (!assinaturaValida(req.get("SignSolu-Firma"), req.body, process.env.SIGNSOLU_WHSEC)) {
return res.status(400).send("assinatura inválida");
}
const evento = JSON.parse(req.body);
// Guarde evento.id: se já processou, responda 200 e não faça nada
// (dentro dos 5 minutos alguém poderia repetir o mesmo aviso).
res.sendStatus(200);
});# Python (Flask)
import hashlib, hmac, os, re, time
from flask import Flask, request, abort
app = Flask(__name__)
def assinatura_valida(cabecalho, corpo, segredo, tolerancia=300):
t, assinaturas = None, []
for parte in (cabecalho or "").split(","):
k, _, v = parte.strip().partition("=")
if k == "t" and re.fullmatch(r"\d{1,12}", v):
t = int(v)
if k == "v1" and re.fullmatch(r"[0-9a-f]{64}", v):
assinaturas.append(v)
# Fora da janela = repetição de um aviso antigo: rejeite.
if t is None or not assinaturas or abs(time.time() - t) > tolerancia:
return False
esperada = hmac.new(segredo.encode(), f"{t}.".encode() + corpo, hashlib.sha256).hexdigest()
return any(hmac.compare_digest(esperada, a) for a in assinaturas)
@app.post("/signsolu/eventos")
def eventos():
corpo = request.get_data() # bytes, exatamente como chegaram
if not assinatura_valida(request.headers.get("SignSolu-Firma"), corpo, os.environ["SIGNSOLU_WHSEC"]):
abort(400)
evento = request.get_json()
# Guarde evento["id"]: se já processou, responda 200 e não faça nada.
return "", 200- Responda com um
2xxem menos de 10 segundos e processe depois. Um redirecionamento conta como falha. - Se falhar, tentamos de novo com espera crescente (1 min, 5 min, 15 min, 1 h, 3 h, 6 h, 12 h e depois a cada 24 h) durante 72 horas.
- Se em 72 horas você não aceitar nenhuma entrega, o webhook é desligado. Reative com
POST /v1/webhooks/{id}/enable. - O mesmo evento pode chegar duas vezes e nem sempre em ordem. Use
idpara não repetir ecreadopara ordenar. O cabeçalhoSignSolu-Entregaidentifica cada entrega. - Em
GET /v1/webhooks/{id}/deliveriesvocê vê cada entrega com as tentativas, ePOST …/deliveries/{entrega}/retryreenvia na hora. - O segredo vazou?
POST /v1/webhooks/{id}/rotate-secretgera um novo e o anterior deixa de valer.
Modo de teste
Com uma chave ssk_test_… tudo funciona igual, mas os documentos ficam marcados como de teste. Levam marca-d’água, não descontam do plano e não mandam e-mail. Os eventos deles só chegam aos webhooks cadastrados com uma chave de teste. Use para o seu ambiente de desenvolvimento e os seus testes automáticos.
Constância NOM-151 para documentos sob a lei mexicana
Para documentos assinados sob a lei mexicana, a SignSolú emite a constância de conservação NOM-151 do documento assinado por meio de um prestador de serviços de certificação credenciado pela Secretaria de Economia do México. Ela é ativada para a sua equipe sob solicitação.
Quando a constância sai, avisamos com nom151.issued e você baixa em GET /v1/documents/{id}/files. Se não puder ser emitida, chega nom151.failed com o motivo. Documentos de teste nunca pedem a constância.
Erros
Todos os erros têm o mesmo formato. Guarde o request_id se escrever para o suporte. Os códigos de erro são os mesmos em todos os idiomas.
{ "error": { "codigo": "documento_no_encontrado", "mensaje": "…", "request_id": "req_…" } }| HTTP | O que aconteceu |
|---|---|
| 400 | Algo na requisição não é válido, e mensaje diz o quê |
| 401 | Falta a chave, ela não existe ou foi revogada |
| 403 | A chave não tem a permissão, ou o seu plano está sem saldo |
| 404 | Não existe, ou não é da sua equipe |
| 409 | Conflito. O status do documento não permite, ou a referência já existe |
| 422 | Não foi possível ler o PDF |
| 429 | Você passou do limite. Espere o que diz o cabeçalho Retry-After |
| 500 | Erro nosso. Tente de novo com a mesma Idempotency-Key |
Limites de uso
- Chave
live: 120 requisições por minuto e 10.000 por dia. - Chave
test: 30 requisições por minuto. - Todo
POSTaceitaIdempotency-Key. Se repetir a requisição com a mesma chave em 24 horas, devolvemos a mesma resposta sem fazer nada duas vezes. - Máximo de 10 webhooks por conta e por modo.
Precisa de mais, ou quer ajuda com a integração? Escreva para info@solufintech.com.
Preço e termos
As chaves de teste não custam nada. As de produção vêm nos planos pagos, sem custo à parte. Cada documento criado pela API desconta do seu plano ou do pacote da sua equipe, igual no painel. O plano inclui 200 documentos por mês. Para mais, escreva para nós e montamos um plano para o seu volume.
Para quem é e o que resolve, em poucas linhas: API de assinatura eletrônica para empresas. Os preços estão em preços. O uso da API segue os termos de uso da API.