NueForm

API de Sesiones de Firma

Crea, gestiona y rastrea sesiones de firma electrónica para preguntas de contrato.

La API de Sesiones de Firma te permite crear y gestionar programáticamente sesiones de firma para preguntas de contrato. Puedes crear sesiones, rastrear el progreso de firma, reenviar solicitudes, anular sesiones y descargar documentos firmados.

Todos los cuerpos de solicitud y respuesta utilizan nombres de campo en 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

Crear Sesión

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

Crea una nueva sesión de firma para un formulario que contiene una o más preguntas de contrato. Devuelve la sesión con enlaces de firma únicos para cada slot de firmante.

Parámetros de Ruta

idstring

El ID del formulario

Cuerpo de Solicitud

signersarray

Arreglo de configuraciones de firmantes, una por slot. Cada objeto puede incluir slot_number (entero), first_name (cadena), last_name (cadena) y email (cadena). Todos los campos excepto slot_number son opcionales.

signing_orderstring

"sequential" o "any". Por defecto usa el orden de firma predeterminado de la pregunta.

expiry_daysinteger

Número de días antes de que la sesión expire. Predeterminado: 30.

passwordstring

Contraseña para proteger los enlaces de firma.

hide_other_signersboolean

Oculta los campos completados por otros firmantes. Predeterminado: false.

require_email_verificationboolean

Exige verificación de correo antes de firmar. Predeterminado: false.

copy_modestring

"ask", "always" o "disabled". Predeterminado: "ask".

notify_emailsarray

Arreglo de direcciones de correo que recibirán notificaciones de estado.

notify_eventsarray

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

send_signing_emailsboolean

Envía correos de solicitud de firma a los firmantes que tengan dirección de correo. Predeterminado: false.

custom_email_bodystring

Plantilla de correo personalizada. Soporta variables: {slot_firstName}, {slot_lastName}, {slot_link}, {expiryDate}.

Respuesta

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"
}

Ejemplos 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 Sesiones

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

Devuelve todas las sesiones de firma de un formulario.

Parámetros de Consulta

statusstring

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

pageinteger

Número de página (predeterminado: 1)

per_pageinteger

Resultados por página (predeterminado: 20)

Respuesta

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
}

Ejemplos 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"

Obtener Sesión

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

Devuelve una sola sesión de firma con todos los detalles, incluidos los enlaces de firmantes y sus estados.

Respuesta

Devuelve el mismo objeto de sesión que el endpoint de creación, con estados y marcas de tiempo actualizados para cada enlace de firmante.

Ejemplos de Código

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

Anular Sesión

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

Anula una sesión de firma activa. Todos los enlaces de firma pendientes quedan invalidados. Se notifica a las partes que ya firmaron y los PDF reciben la marca de agua "VOIDED".

Cuerpo de Solicitud

reasonstring

Motivo de la anulación de la sesión.

Respuesta

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

Ejemplos 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 Solicitud de Firma

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

Reenvía el correo de solicitud de firma a un firmante específico. El firmante debe tener una dirección de correo configurada.

Respuesta

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

Ejemplos 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 Firmados

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

Devuelve la lista de documentos firmados de una sesión completada. Cada documento corresponde a una pregunta de contrato del formulario.

Respuesta

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"
    }
  ]
}

Ejemplos de Código

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

Obtener Documento Firmado

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

Descarga un documento firmado específico como archivo PDF.

Respuesta

Devuelve el archivo PDF con Content-Type: application/pdf.

Ejemplos 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

Obtener Pista de Auditoría

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

Devuelve la pista de auditoría completa de una sesión de firma, incluidos eventos de visualización, firmas, rechazos y eventos del sistema.

Respuesta

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"
    }
  ]
}

Ejemplos 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 Corto

GET/api/v1/s/:shortCode

Endpoint público (no requiere autenticación). Resuelve un código corto de firma al contexto de formulario y sesión necesario para renderizar la experiencia de firma.

Respuesta

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
}

Ejemplos de Código

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

Verificar Contraseña

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

Endpoint público. Verifica la contraseña de una sesión de firma protegida con contraseña. Devuelve un token de acceso temporal si es correcta.

Cuerpo de Solicitud

passwordstring

La contraseña de la sesión.

Respuesta

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

Respuesta de Error (401)

json
{
  "error": "Invalid password"
}

Ejemplos 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"}'
Ultima actualizacion: 24 de agosto de 2026