API v2 + MCP

API de Assinatura Eletronica

Envie documentos para assinatura via WhatsApp em 1 chamada. Integre com IA via MCP. Validade juridica no Brasil.

Base URL

https://sign.riasistemas.com.br

Fluxo

Base Legal

• Lei 14.063/2020 — Assinatura Eletronica Simples (Art. 4, II) + Avancada (Art. 4, III)
• MP 2.200-2/2001 Art.10 §2 — Validade juridica de documentos eletronicos

Niveis de Assinatura

Quick Start

Envie seu primeiro documento para assinatura em 30 segundos:

1. Obtenha sua API Key

Acesse o Painel de Integracao e copie sua chave (formato rsk_...).

2. Envie um documento

curl -X POST https://sign.riasistemas.com.br/api/v2/send \
  -H "Authorization: Bearer rsk_SUA_API_KEY" \
  -F "file=@contrato.pdf" \
  -F 'data={
    "subject": "Contrato de Servicos",
    "signers": [
      {
        "name": "Maria Silva",
        "phone": "+5541999999999"
      }
    ]
  }'

3. Pronto!

Maria recebe o documento no WhatsApp e assina pelo celular. Voce recebe o webhook envelope.completed quando todos assinarem.

// Resposta
{
  "id": "env_a1b2c3d4...",
  "status": "sent",
  "signers": [{
    "id": "sgn_x1y2z3...",
    "name": "Maria Silva",
    "sign_url": "https://sign.riasistemas.com.br/sign/abc123...",
    "status": "sent"
  }],
  "document": {
    "id": "doc_p1q2r3...",
    "filename": "contrato.pdf",
    "hash": "sha256:a1b2c3d4...",
    "pages": 5
  }
}

Autenticacao

