Integração · Python
Assinatura eletrônica em Python
A API REST funciona com qualquer cliente HTTP. Os exemplos usam requests e a biblioteca padrão hmac para o webhook.
curl -X POST /v1/signature-requests
201 Created · 312 ms
"status": "SENT", "signingUrl": "…/s/9xq4m"
webhook signer.signed → 200 OK
Antes de tudo: a chave fica no servidor
Onde fica a chave: Leia ASSINAPI_SECRET_KEY de os.environ no servidor (Django settings, FastAPI dependencies). Nunca no código-fonte.
Como funciona
- 1
Seu backend (Django/FastAPI/Flask) cria o envelope com requests.
- 2
Anexa o PDF, adiciona os signatários e envia.
- 3
O signatário assina pelo link.
- 4
O endpoint de webhook valida o HMAC com hmac.compare_digest.
- 5
O backend atualiza o status e baixa o PDF assinado.
Código pronto
Criar envelope
import os, uuid, requests
res = requests.post("https://api.assinapi.com.br/v1/envelopes", headers={"Authorization": f"Bearer {os.environ['ASSINAPI_SECRET_KEY']}", "Idempotency-Key": str(uuid.uuid4())}, json={"title":"Contrato de prestação de serviços","expirationDays":7}, timeout=30)
data = res.json()
if not res.ok:
raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data)Validar webhook
import hmac, hashlib, os, time
def verify_assinapi_webhook(raw_body: bytes, headers) -> bool:
signature = headers.get("X-Signature", "")
event_id = headers.get("X-Event-Id", "")
timestamp = int(headers.get("X-Timestamp", "0"))
if abs(time.time() - timestamp) > 300:
return False
message = f"{event_id}.{timestamp}.".encode() + raw_body
expected = "v1=" + hmac.new(os.environ["ASSINAPI_WEBHOOK_SECRET"].encode(), message, hashlib.sha256).hexdigest()
return hmac.compare_digest(signature, expected)Exemplos apontam para o Sandbox (https://api.assinapi.com.br/v1). Em Produção, troque apenas a chave (ask_live_…); o endereço é o mesmo.
Perguntas frequentes
Perguntas técnicas.
Existe SDK Python?
Ainda não — está planejado. A API REST e os exemplos acima cobrem o fluxo completo, e o OpenAPI permite gerar um cliente.
Como meu sistema fica sabendo que o documento foi assinado?
Por webhooks assinados com HMAC-SHA256 (eventos como signer.signed e envelope.completed) ou consultando GET /v1/signature-requests/:id, que devolve o status e o próximo passo em português.
Como o signatário se autentica? Dá para usar WhatsApp?
WhatsApp está nos planos pagos. Simples: por padrão só o link por e-mail (EMAIL_LINK). Avançada (CPF e data de nascimento conferidos): nos planos pagos, link por e-mail + código pelo WhatsApp (WHATSAPP_OTP) ou só WhatsApp (WHATSAPP_LINK); no Free, link e código por e-mail (EMAIL_OTP), e pedir WhatsApp devolve 402 WHATSAPP_REQUIRES_PAID_PLAN. Envie o celular em phone (+5511999999999) e, se quiser, defina o padrão no projeto.
Consigo testar sem custo?
Sim. O Sandbox é gratuito: chaves ask_test_…, código de confirmação fixo 123456 e CPFs de teste. Documentos de Sandbox não têm validade e não consomem a franquia do plano.
Primeira assinatura no Sandbox em menos de 10 minutos.
Sem cartão de crédito. Sandbox gratuito; você só paga por documentos enviados em Produção.