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_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Cada 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.

RotaPara quê
POST /v1/documentsCriar e, se quiser, já enviar
GET /v1/documentsListar, com filtros por status, referência e data
GET /v1/documents/{id}Status do documento e de cada pessoa
POST /v1/documents/{id}/sendEnviar um rascunho
POST /v1/documents/{id}/remindLembrar quem ainda não assinou
POST /v1/documents/{id}/cancelCancelar
GET /v1/documents/{id}/filesLinks temporários para o PDF assinado e o certificado de auditoria
GET /v1/templatesOs seus modelos
GET /v1/accountPlano, documentos disponíveis e equipe
POST /v1/exportsZIP 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.

EventoQuando chega
document.sentO documento saiu para assinatura
signer.viewedAlguém abriu o próprio link pela primeira vez
signer.signedAlguém assinou
signer.declinedAlguém recusou assinar
document.completedTodos assinaram e o PDF assinado está pronto
document.cancelledO documento foi cancelado
document.expiredO link venceu sem que todos assinassem
nom151.issuedSaiu a constância NOM-151 (documentos sob a lei mexicana)
nom151.failedA 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 2xx em 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 id para não repetir e creado para ordenar. O cabeçalho SignSolu-Entrega identifica cada entrega.
  • Em GET /v1/webhooks/{id}/deliveries você vê cada entrega com as tentativas, e POST …/deliveries/{entrega}/retry reenvia na hora.
  • O segredo vazou? POST /v1/webhooks/{id}/rotate-secret gera 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_…" } }
HTTPO que aconteceu
400Algo na requisição não é válido, e mensaje diz o quê
401Falta a chave, ela não existe ou foi revogada
403A chave não tem a permissão, ou o seu plano está sem saldo
404Não existe, ou não é da sua equipe
409Conflito. O status do documento não permite, ou a referência já existe
422Não foi possível ler o PDF
429Você passou do limite. Espere o que diz o cabeçalho Retry-After
500Erro 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 POST aceita Idempotency-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.