Todas as rotas /api/* e /mcp requerem autenticacao via API Key no header HTTP:

Authorization: Bearer rsk_sua_api_key_aqui

As chaves sao geradas no Painel de Integracao. O prefixo rsk_ identifica chaves do RIA Sign. Apenas o hash SHA-256 da chave e armazenado.

Para clientes MCP (ChatGPT, Claude), use OAuth 2.1 com PKCE — o usuario autoriza via telefone+OTP sem expor a API Key.

Respostas de Erro

Enviar PDF para Assinatura

Envio completo em 1 chamada: upload do PDF + dados dos signatarios + envio automatico via WhatsApp.

curl -X POST https://sign.riasistemas.com.br/api/v2/send \
  -H "Authorization: Bearer rsk_sua_api_key" \
  -F "file=@contrato.pdf" \
  -F 'data={
    "subject": "Contrato de Prestacao de Servicos",
    "signers": [
      {"name": "Maria Silva", "phone": "+5541999999999", "role": "contratante"},
      {"name": "Joao Santos", "phone": "+5541988888888", "role": "contratado"}
    ],
    "selfie": true,
    "idPhoto": true,
    "reminders": 3,
    "webhookUrl": "https://meusite.com/webhook"
  }'

{
  "id": "env_a1b2c3d4...",
  "status": "sent",
  "signers": [
    {
      "id": "sgn_x1y2z3...",
      "name": "Maria Silva",
      "phone": "+5541999999999",
      "sign_url": "https://sign.riasistemas.com.br/sign/abc123...",
      "status": "sent",
      "order": 1
    },
    {
      "id": "sgn_w4v5u6...",
      "name": "Joao Santos",
      "phone": "+5541988888888",
      "sign_url": "https://sign.riasistemas.com.br/sign/def456...",
      "status": "sent",
      "order": 2
    }
  ],
  "document": {
    "id": "doc_p1q2r3...",
    "filename": "contrato.pdf",
    "hash": "sha256:a1b2c3d4...",
    "pages": 5
  }
}

Enviar com Template

Envie contratos usando templates pre-criados, texto livre (analisado por IA) ou templates manuais com placeholders. Sem precisar de PDF — o documento e gerado automaticamente.

{
  "template_id": "tpl_abc123",
  "signers": [{"name": "Maria", "phone": "+5541999999999", "role": "locatario"}],
  "fields": {"VALOR_ALUGUEL": "R$ 2.500,00", "ENDERECO": "Rua das Flores, 123"}
}

{
  "text": "CONTRATO DE PRESTACAO DE SERVICOS\n\nPelo presente, Maria Silva (contratante) contrata Joao Santos (contratado) para...",
  "signers": [
    {"name": "Maria Silva", "phone": "+5541999999999"},
    {"name": "Joao Santos", "phone": "+5541988888888"}
  ]
}

{
  "template_text": "Eu, [NOME_CONTRATANTE], CPF [CPF_CONTRATANTE], contrato [NOME_CONTRATADO] para...",
  "signers": [
    {"name": "Maria", "phone": "+5541999999999", "role": "contratante"},
    {"name": "Joao", "phone": "+5541988888888", "role": "contratado"}
  ]
}

{
  "id": "env_a1b2c3d4...",
  "status": "sent",
  "subject": "Contrato de Servicos",
  "template_mode": true,
  "ai_analyzed": true,
  "warnings": [],
  "signers": [
    {
      "id": "sgn_x1y2z3...",
      "name": "Maria Silva",
      "role": "contratante",
      "sign_url": "https://sign.riasistemas.com.br/sign/abc123...",
      "status": "sent"
    }
  ]
}

Gerar Contrato com IA

Use inteligencia artificial para gerar contratos completos com placeholders e papeis sugeridos.

curl -X POST https://sign.riasistemas.com.br/api/v2/generate \
  -H "Authorization: Bearer rsk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{"type": "contrato_servicos", "description": "Desenvolvimento de site institucional, valor R$5.000, prazo 30 dias"}'

{
  "name": "Contrato de Prestacao de Servicos",
  "template_text": "CONTRATO DE PRESTACAO DE SERVICOS\n\nPelo presente instrumento...\n[NOME_CONTRATANTE]...",
  "placeholders": {
    "NOME_CONTRATANTE": {"label": "Nome do Contratante", "auto": "name"},
    "CPF_CONTRATANTE": {"label": "CPF do Contratante", "auto": "cpf"},
    "VALOR": {"label": "Valor do Servico"}
  },
  "suggested_signers": [
    {"role": "contratante", "description": "Parte contratante", "placeholders": ["NOME_CONTRATANTE", "CPF_CONTRATANTE"]},
    {"role": "contratado", "description": "Prestador de servicos", "placeholders": ["NOME_CONTRATADO", "CPF_CONTRATADO"]}
  ]
}

{
  "id": "tpl_a1b2c3d4...",
  "name": "Contrato de Servicos",
  "template_text": "...(texto atualizado)...",
  "placeholders": {...},
  "suggested_signers": [...],
  "change_summary": "Adicionada clausula 8 com multa de 10% por atraso."
}

Gerenciamento

Endpoints para listar, consultar, baixar e gerenciar envelopes e templates.

{
  "id": "env_a1b2c3d4...",
  "status": "sent",
  "subject": "Contrato de Servicos",
  "created_at": "2026-04-15T12:00:00Z",
  "signers": [
    {
      "id": "sgn_x1y2z3...",
      "name": "Maria Silva",
      "phone": "+5541999999999",
      "role": "contratante",
      "status": "signed",
      "sign_url": "https://sign.riasistemas.com.br/sign/abc123...",
      "viewed_at": "2026-04-15T12:05:00Z",
      "signed_at": "2026-04-15T12:08:00Z"
    }
  ],
  "document": {
    "id": "doc_p1q2r3...",
    "filename": "contrato.pdf",
    "hash": "sha256:a1b2c3d4...",
    "signed_hash": "sha256:e5f6g7h8...",
    "pages": 5
  }
}

{
  "reminded": [
    {"name": "Joao Santos", "status": "sent", "channel": "whatsapp"}
  ]
}

Servidor MCP

O RIA Sign implementa o Model Context Protocol (MCP), permitindo que assistentes de IA como ChatGPT, Claude e outros clientes MCP enviem documentos para assinatura diretamente pela conversa.

O que e MCP?

O MCP e um protocolo padrao que conecta modelos de IA a servicos externos via JSON-RPC 2.0. O RIA Sign expoe ferramentas (tools) que qualquer cliente MCP pode chamar para criar, enviar e gerenciar documentos de assinatura.

Conexao

Autenticacao MCP

Use Authorization: Bearer rsk_... (API Key direta) ou um token obtido via OAuth 2.1. A autenticacao e necessaria apenas para tools/call — initialize e tools/list funcionam sem auth.

Protocolo

Versoes suportadas: 2025-11-25 (default) e 2025-03-26.

Exemplo — Inicializar

curl -X POST https://sign.riasistemas.com.br/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "clientInfo": {"name": "MeuApp", "version": "1.0"}
    }
  }'

Exemplo — Listar ferramentas

curl -X POST https://sign.riasistemas.com.br/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Exemplo — Chamar ferramenta

curl -X POST https://sign.riasistemas.com.br/mcp \
  -H "Authorization: Bearer rsk_sua_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "generate_contract",
      "arguments": {
        "type": "contrato_servicos",
        "description": "Site institucional, R$5000, 30 dias"
      }
    }
  }'

Ferramentas MCP (19)

Todas as ferramentas disponiveis via tools/call:

Envio

Inteligencia Artificial

Gerenciamento

Templates e Contatos

Agent Skill — Authoring Playbook

O RIA Sign publica uma Skill oficial (formato Anthropic) que ensina assistentes de IA (Claude, ChatGPT) a redigir contratos com a estrutura correta para a tool send_structured_contract: como nomear placeholders, quando usar CEP+ViaCEP, regras de assinatura, anti-duplicacao, validacao de signatarios e preview obrigatorio antes do envio.

O que a Skill cobre

• Prime Directive: minimizar campos de digitacao manual por signatario. Hierarquia: inline → auto → CEP+ViaCEP → shared → date picker → manual (ultimo recurso).
• Placeholders: tipos (auto, type, input_type, shared), naming UPPER_SNAKE_CASE, regras de reuso.
• Enderecos: padrao de 7 placeholders com CEP unico input + auto-fill ViaCEP. Comarca/foro derivada do 1º signatario.
• Valores monetarios: 1 placeholder [VALOR] em formato "R$ X.XXX,XX (extenso)" — nunca separar numerico e por extenso.
• Datas: auto:date (hoje, automatico) vs input_type:date (date picker do Flow).
• Signatarios: minimo de partes por tipo de documento, ordem (sequencial vs paralelo), regra do remetente, testemunhas, representante legal, tripartite.
• Pre-send safety: preview obrigatorio + confirmacao explicita antes de disparar WhatsApp irreversivel.
• 4 exemplos gold-standard (locacao, recibo, procuracao, NDA bilateral) e 18 anti-patterns categorizados.

Como usar com seu cliente MCP

Clientes MCP modernos (Claude.ai, Claude Desktop, ChatGPT) podem carregar a Skill automaticamente quando o RIA Sign for instalado pelo diretorio oficial da Anthropic. Para uso manual ou em outros clientes, baixe o SKILL.md do repositorio publico e carregue como system context antes de pedir ao LLM para redigir um documento.

OAuth 2.1

Para clientes MCP (ChatGPT, Claude, etc.), o RIA Sign suporta OAuth 2.1 com PKCE. O usuario autoriza via telefone + OTP no WhatsApp — sem precisar da API Key.

Endpoints

Descoberta (Well-Known)

Fluxo de Autorizacao

Exemplo — Registrar cliente

curl -X POST https://sign.riasistemas.com.br/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name": "MeuApp", "redirect_uris": ["https://meuapp.com/callback"]}'

// Resposta
{"client_id": "client_abc123...", "redirect_uris": ["https://meuapp.com/callback"]}

Exemplo — Trocar codigo por token

curl -X POST https://sign.riasistemas.com.br/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "authcode_xxx...",
    "client_id": "client_abc123",
    "redirect_uri": "https://meuapp.com/callback",
    "code_verifier": "PKCE_VERIFIER_AQUI"
  }'

// Resposta
{
  "access_token": "rsk_...",
  "token_type": "bearer",
  "expires_in": 2592000
}

PKCE (S256)

Recomendado para seguranca. Envie code_challenge na autorizacao e code_verifier na troca do token. Metodo suportado: S256 (SHA-256 + base64url).

Webhooks

Receba notificacoes em tempo real sobre eventos do envelope. Configure o webhookUrl ao criar o envelope.

Eventos

Payload

Header X-RiaSign-Event indica o tipo. Header X-RiaSign-Signature contem o HMAC-SHA256 para verificacao.

{
  "event": "signer.signed",
  "envelope_id": "env_a1b2c3d4...",
  "signer": {
    "name": "Maria Silva",
    "phone": "+5541999999999",
    "signed_at": "2026-04-15T14:43:06Z"
  },
  "channel": "whatsapp_flow",
  "timestamp": "2026-04-15T14:43:06Z"
}

Exemplo — envelope.completed

{
  "event": "envelope.completed",
  "envelope_id": "env_a1b2c3d4...",
  "document_hash": "sha256:e5f6g7h8...",
  "signers": [
    {"name": "Maria Silva", "signed_at": "2026-04-15T14:43:06Z"},
    {"name": "Joao Santos", "signed_at": "2026-04-15T15:02:18Z"}
  ],
  "timestamp": "2026-04-15T15:02:18Z"
}

Verificacao de Assinatura

const crypto = require('crypto');
const signature = crypto
  .createHmac('sha256', suaApiKey)
  .update(requestBody)
  .digest('hex');

if (signature === headers['x-riasign-signature']) {
  // Webhook autentico
}

Retry

Em caso de falha (timeout ou status >= 400), o webhook e reenviado com backoff:

• 1a tentativa: imediato
• 2a tentativa: +2 segundos
• 3a tentativa: +5 segundos

Codigos de Erro

A API retorna erros em JSON com o campo error:

{"error": "Envelope not found"}

IDs

Todos os IDs usam prefixos para identificacao:

Exemplos de Integracao

Node.js

const fs = require('fs');

const form = new FormData();
form.append('file', new Blob([fs.readFileSync('contrato.pdf')]), 'contrato.pdf');
form.append('data', JSON.stringify({
  subject: 'Contrato de Servicos',
  signers: [{name: 'Maria Silva', phone: '+5541999999999'}],
  selfie: true,
  webhookUrl: 'https://meusite.com/webhook',
}));

const res = await fetch('https://sign.riasistemas.com.br/api/v2/send', {
  method: 'POST',
  headers: {'Authorization': 'Bearer rsk_sua_api_key'},
  body: form,
});

const envelope = await res.json();
console.log('Envelope criado:', envelope.id);
// Signatarios recebem no WhatsApp automaticamente

Python

import requests, json

with open('contrato.pdf', 'rb') as f:
    res = requests.post(
        'https://sign.riasistemas.com.br/api/v2/send',
        headers={'Authorization': 'Bearer rsk_sua_api_key'},
        files={'file': ('contrato.pdf', f, 'application/pdf')},
        data={'data': json.dumps({
            'subject': 'Contrato de Servicos',
            'signers': [{'name': 'Maria Silva', 'phone': '+5541999999999'}],
            'selfie': True,
        })}
    )

envelope = res.json()
print(f'Envelope criado: {envelope["id"]}')

MCP (Claude / ChatGPT)

Configure o RIA Sign como servidor MCP no seu cliente:

// claude_desktop_config.json (exemplo)
{
  "mcpServers": {
    "ria-sign": {
      "url": "https://sign.riasistemas.com.br/mcp",
      "transport": "streamable-http"
    }
  }
}

Depois, basta pedir ao assistente: "Gere um contrato de servicos e envie para Maria Silva (+5541999999999)".