Emita uma procuração particular com assinatura eletrônica em minutos, sem imprimir, sem deslocamento e sem reconhecimento de firma: o outorgante assina com biometria facial + OTP (ou com certificado ICP-Brasil, quando a contraparte exigir), com validade jurídica fundada na MP 2.200-2/2001 e tratamento de dados conforme a LGPD. Cada procuração sai acompanhada de um pacote de evidências assinado digitalmente (.p7m) que qualquer terceiro — o outorgado, um banco, um juiz — pode verificar de forma independente.
Público-alvo: escritórios de advocacia com sistema próprio, contabilidades e legaltechs que precisam gerar e coletar procurações de clientes em escala.
⚠️ Escopo jurídico — este guia cobre procuração particular (instrumento particular, Código Civil art. 653 e seguintes). Atos que a lei exige por instrumento público ou que dependem de registro em cartório (ex.: alienação de imóveis por escritura pública) ficam fora do escopo. Além disso, a aceitação de procurações eletrônicas por terceiros — bancos, juntas comerciais, órgãos públicos — varia caso a caso: confirme com a contraparte antes de padronizar o fluxo. O foco aqui são procurações entre particulares: representação em assembleia, representação perante a contabilidade, representação comercial.
POST /oauth2/token (OAuth2 client_credentials).POST /v1/signing-sessions, perfil BIOMETRIC_PLUS_OTP e o PDF da procuração em base64.url + "?cs=" + clientSecret como se fosse o outorgante e conclua aceite → biometria → OTP (em HML, o código vem em sandbox.otpCode).evidenceId retornado, chame GET /v1/verify/{evidenceId}/downloads e baixe o pacote de evidências .p7m e o PDF final carimbado — sua primeira procuração eletrônica completa.O fluxo tradicional de uma procuração particular é desproporcional ao valor do documento: o escritório redige, envia por e-mail, o cliente imprime, assina, reconhece firma em cartório (fila, taxa, horário comercial) e devolve o papel por motoboy ou foto de baixa qualidade no WhatsApp. Para uma contabilidade que precisa de procurações de dezenas de clientes todo início de ano, ou uma legaltech que representa titulares em assembleias, esse ciclo consome dias por documento e trava o serviço principal.
O ponto sensível é que a procuração é um documento de outorga de poderes — quem a recebe quer segurança de que foi mesmo aquele CPF que assinou. Um aceite de um clique dificilmente convence a contraparte; papel com firma reconhecida convence, mas custa caro em tempo. A procuração digital com biometria facial resolve o meio-termo: o outorgante prova presença (liveness), o rosto é comparado com a base vinculada ao CPF, e um código OTP confirma a posse do e-mail ou telefone. Tudo isso fica registrado em um pacote de evidências assinado com certificado ICP-Brasil.
O resultado de negócio: a procuração sai no mesmo dia (frequentemente na mesma hora), o custo de cartório desaparece para os casos em que o instrumento particular basta, e o escritório passa a ter um protocolo verificável publicamente para anexar ao processo ou apresentar à contraparte — em vez de um PDF escaneado cuja autenticidade ninguém consegue checar.
Seu sistema (jurídico / contábil / legaltech)
│ 1. POST /oauth2/token (autentica)
│ 2. POST /v1/signing-sessions (PDF da procuração + BIOMETRIC_PLUS_OTP)
▼
SignDocs API ──► e-mail de convite (se `owner` informado)
│ ou link entregue por seus canais (url + "?cs=" + clientSecret)
▼
Outorgante ──► página hospedada: lê a procuração → aceita
│ → biometria facial (liveness + match por CPF)
│ → digita OTP recebido por e-mail/SMS
▼
SignDocs ──► webhook SIGNING_SESSION.COMPLETED { evidenceId }
│
▼
Seu sistema ──► GET /v1/verify/{evidenceId}/downloads
→ pacote .p7m + PDF final carimbado (arquive no dossiê)Por que sessão de assinatura e não envelope ou sessão de confiança:
| Primitiva | Serve para | Procuração particular? |
|---|---|---|
Sessão de assinatura (POST /v1/signing-sessions) |
1 signatário sobre 1 documento | ✅ Sim — a procuração é ato unilateral: só o outorgante assina; o outorgado não precisa assinar para o mandato valer |
Envelope (POST /v1/envelopes) |
2+ signatários sobre o mesmo documento | Apenas se houver mais de um outorgante (ex.: sócios outorgando em conjunto) ou se você quiser a assinatura de aceite do outorgado no mesmo PDF |
Sessão de confiança (POST /v1/trust-sessions) |
Autenticar uma ação sem documento | Não — aqui existe um PDF que precisa ser assinado |
Se o seu caso tiver múltiplos outorgantes, o mesmo desenho funciona trocando a sessão por um envelope — veja Envelopes de Assinatura Expressa.
transactions:read transactions:write steps:write evidence:read webhooks:write (adicione verification:write se for usar POST /v1/verify/document).@signdocs-brasil/api (npm) ou signdocs-brasil (PyPI). Para Go, Java, PHP e C#, consulte o guia dos SDKs.🟠 HML vs Produção — desenvolva sempre em HML (
https://api-hml.signdocs.com.br); credenciais HML não consomem cota do plano e os dados expiram em 7 dias. Produção éhttps://api.signdocs.com.br. Em HML a biometria é simulada e o OTP vem na resposta (sandbox.otpCode).
A API usa OAuth2 client_credentials, servidor-a-servidor. Troque client_id + client_secret por um access_token:
export SIGNDOCS_BASE_URL="https://api-hml.signdocs.com.br"
ACCESS_TOKEN=$(curl -s -X POST "$SIGNDOCS_BASE_URL/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=$SIGNDOCS_CLIENT_ID&client_secret=$SIGNDOCS_CLIENT_SECRET" \
| jq -r '.access_token')import { SignDocsBrasilClient } from '@signdocs-brasil/api';
const client = new SignDocsBrasilClient({
clientId: process.env.SIGNDOCS_CLIENT_ID!,
clientSecret: process.env.SIGNDOCS_CLIENT_SECRET!,
baseUrl: process.env.SIGNDOCS_BASE_URL, // https://api-hml.signdocs.com.br
});import os
from signdocs_brasil import SignDocsBrasilClient, ClientConfig
client = SignDocsBrasilClient(ClientConfig(
client_id=os.environ['SIGNDOCS_CLIENT_ID'],
client_secret=os.environ['SIGNDOCS_CLIENT_SECRET'],
base_url=os.environ.get('SIGNDOCS_BASE_URL', 'https://api-hml.signdocs.com.br'),
))O SDK renova o token automaticamente; no HTTP puro, cache o token até perto do expires_in.
O perfil BIOMETRIC_PLUS_OTP exige signer.cpf (para o match biométrico) e signer.email (para o OTP — ou phone + otpChannel: "sms"). Use metadata para amarrar a sessão ao seu dossiê interno: esses pares chave-valor voltam nos webhooks e ficam gravados no pacote de evidências.
PDF_BASE64=$(base64 -w0 procuracao-particular.pdf)
curl -s -X POST "$SIGNDOCS_BASE_URL/v1/signing-sessions" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d @- <<EOF
{
"purpose": "DOCUMENT_SIGNATURE",
"policy": { "profile": "BIOMETRIC_PLUS_OTP" },
"signer": {
"name": "Helena Prado",
"cpf": "12345678901",
"email": "helena@example.com",
"userExternalId": "cliente-0042"
},
"owner": {
"name": "Almeida & Prado Advogados",
"email": "procuracoes@escritorio.example.com"
},
"document": { "content": "$PDF_BASE64", "filename": "procuracao-particular.pdf" },
"metadata": {
"tipo_documento": "procuracao_particular",
"outorgado": "Carlos Menezes",
"poderes": "representacao_assembleia_2026",
"dossie": "PROC-2026-0187"
},
"returnUrl": "https://app.escritorio.example.com/procuracoes/concluida",
"locale": "pt-BR",
"expiresInMinutes": 1440
}
EOFimport { readFileSync } from 'fs';
const pdfBase64 = readFileSync('procuracao-particular.pdf').toString('base64');
const session = await client.signingSessions.create({
purpose: 'DOCUMENT_SIGNATURE',
policy: { profile: 'BIOMETRIC_PLUS_OTP' },
signer: {
name: 'Helena Prado',
cpf: '12345678901',
email: 'helena@example.com',
userExternalId: 'cliente-0042',
},
owner: { name: 'Almeida & Prado Advogados', email: 'procuracoes@escritorio.example.com' },
document: { content: pdfBase64, filename: 'procuracao-particular.pdf' },
metadata: {
tipo_documento: 'procuracao_particular',
outorgado: 'Carlos Menezes',
poderes: 'representacao_assembleia_2026',
dossie: 'PROC-2026-0187',
},
returnUrl: 'https://app.escritorio.example.com/procuracoes/concluida',
locale: 'pt-BR',
expiresInMinutes: 1440,
});
console.log('Session ID:', session.sessionId);
console.log('Link de assinatura:', `${session.url}?cs=${session.clientSecret}`);import base64
with open('procuracao-particular.pdf', 'rb') as f:
pdf_base64 = base64.b64encode(f.read()).decode()
session = client.signing_sessions.create(CreateSigningSessionRequest(
purpose='DOCUMENT_SIGNATURE',
policy=Policy(profile='BIOMETRIC_PLUS_OTP'),
signer=Signer(
name='Helena Prado',
cpf='12345678901',
email='helena@example.com',
user_external_id='cliente-0042',
),
owner=Owner(name='Almeida & Prado Advogados', email='procuracoes@escritorio.example.com'),
document=InlineDocument(content=pdf_base64, filename='procuracao-particular.pdf'),
metadata={
'tipo_documento': 'procuracao_particular',
'outorgado': 'Carlos Menezes',
'poderes': 'representacao_assembleia_2026',
'dossie': 'PROC-2026-0187',
},
return_url='https://app.escritorio.example.com/procuracoes/concluida',
locale='pt-BR',
expires_in_minutes=1440,
))
print('Session ID:', session.session_id)
print('Link de assinatura:', f'{session.url}?cs={session.client_secret}')✅ Dica —
expiresInMinutesaceita de 5 a 1440 (24 h). Para procuração, 24 h é um bom padrão: dá tempo para o cliente assinar sem deixar links válidos circulando por dias. Se expirar, crie outra sessão — leva um POST.
A resposta traz url e clientSecret (token de uso único). O link que o outorgante abre é a combinação dos dois: url + "?cs=" + clientSecret.
Você tem duas formas de entrega:
owner com e-mail diferente de signer.email, a SignDocs envia o convite para o outorgante automaticamente (a resposta traz inviteSent: true) e notifica o escritório quando a assinatura concluir.owner e envie o link montado pelo seu sistema — e-mail transacional, área do cliente, ou WhatsApp/Telegram via seus fluxos de automação (a SignDocs não envia mensagens de WhatsApp; seu sistema entrega o link pelo canal que preferir).⚠️ Não abra o link no navegador do seu backoffice — o
clientSecreté de uso único e a sessão pertence ao outorgante. Trate o link como credencial: nunca registre em logs.
Na página hospedada, o outorgante lê a procuração, aceita, passa pela prova de vida facial (com match contra o CPF informado) e confirma o código OTP. Não há app para instalar: funciona no navegador do celular.
Para produção, use webhooks (seção seguinte). Para conferência pontual ou desenvolvimento, consulte a sessão:
curl -s "$SIGNDOCS_BASE_URL/v1/signing-sessions/$SESSION_ID" \
-H "Authorization: Bearer $ACCESS_TOKEN"
# → { "status": "COMPLETED", "evidenceId": "ev_01JXYZ...", ... }Com o evidenceId em mãos, baixe os artefatos — o endpoint de downloads é público (URLs pré-assinadas de curta duração):
curl -s "$SIGNDOCS_BASE_URL/v1/verify/$EVIDENCE_ID/downloads" | jq '.downloads'
# → { "evidencePack": { "url": "...", "filename": "....p7m" },
# "finalPdf": { "url": "...", "filename": "....pdf" },
# "originalDocument": { ... } }const result = await client.signingSessions.waitForCompletion(session.sessionId);
console.log('Status:', result.status); // COMPLETED
console.log('Evidence ID:', result.evidenceId);
const dl = await fetch(
`${process.env.SIGNDOCS_BASE_URL}/v1/verify/${result.evidenceId}/downloads`,
).then(r => r.json());
// Arquive AMBOS no dossiê da procuração:
console.log('Pacote .p7m:', dl.downloads.evidencePack.url);
console.log('PDF final carimbado:', dl.downloads.finalPdf.url);import requests
result = client.signing_sessions.wait_for_completion(session.session_id)
print('Status:', result.status) # COMPLETED
print('Evidence ID:', result.evidence_id)
dl = requests.get(
f"{os.environ['SIGNDOCS_BASE_URL']}/v1/verify/{result.evidence_id}/downloads"
).json()
# Arquive AMBOS no dossiê da procuração:
print('Pacote .p7m:', dl['downloads']['evidencePack']['url'])
print('PDF final carimbado:', dl['downloads']['finalPdf']['url'])O que compõe a prova, e por que ela se sustenta sozinha:
.p7m offline com OpenSSL contra a cadeia ICP-Brasil pública: openssl cms -verify -in evidencia.p7m -CAfile icp-brasil-bundle.pem -out evidencia.json.⚠️ Sem carimbo do tempo TSA — a prova temporal vem do timestamp ISO do servidor registrado na trilha de auditoria e selado no
.p7m; a API não anexa carimbo do tempo RFC 3161/ACT ICP-Brasil. Se a contraparte exigir carimbo de tempo de ACT, trate como requisito fora do escopo deste fluxo.
Alguns destinatários — bancos em operações específicas, órgãos públicos, cartórios de registro — só aceitam documento assinado com certificado digital ICP-Brasil (e-CPF). Para esses casos, troque uma linha:
# ... mesmo payload da seção 5, mudando apenas:
# "policy": { "profile": "DIGITAL_CERTIFICATE" }O outorgante assina na mesma página hospedada, selecionando seu certificado A1; o resultado inclui a assinatura digital embutida no PDF (detectável por qualquer validador PAdES) além do pacote de evidências.
O trade-off, na prática:
BIOMETRIC_PLUS_OTP |
DIGITAL_CERTIFICATE |
|
|---|---|---|
| O que o outorgante precisa ter | Celular com câmera | Certificado ICP-Brasil (e-CPF) válido — custo anual e emissão prévia |
| Fricção para o cliente leigo | Baixa (2-3 minutos no navegador) | Alta — grande parte das pessoas físicas não possui e-CPF |
| Base de validade | MP 2.200-2/2001 art. 10 §2º (eficácia admitida pelas partes) + evidências robustas de identidade | MP 2.200-2/2001, assinatura com certificado ICP-Brasil — presunção legal de autenticidade |
| Aceitação por terceiros | Excelente entre particulares; varia em bancos e órgãos | Mais ampla — é o formato que órgãos públicos reconhecem por padrão |
| Verificação posterior | Verificador público + .p7m |
Verificador público + .p7m + assinatura PAdES embutida no PDF |
Recomendação prática: pergunte quem vai receber a procuração. Entre particulares (assembleia de condomínio ou de sócios, contabilidade, representação comercial), BIOMETRIC_PLUS_OTP maximiza conversão com prova forte. Se a contraparte já sinalizou exigência de ICP-Brasil, use DIGITAL_CERTIFICATE de saída — refazer a coleta depois custa mais que a fricção inicial. Detalhes jurídicos finos por perfil: perfis de assinatura e níveis legais.
A força da procuração eletrônica está em ser verificável por quem a recebe, sem confiar na palavra do escritório. Dois endpoints cobrem os dois cenários.
Cenário A — o outorgado (ou o juiz, ou o banco) tem o protocolo. A verificação por evidenceId é pública, sem autenticação:
curl -s "https://api.signdocs.com.br/v1/verify/$EVIDENCE_ID"
# → status, hash da evidência, perfil de política, etapas concluídas
# (CPF e e-mail retornam mascarados na consulta pública)O mesmo protocolo funciona no verificador web: https://verificador.signdocs.com.br/{evidenceId} — imprima esse link no rodapé do seu template de procuração para que qualquer portador do PDF valide na hora.
Cenário B — alguém recebeu um PDF avulso e quer saber se está assinado digitalmente. POST /v1/verify/document inspeciona o arquivo e detecta assinaturas digitais embutidas (PAdES/CAdES):
curl -s -X POST "https://api.signdocs.com.br/v1/verify/document" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"content\": \"$(base64 -w0 procuracao-recebida.pdf)\", \"filename\": \"procuracao-recebida.pdf\"}"
# → { "signed": true, "signatureCount": 1,
# "signatures": [ { "type": "pades", "confidence": 0.98, ... } ] }Limites importantes desse endpoint: ele detecta assinaturas digitais embutidas (útil para PDFs vindos de fluxos DIGITAL_CERTIFICATE, de qualquer provedor), mas não valida cadeia ICP-Brasil nem revogação, não extrai a identidade do signatário e não enxerga rubricas desenhadas ou carimbos visuais. Para procurações assinadas com perfis eletrônicos (biometria/OTP), a verificação canônica é sempre o Cenário A — o evidenceId. O PDF é inspecionado em memória e descartado. Requer scope verification:write, credenciais de produção (HML recebe 403) e consome cota verification por chamada.
Em vez de polling, registre um webhook uma única vez e deixe a SignDocs avisar seu sistema:
curl -s -X POST "$SIGNDOCS_BASE_URL/v1/webhooks" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"url": "https://app.escritorio.example.com/webhooks/signdocs",
"events": ["SIGNING_SESSION.COMPLETED", "SIGNING_SESSION.EXPIRED"]
}'
# → 201 { "webhookId": "...", "secret": "whsec_..." } (o secret só aparece aqui)Eventos relevantes para este cenário:
| Evento | Quando | Ação sugerida |
|---|---|---|
SIGNING_SESSION.COMPLETED |
Outorgante concluiu todas as etapas | Baixar .p7m + PDF final, arquivar no dossiê (metadata.dossie vem no payload), notificar o outorgado |
SIGNING_SESSION.EXPIRED |
Link expirou sem assinatura | Criar nova sessão e reenviar o link ao cliente |
Todo payload chega assinado com HMAC-SHA256 (headers X-SignDocs-Signature + X-SignDocs-Timestamp) — valide a assinatura antes de processar. Especificação completa, reentrega e exemplos de handler: guia de webhooks.
| Perfil | Garantia de identidade | Quando usar em procuração |
|---|---|---|
CLICK_PLUS_OTP |
Posse do e-mail/telefone | Procurações internas de baixíssimo risco; frágil se a outorga for contestada |
BIOMETRIC |
Prova de vida + match facial pelo CPF | Bom equilíbrio quando o e-mail do cliente não é confiável |
BIOMETRIC_PLUS_OTP |
Biometria facial e posse do canal | Recomendado — dois fatores independentes; é o perfil deste guia |
DIGITAL_CERTIFICATE |
Certificado ICP-Brasil do outorgante | Quando a contraparte exige ICP-Brasil (seção 8) |
O default recomendado é BIOMETRIC_PLUS_OTP: procuração é outorga de poderes, e o cenário de contestação típico é "não fui eu que assinei" — biometria facial atrelada ao CPF mais OTP tornam essa alegação difícil de sustentar diante do pacote de evidências. CLICK_ONLY não aparece na tabela de propósito: para este documento, não use. Comparativo completo dos níveis legais: perfis de assinatura.
Para escritórios que usam agentes de IA no dia a dia, o servidor MCP da SignDocs Brasil expõe a API como ferramentas no Claude (Desktop, Code ou claude.ai). O fluxo vira uma conversa:
create_signing_session (com sua confirmação antes de executar — a ação consome cota e gera efeito jurídico) e devolve o link de assinatura pronto para encaminhar..p7m.Solicite o acesso ao servidor MCP pelo painel admin. Se o escritório usa automação visual, os mesmos passos deste guia existem como módulos prontos no n8n, Make e Zapier.
422 — CPF ausente com perfil biométrico. BIOMETRIC_PLUS_OTP exige signer.cpf (11 dígitos, sem pontuação):
{ "type": "https://docs.signdocs.com.br/errors#validation",
"title": "Unprocessable Entity", "status": 422,
"detail": "signer.cpf is required for policy profile BIOMETRIC_PLUS_OTP" }Correção: inclua o CPF do outorgante — é ele que ancora o match biométrico.
422 — canal de OTP sem destino. A etapa OTP precisa de signer.email, ou de signer.phone (E.164) com otpChannel: "sms". Correção: informe pelo menos um canal válido; para deixar o outorgante escolher na hora, envie ambos com otpChannelSelectable: true.
401 — token expirado.
{ "type": "https://docs.signdocs.com.br/errors#unauthorized",
"title": "Unauthorized", "status": 401,
"detail": "Access token is invalid or expired" }Correção: renove via POST /oauth2/token. Não reutilize tokens além do expires_in.
403 — POST /v1/verify/document com credenciais HML. Esse endpoint só aceita credenciais de produção com scope verification:write. Correção: teste a detecção em produção; em HML, valide o restante do fluxo e use GET /v1/verify/{evidenceId} (público, funciona nos dois ambientes).
Sessão expirada antes da assinatura. O outorgante clicou no link depois de expiresInMinutes (máximo 1440). Não há "reativar": trate o webhook SIGNING_SESSION.EXPIRED criando uma nova sessão e reenviando o link — o documento e os metadados são os mesmos, muda só o POST.
Sim. O Código Civil admite o mandato por instrumento particular, e a MP 2.200-2/2001 (art. 10, §2º) reconhece assinaturas eletrônicas não-ICP quando admitidas pelas partes como válidas. O pacote de evidências com biometria, OTP, hash do documento e trilha de auditoria assinada com certificado ICP-Brasil dá o lastro probatório. Para os detalhes por perfil, veja níveis legais.
Entre particulares, quando a lei não exige forma especial, o reconhecimento de firma não é requisito de validade do instrumento particular — e a verificação pública do evidenceId cumpre papel semelhante ao de conferir a autoria. Porém, terceiros podem exigir firma reconhecida ou procuração pública por política própria (bancos e alguns órgãos fazem isso). Confirme com o destinatário antes.
Quando o ato a ser praticado exigir instrumento público — por exemplo, alienação de imóveis por escritura pública — a procuração acompanha a forma do ato. Esses casos ficam fora deste fluxo: procure um tabelionato de notas. Este guia cobre procurações particulares, como representação em assembleia, perante a contabilidade e representação comercial.
Com biometria (BIOMETRIC_PLUS_OTP), o outorgante prova identidade na hora — prova de vida facial vinculada ao CPF mais código OTP — sem precisar possuir certificado digital. Com ICP-Brasil (DIGITAL_CERTIFICATE), o outorgante assina com o e-CPF que já possui, formato com presunção legal de autenticidade e aceitação mais ampla em órgãos públicos. A seção 8 detalha o trade-off; na dúvida, decida por quem vai receber a procuração.
De três formas independentes: consultando o protocolo no verificador público (https://verificador.signdocs.com.br/{evidenceId} ou GET /v1/verify/{evidenceId}, sem autenticação); validando o pacote .p7m offline com OpenSSL contra a cadeia ICP-Brasil; e — se o perfil foi DIGITAL_CERTIFICATE — abrindo o PDF em qualquer validador PAdES. Nenhuma das três depende de confiar no escritório que emitiu.
Sim, trocando a sessão única por um envelope multi-signatário (POST /v1/envelopes com totalSigners: 2 e uma sessão por outorgante) — cada um assina com seu próprio fluxo de biometria + OTP e o PDF final consolida as assinaturas. Veja envelopes de assinatura expressa.