Fluxo de uma operação
O ciclo de vida de uma assinatura eletrônica, do upload ao download.
Antes de mergulhar em endpoint por endpoint, entenda o arco completo de uma operação. Toda integração com a ForSign segue essencialmente esse fluxo.
Resumo em sequência
Os webhooks são assíncronos — chegam em segundos a minutos depois do evento,
não na resposta da chamada original. Para baixar os PDFs finalizados, espere
o evento DocumentReady.
Detalhamento por passo
Obter a chave de API
No painel da ForSign, vá em Configurações > Desenvolvedor e gere uma
X-Api-Key. Guarde com cuidado — ela autentica todas as suas requisições.
Upload do documento
Suba o PDF que será assinado. A API retorna um id (UUID) que você vai
referenciar no próximo passo. Você pode subir múltiplos arquivos antes de criar
a operação.
curl -X POST "https://api.forsign.digital/api/v2/document/upload" \
-H "X-Api-Key: $FORSIGN_API_KEY" \
-F "[email protected]"
# → { "id": "d25058de-259a-4543-98f0-e1c4fb52ba0e" }Síncrono. Resposta em poucos segundos. Detalhes →
Criar a operação
Combine documentos, assinantes, ordem de assinatura, canais de notificação e
regras de finalização numa única requisição. Você recebe o id da operação
(número sequencial por conta) pra rastrear tudo depois.
curl -X POST "https://api.forsign.digital/api/v1/operation" \
-H "X-Api-Key: $FORSIGN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Contrato",
"files": [{ "id": "d25058de-...", "description": "contrato.pdf" }],
"members": [{ "name": "...", "email": "...", "signatures": [...] }]
}'Síncrono. A operação fica pronta para receber assinaturas assim que retorna. POST /api/v1/operation →
Processo dos assinantes
Os assinantes recebem o convite pelo canal definido (email, WhatsApp, SMS), preenchem formulários (se houver), enviam anexos solicitados e assinam o documento. Esse fluxo acontece no portal da ForSign — você não precisa fazer nada.
Assíncrono. Dura de minutos a dias, dependendo do assinante.
Gerenciar anexos (opcional)
Se a operação solicita anexos (RG, comprovante etc.), use os endpoints de anexo
para aprovar, rejeitar ou baixar os arquivos enviados — você pode reagir em
tempo real via webhook AttachmentFilled.
Receber eventos via Webhook (opcional)
Em vez de fazer polling, configure um webhook para ser notificado quando alguém
assina (DocumentSigned), quando todos terminaram (CompletedOperation),
quando o ZIP final está pronto (DocumentReady) ou quando um formulário é
preenchido (FormFilled).
Finalizar a operação
A finalização pode ser automática (assim que o último assinante assina) ou
manual (você chama o endpoint de conclusão quando quiser) — definido na
criação via manualFinish.hasManualFinish.
# Concluir uma operação em modo manual (todos os assinantes já assinaram)
curl -X POST "https://api.forsign.digital/api/v2/operation/{id}/complete" \
-H "X-Api-Key: $FORSIGN_API_KEY"Download dos documentos
Com a operação finalizada, baixe todos os documentos assinados num ZIP único,
ou um documento específico em Base64. Espere o webhook DocumentReady antes
de baixar — CompletedOperation dispara antes do PDF final estar selado.
curl -X GET "https://api.forsign.digital/api/v2/operation/{id}/download-arquivos" \
-H "X-Api-Key: $FORSIGN_API_KEY" \
-o assinados.zipQuer um atalho? Baixe a Postman Collection —
os 13 endpoints já vêm com X-Api-Key configurada via variável de coleção.
Síncrono vs assíncrono
| Passo | Modo | Latência típica |
|---|---|---|
| Upload do documento | Síncrono | < 1s |
| Criar operação | Síncrono | < 1s |
| Notificação ao assinante | Assíncrono (em background) | segundos |
| Assinatura | Assíncrono (humano) | minutos a dias |
Webhook DocumentSigned | Assíncrono | segundos após assinar |
Webhook CompletedOperation | Assíncrono | segundos após o último assinar |
Webhook DocumentReady | Assíncrono | segundos após CompletedOperation |
| Forçar conclusão | Síncrono | < 1s |
| Download ZIP | Síncrono | depende do tamanho |
Versões: quando v1, quando v2
A maioria dos endpoints novos está em /api/v2/. A criação de operação ainda
vive em /api/v1/operation por compatibilidade — esse endpoint é o mais complexo
e ainda não foi migrado. Sempre confira a URL na página do endpoint.