API de Sessões de Assinatura

Crie, gerencie e acompanhe sessões de assinatura eletrônica para perguntas de contrato.

A API de Sessões de Assinatura permite criar e gerenciar programaticamente sessões de assinatura para perguntas de contrato. Você pode criar sessões, acompanhar o progresso das assinaturas, reenviar requisições, anular sessões e baixar documentos assinados.

Todos os corpos de requisição e resposta usam nomes de campos em snake_case.

Endpoints

POST/api/v1/forms/:id/signing-sessionsGET/api/v1/forms/:id/signing-sessionsGET/api/v1/signing-sessions/:sessionIdPOST/api/v1/signing-sessions/:sessionId/voidPOST/api/v1/signing-sessions/:sessionId/resend/:slotNumberGET/api/v1/signing-sessions/:sessionId/documentsGET/api/v1/signing-sessions/:sessionId/documents/:docIdGET/api/v1/signing-sessions/:sessionId/auditGET/api/v1/s/:shortCodePOST/api/v1/s/:shortCode/verify-password

Criar sessão

POST/api/v1/forms/:id/signing-sessions

Cria uma nova sessão de assinatura para um formulário que contém uma ou mais perguntas de contrato. Retorna a sessão com links de assinatura exclusivos para cada slot de signatário.

Parâmetros de caminho

idstring

O ID do formulário

Corpo da requisição

signersarray

Array de configurações de signatários, uma por slot. Cada objeto pode incluir slot_number (inteiro), first_name (string), last_name (string) e email (string). Todos os campos, exceto slot_number, são opcionais.

signing_orderstring

"sequential" ou "any". O padrão é a ordem de assinatura padrão da pergunta.

expiry_daysinteger

Número de dias até a sessão expirar. Padrão: 30.

passwordstring

Senha para proteger os links de assinatura.

hide_other_signersboolean

Oculta os campos preenchidos dos outros signatários. Padrão: false.

require_email_verificationboolean

Exige verificação de e-mail antes da assinatura. Padrão: false.

copy_modestring

"ask", "always" ou "disabled". Padrão: "ask".

notify_emailsarray

Array de endereços de e-mail que receberão notificações de status.

notify_eventsarray

Array de tipos de evento: "each_signature", "all_complete", "decline", "expiry".

send_signing_emailsboolean

Envia e-mails de requisição de assinatura para os signatários que têm endereço de e-mail. Padrão: false.

custom_email_bodystring

Modelo de e-mail personalizado. Suporta variáveis: {slot_firstName}, {slot_lastName}, {slot_link}, {expiryDate}.

Resposta

json

{
  "id": "ses_abc123def456",
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "status": "active",
  "signing_order": "sequential",
  "total_slots": 2,
  "total_signed": 0,
  "expires_at": "2026-04-25T00:00:00.000Z",
  "hide_other_signers": false,
  "copy_mode": "ask",
  "signer_links": [
    {
      "slot_number": 1,
      "slot_label": "Buyer",
      "short_code": "xK9f2",
      "signing_url": "https://nue.fm/s/xK9f2",
      "first_name": "John",
      "last_name": "Smith",
      "email": "john@example.com",
      "status": "pending"
    },
    {
      "slot_number": 2,
      "slot_label": "Seller",
      "short_code": "mP3a7",
      "signing_url": "https://nue.fm/s/mP3a7",
      "first_name": null,
      "last_name": null,
      "email": null,
      "status": "pending"
    }
  ],
  "created_at": "2026-03-26T10:00:00.000Z"
}

Exemplos de código

bash

curl -X POST "https://api.nueform.io/api/v1/forms/FORM_ID/signing-sessions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signers": [
      {"slot_number": 1, "first_name": "John", "last_name": "Smith", "email": "john@example.com"},
      {"slot_number": 2, "first_name": "Jane", "last_name": "Doe"}
    ],
    "signing_order": "sequential",
    "expiry_days": 30,
    "send_signing_emails": true
  }'

Listar sessões

GET/api/v1/forms/:id/signing-sessions

Retorna todas as sessões de assinatura de um formulário.

Parâmetros de consulta

statusstring

Filtra por status: "active", "fully_signed", "declined", "voided", "expired".

pageinteger

Número da página (padrão: 1)

per_pageinteger

Resultados por página (padrão: 20)

Resposta

json

{
  "sessions": [
    {
      "id": "ses_abc123def456",
      "status": "active",
      "total_slots": 2,
      "total_signed": 1,
      "signing_order": "sequential",
      "expires_at": "2026-04-25T00:00:00.000Z",
      "created_at": "2026-03-26T10:00:00.000Z"
    }
  ],
  "total": 5,
  "page": 1,
  "per_page": 20
}

Exemplos de código

bash

curl -X GET "https://api.nueform.io/api/v1/forms/FORM_ID/signing-sessions?status=active" \
  -H "Authorization: Bearer YOUR_API_KEY"

Obter sessão

GET/api/v1/signing-sessions/:sessionId

Retorna uma única sessão de assinatura com todos os detalhes, incluindo os links dos signatários e seus status.

