simples.sign
API RESTMCPopenapi.json

Simples Sign — API pública v1

API pública do Simples Sign para sistemas e agentes de IA: criar envelopes, consultar status, baixar PDF assinado e prova pública, validar documentos e analisar contratos (IA). Operações pagas debitam créditos da organização (comprados em reais no painel; válidos por 12 meses). Autenticação: Authorization: Bearer sks_... (chave criada em Organização → API e agentes de IA). Limite: 120 requisições/min por chave.

Base: https://sign.simples.media/api · Especificação: openapi.json · Agentes: guia MCP

Autenticação

Crie a chave em Organização → API e agentes de IA (só administradores). Ela aparece uma única vez; guardamos apenas o hash SHA-256. Escopos: envelopes:read, envelopes:write, verify, credits:read, ai. Revogação imediata pela mesma tela.

curl https://sign.simples.media/api/v1/credits -H "Authorization: Bearer $SIGN_API_KEY"

Créditos

Operação Custo
Criar envelope 10 créditos
Validar documento 1 crédito
Análise de contrato por IA 5 créditos (0 se já analisado)
Status, listar, PDF assinado, prova grátis

Créditos são comprados em reais (cartão ou Pix, Stripe) pelo painel em Organização → API e agentes de IA. Não há recarga por transferência, carteira, envio entre organizações, saque ou revenda. Regras: validade de 12 meses por compra; cada nova compra revalida todo o saldo (inclusive vencido); avisos por e-mail 30 e 7 dias antes; consumo dos lotes mais antigos primeiro; créditos pagos e bônus separados; pessoa física pode pedir reembolso do pago vencido (devolução em até 30 dias), pessoa jurídica perde, bônus vence sem reembolso. Falha do nosso lado (5xx, erro de IA) estorna automaticamente (refunded: true no erro). Sem créditos a operação retorna 402 insufficient_credits e nada é cobrado.

Endpoints

POST /v1/envelopes

Criar envelope. Cria o envelope e envia os convites por e-mail. Custo: 10 créditos.

Escopo: envelopes:write

GET /v1/envelopes

Listar envelopes. Mais recentes primeiro. Custo: grátis.

Escopo: envelopes:read

GET /v1/envelopes/{id}

Status do envelope. Status do envelope e de cada signatário. Custo: grátis.

Escopo: envelopes:read

GET /v1/envelopes/{id}/signed-pdf

PDF assinado. URL temporária do PDF assinado (só concluídos; 409 not_completed caso contrário). Custo: grátis.

Escopo: envelopes:read

GET /v1/envelopes/{id}/proof

Prova pública. Página /v, JSON de validação, trilha de auditoria, recibo OpenTimestamps e âncora na Simples Ledger. Custo: grátis.

Escopo: envelopes:read

POST /v1/envelopes/{id}/analysis

Analisar contrato (IA). Resumo, cláusulas de risco e perguntas. Resultado em cache pelo SHA-256 do PDF (repetição não é cobrada). Custo: 5 créditos (0 se já analisado).

Escopo: ai

POST /v1/verify

Validar documento. Confere se o PDF (ou o SHA-256) corresponde a um documento assinado no Simples Sign. Custo: 1 crédito.

Escopo: verify

GET /v1/credits

Créditos. Saldo (pago/bônus), validade, lotes, preços e como comprar. Custo: grátis.

Escopo: credits:read

POST /v1/credits/sync

Desativado (410 ledger_deposits_disabled): a recarga por Simples Ledger foi removida.

POST /mcp

Servidor MCP (Streamable HTTP). JSON-RPC 2.0 do Model Context Protocol, sem sessão, respostas application/json. Veja /docs/mcp/.

Exemplo: criar envelope

curl -X POST https://sign.simples.media/api/v1/envelopes \
  -H "Authorization: Bearer $SIGN_API_KEY" -H 'content-type: application/json' \
  -d '{"title":"Contrato de serviço","pdf_base64":"'$(base64 -w0 contrato.pdf)'",
       "signers":[{"name":"Ana","email":"ana@empresa.com","auth":"email"}]}'

Webhooks

Configure a URL (https público, porta 443) em Organização → API e agentes de IA. O segredo whsec_... é exibido uma vez. Eventos: envelope.created, signer.signed, envelope.completed (e ping no teste).

import { createHmac, timingSafeEqual } from 'node:crypto';
function valid(req, rawBody, secret) {
  const [t, v1] = req.headers['x-sign-signature'].split(',').map((p) => p.split('=')[1]);
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // anti-replay
  const mac = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return timingSafeEqual(Buffer.from(mac), Buffer.from(v1));
}

Responda 2xx em até 5 s. Falhas são re-tentadas até 4 vezes (2, 4, 8, 16 min). Use X-Sign-Delivery (id do evento) para descartar duplicados.

Erros e limites

HTTP error Significado
401 invalid_api_key chave ausente, inválida ou revogada
403 insufficient_scope a chave não tem o escopo exigido
402 insufficient_credits créditos insuficientes (cost, balance)
409 not_completed envelope ainda não concluído
429 rate_limited mais de 120 req/min por chave (Retry-After)

A análise por IA é automática e informativa: não é aconselhamento jurídico.

Simples Media LTDA · Termos · Privacidade