Kuenta Docs

Appearance

Crear sobre de documentos​

POST
/envelope

Crea un nuevo sobre de documentos que agrupa múltiples documentos para ser firmados por uno o más destinatarios. Los sobres permiten gestionar workflows complejos de firma con secuencias específicas, validaciones personalizadas y seguimiento detallado del progreso.

Uso

Los sobres son contenedores para documentos que necesitan ser firmados o revisados por múltiples participantes. Este endpoint permite crear un sobre configurando destinatarios, documentos y flujos de firma.

Flujo típico

  1. Crear el sobre con documentos iniciales y destinatarios
  2. Configurar los métodos de firma requeridos
  3. Enviar notificaciones a los destinatarios
  4. Seguimiento del proceso de firma

Permisos requeridos

  • WriteEnvelope: Creación de sobres

Authorizations​

bearerAuth

JWT token de autenticación. Utilice este esquema para autenticar solicitudes con un token JWT.

TypeHTTP (bearer)

Request Body​

application/json
JSON
{
"title": "Documentos de Crédito Hipotecario - Juan Pérez",
"description": "Documentos requeridos para la aprobación del crédito hipotecario por $250,000,000 COP",
"priority": "string",
"documents": [
{
"documentId": "123e4567-e89b-12d3-a456-426614174000",
"documentName": "Contrato de Crédito Hipotecario",
"documentType": "string",
"documentOrder": 1,
"signatureFields": [
{
"fieldId": "sig_field_primary_debtor_1",
"fieldName": "Firma del Deudor Principal",
"recipientRole": "primary_debtor",
"pageNumber": 5,
"coordinates": {
"x": 150.5,
"y": 650.3,
"width": 200,
"height": 60
},
"required": true,
"signatureType": "string",
"validationRules": {
"requireOTP": true,
"requireBiometric": false,
"minimumQualityScore": 85
}
}
],
"additionalFields": [
{
"fieldId": "date_field_1",
"fieldType": "string",
"fieldName": "Fecha de Firma",
"recipientRole": "primary_debtor",
"pageNumber": 5,
"coordinates": {
"x": 400,
"y": 650.3,
"width": 150,
"height": 30
},
"required": true,
"defaultValue": "{current_date}"
}
]
}
],
"recipients": [
{
"recipientName": "Juan Carlos Pérez García",
"recipientEmail": "[email protected]",
"recipientPhone": "+573001234567",
"role": "primary_debtor",
"documentType": "string",
"documentNumber": "12345678",
"signingOrder": 1,
"language": "string",
"notificationPreferences": {
"sendEmailInvitation": true,
"sendSMSInvitation": true,
"sendReminders": true,
"reminderFrequency": "string"
},
"accessRestrictions": {
"allowedIPs": [
[
"192.168.1.0/24",
"10.0.0.100"
]
],
"deviceRestriction": false,
"timeRestriction": {
"allowedHours": {
"start": "08:00",
"end": "18:00"
},
"timezone": "America/Bogota"
}
},
"personalMessage": "Estimado Juan, por favor firme los documentos de su crédito hipotecario"
}
],
"workflowSettings": {
"workflowType": "string",
"autoSend": true,
"allowDelegation": false,
"requireAllSignatures": true,
"expirationDays": 15,
"reminderSettings": {
"enableReminders": true,
"firstReminderAfterHours": 24,
"reminderIntervalHours": 48,
"maxReminders": 5
}
},
"securitySettings": {
"encryptionLevel": "string",
"auditTrailLevel": "string",
"requireMFA": true,
"allowDownload": true,
"watermarkDocuments": true,
"complianceLevel": "string"
},
"webhookSettings": {
"webhookUrl": "https://api.cliente.com/webhook/envelope-events",
"enabledEvents": [
[
"envelope_sent",
"document_signed",
"envelope_completed"
]
],
"secretKey": "webhook_secret_123456",
"retrySettings": {
"maxRetries": 3,
"retryIntervalSeconds": 60
}
},
"metadata": {
"businessContext": "Proceso de aprobación de crédito hipotecario",
"customerReference": "CRED-HIP-2024-001",
"loanAmount": 250000000,
"loanPurpose": "Compra de vivienda VIS",
"tags": [
[
"hipotecario",
"vis",
"urgente",
"cliente_premium"
]
],
"customFields": {
"additionalProperties": "string"
}
}
}

Responses​

Sobre creado exitosamente
application/json
JSON
{
"success": true,
"message": "Sobre de documentos creado exitosamente",
"data": {
"envelopeId": "123e4567-e89b-12d3-a456-426614174000",
"title": "Documentos de Crédito Hipotecario - Juan Pérez",
"status": "string",
"documentsInfo": {
"totalDocuments": 3,
"totalSignatureFields": 6,
"documentsProcessed": [
{
"documentId": "123e4567-e89b-12d3-a456-426614174000",
"documentName": "Contrato de Crédito Hipotecario",
"status": "processed",
"signatureFieldsCount": 2
}
]
},
"recipientsInfo": {
"totalRecipients": 2,
"recipientsProcessed": [
{
"recipientId": "456b7890-c123-45d6-e789-012345678901",
"recipientName": "Juan Carlos Pérez García",
"recipientEmail": "[email protected]",
"role": "primary_debtor",
"status": "string",
"signingUrl": "https://signatures.kuenta.co/sign/env-123e4567-e89b-12d3-a456-426614174000/rec-456b7890-c123-45d6-e789-012345678901",
"notificationsSent": [
{
"method": "email",
"status": "sent",
"sentAt": "2024-01-15T16:30:00Z"
}
]
}
]
},
"workflowInfo": {
"workflowType": "sequential",
"currentStage": "awaiting_primary_debtor",
"nextAction": "Esperando firma del deudor principal",
"estimatedCompletion": "2024-01-17T18:00:00Z"
},
"securityInfo": {
"encryptionApplied": "AES-256",
"auditTrailEnabled": true,
"complianceLevel": "ESIGN_ACT_COMPLIANT",
"certificateInfo": "SSL Certificate válido hasta 2025-12-31"
},
"timestamps": {
"createdAt": "2024-01-15T16:30:00Z",
"sentAt": "2024-01-15T16:30:30Z",
"expiresAt": "2024-01-30T16:30:00Z"
},
"urls": {
"envelopeDetailsUrl": "https://api.kuenta.co/envelope/env-123e4567-e89b-12d3-a456-426614174000",
"auditTrailUrl": "https://api.kuenta.co/envelope/env-123e4567-e89b-12d3-a456-426614174000/audit-trail",
"manageEnvelopeUrl": "https://portal.kuenta.co/envelope/env-123e4567-e89b-12d3-a456-426614174000"
}
}
}

Playground​

Server
Authorization
Body

Samples​

Powered by VitePress OpenAPI