prof-ramos Assinafy API
Assinafy é uma plataforma de assinatura digital com API REST.
Antes de implementar
- Identifique a tarefa (upload, assignment, webhook, template, etc.)
- Leia o arquivo de doc local indicado no Decision Tree abaixo
- Se for código, leia também
references/integration-patterns.md - Confirme o ambiente (sandbox em dev, produção só quando o usuário pedir)
Fonte primária: assinafy/assinafy-api-docs/. Consulte https://api.assinafy.com.br/v1/docs apenas se a doc local não cobrir o caso.
Regras importantes
| Regra | Por quê |
|---|---|
Use sandbox (https://sandbox.assinafy.com.br/v1) em desenvolvimento |
Evita cobranças e afeta documentos reais |
| API Key só no backend | Chave exposta no frontend permite abuso da conta |
Header X-Api-Key (ou Bearer token) |
Forma documentada de autenticação server-side |
Trate status no body e HTTP status |
A API retorna erros em ambos os níveis |
Upload via multipart, campo file |
Endpoint de upload não aceita JSON com base64 |
virtual = sem campos; collect = com field definitions |
Escolha errada quebra o fluxo de assinatura |
| Webhook: validar secret, responder 200, processar idempotente | Retries do provedor reenviam o mesmo evento |
Variáveis de ambiente padrão: ASSINAFY_API_KEY, ASSINAFY_ACCOUNT_ID, ASSINAFY_BASE_URL, ASSINAFY_WEBHOOK_SECRET. Detalhes em references/integration-patterns.md.
Decision Tree — qual doc ler
| Tarefa | Arquivo |
|---|---|
| Primeira integração | assinafy/assinafy-api-docs/README.md, quick-start.md |
| Autenticação / API keys | authentication.md |
| Documentos (upload, download, status) | documents.md + schemas/document.md |
| Signatários | signers.md + schemas/signer.md |
| Solicitar assinatura | assignments.md + schemas/assignment.md |
| Campos no PDF (collect) | field-definitions.md |
| Templates | templates.md |
| Tags | tags.md |
| Fluxo do signatário | signer-documents.md |
| Webhooks | webhooks.md + references/webhook-events.md |
| Paginação, erros, ambientes | basics.md |
| Padrões de código | references/integration-patterns.md |
Todos os caminhos são relativos a assinafy/assinafy-api-docs/ exceto references/.
Fluxo típico
Credenciais → Upload PDF → Criar signers → Assignment → Webhooks → Download certificated
Exemplo — assignment virtual:
{
"method": "virtual",
"signerIds": ["<signer_id>"],
"expires_at": "2026-12-31T23:59:59Z",
"message": "Por favor, assine o documento."
}
Para collect, leia assignments.md seção "Create with Input" antes de implementar.
Referências externas
- Coleção Postman: https://www.postman.com/devassinafy/dev-assinafy-s-workspace/collection/tqqxlsd/assinafy-api-collection
- Códigos de erro HTTP:
assinafy/assinafy-api-docs/basics.md