Resposta

Retorna o mesmo objeto de sessão do endpoint de criação, com status e carimbos de data/hora atualizados para cada link de signatário.

Exemplos de código

bash

curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456" \
  -H "Authorization: Bearer YOUR_API_KEY"

Anular sessão

POST/api/v1/signing-sessions/:sessionId/void

Anula uma sessão de assinatura ativa. Todos os links de assinatura pendentes são invalidados. As partes que já assinaram são notificadas e os PDFs recebem a marca d'água "VOIDED".

Corpo da requisição

reasonstring

Motivo da anulação da sessão.

Resposta

json

{
  "id": "ses_abc123def456",
  "status": "voided",
  "voided_at": "2026-03-27T15:30:00.000Z",
  "void_reason": "Terms changed, new agreement required"
}

Exemplos de código

bash

curl -X POST "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/void" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Terms changed, new agreement required"}'

Reenviar requisição de assinatura

POST/api/v1/signing-sessions/:sessionId/resend/:slotNumber

Reenvia o e-mail de requisição de assinatura para um signatário específico. O signatário deve ter um endereço de e-mail configurado.

Resposta

json

{
  "success": true,
  "sent_to": "john@example.com",
  "slot_number": 1
}

Exemplos de código

bash

curl -X POST "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/resend/1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Listar documentos assinados

GET/api/v1/signing-sessions/:sessionId/documents

Retorna uma lista de documentos assinados de uma sessão concluída. Cada documento corresponde a uma pergunta de contrato do formulário.

Resposta

json

{
  "documents": [
    {
      "id": "doc_xyz789",
      "question_id": "q_abc123",
      "question_title": "Service Agreement",
      "document_url": "https://storage.nueform.io/signed/doc_xyz789.pdf",
      "document_hash": "sha256:a1b2c3d4e5f6...",
      "generated_at": "2026-03-28T12:00:00.000Z"
    }
  ]
}

Exemplos de código

bash

curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/documents" \
  -H "Authorization: Bearer YOUR_API_KEY"

Obter documento assinado

GET/api/v1/signing-sessions/:sessionId/documents/:docId

Baixa um documento assinado específico como arquivo PDF.

Resposta

Retorna o arquivo PDF com Content-Type: application/pdf.

Exemplos de código

bash

curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123/documents/doc_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o signed-document.pdf

Obter trilha de auditoria

GET/api/v1/signing-sessions/:sessionId/audit

Retorna a trilha de auditoria completa de uma sessão de assinatura, incluindo eventos de visualização, assinaturas, recusas e eventos do sistema.

Resposta

json

{
  "entries": [
    {
      "id": "aud_001",
      "action": "session_created",
      "timestamp": "2026-03-26T10:00:00.000Z",
      "actor_email": "owner@company.com",
      "ip_address": "192.168.1.1",
      "user_agent": "Chrome 120 / macOS"
    },
    {
      "id": "aud_002",
      "action": "document_viewed",
      "slot_number": 1,
      "actor_email": "john@example.com",
      "timestamp": "2026-03-26T15:44:00.000Z",
      "ip_address": "10.0.0.1",
      "user_agent": "Chrome 120 / macOS"
    },
    {
      "id": "aud_003",
      "action": "signed",
      "slot_number": 1,
      "actor_name": "John Smith",
      "actor_email": "john@example.com",
      "timestamp": "2026-03-26T15:45:00.000Z",
      "ip_address": "10.0.0.1",
      "user_agent": "Chrome 120 / macOS"
    }
  ]
}

Exemplos de código

bash

curl -X GET "https://api.nueform.io/api/v1/signing-sessions/ses_abc123def456/audit" \
  -H "Authorization: Bearer YOUR_API_KEY"

Resolver código curto

GET/api/v1/s/:shortCode

Endpoint público (não requer autenticação). Resolve um código curto de assinatura para o contexto de formulário e sessão necessário para renderizar a experiência de assinatura.

Resposta

json

{
  "form_id": "665a1b2c3d4e5f6a7b8c9d0e",
  "session_id": "ses_abc123def456",
  "slot_number": 1,
  "slot_label": "Buyer",
  "status": "pending",
  "requires_password": true,
  "requires_email_verification": false,
  "signing_order": "sequential",
  "is_turn": true
}

Exemplos de código

bash

curl -X GET "https://api.nueform.io/api/v1/s/xK9f2"

Verificar senha

POST/api/v1/s/:shortCode/verify-password

Endpoint público. Verifica a senha de uma sessão de assinatura protegida por senha. Retorna um token de acesso temporário em caso de sucesso.

Corpo da requisição

passwordstring

A senha da sessão.

Resposta

json

{
  "success": true,
  "access_token": "tmp_abc123..."
}

Resposta de erro (401)

json

{
  "error": "Invalid password"
}

Exemplos de código

bash

curl -X POST "https://api.nueform.io/api/v1/s/xK9f2/verify-password" \
  -H "Content-Type: application/json" \
  -d '{"password": "mySecretPass123"}'

Última atualização: 20 de julho de 2026