athento.com

Integración con Uanataca Signbox: operación de firma electrónica

Tabla de contenidos

Integración con Uanataca Signbox: operación de firma electrónica

Descripción

La operación op_signbox_sign permite firmar electrónicamente documentos almacenados en Athento enviándolos al Uanataca Signbox Optimizer mediante su API REST. Una vez firmado, el documento se guarda de vuelta en Athento reemplazando el binario original y generando una versión anterior automáticamente.

La integración usa el modo síncrono (useasync=false): Athento espera la respuesta firmada en la misma llamada, sin necesidad de configurar webhooks ni endpoints de callback.

Archivos

  • athentose/file/foperations/op_signbox_sign.py — operación
  • athentose/settings_config/third_party/settings_signbox.py — configuración Django

Configuración en Django settings

Rellena los valores en settings_signbox.py (o en las variables de entorno correspondientes):

# URL del Signbox Optimizer (sin barra final)
# Sandbox: https://optimizer-developers.uanataca.com
SIGNBOX_OPTIMIZER_URL = 'https://tu-optimizer.ejemplo.com'

# Credenciales de facturación (requeridas)
SIGNBOX_BILLING_USERNAME = ''
SIGNBOX_BILLING_PASSWORD = ''

# Identidad digital de firma (al menos SIGNBOX_USERNAME es obligatorio)
SIGNBOX_USERNAME = ''
SIGNBOX_PASSWORD = ''
SIGNBOX_PIN     = ''

# Entorno por defecto: 'prod' o 'sandbox'
SIGNBOX_ENV = 'prod'

Parámetros de la operación

Estos parámetros se configuran por workflow desde la interfaz de Athento:

Parámetro

Valores aceptados

Por defecto

Descripción

format

pades, xades, cades

pades

Formato de firma. pades para PDF, xades para XML, cades para otros.

level

BASIC, T, LTV, LTVLITE, LTVA, EPES

BASIC

Nivel de firma electrónica según estándar eIDAS.

env

prod, sandbox

Valor de SIGNBOX_ENV

Entorno de Signbox. Sobrescribe el setting global si se especifica.

page

Entero ≥ 0

0

Página del PDF donde aparece la firma visual. 0 = última página.

Funcionamiento interno

  1. La operación obtiene el documento (File) por su UUID.
  2. Llama a document.prepare_content() para asegurar que el binario está accesible en disco.
  3. Realiza un POST multipart/form-data a {SIGNBOX_OPTIMIZER_URL}/signbox/api/v1/sign incluyendo el fichero y las credenciales.
  4. Si la respuesta es HTTP 200, el binario firmado se guarda con document.update_binary(), que crea una versión del documento original automáticamente.
  5. En caso de error de red o respuesta no-200, la operación devuelve un aviso (msg_type: warning) sin modificar el documento.

Añadir la operación a un workflow

  1. Ir a Administración → Workflows y editar o crear el workflow deseado.
  2. Añadir la operación "Sign document with Signbox" (categoría integration).
  3. Configurar los parámetros format, level, env y page según las necesidades del proceso.
  4. Asegurarse de que los settings de Django están correctamente configurados en el servidor.

Entorno de pruebas (sandbox)

Uanataca proporciona un Optimizer preconfigurado para pruebas en: https://optimizer-developers.uanataca.com

Configura SIGNBOX_OPTIMIZER_URL con esa URL y SIGNBOX_ENV = 'sandbox' para validar la integración sin afectar a producción.

Notas técnicas

  • El timeout de la llamada HTTP es de 120 segundos. Documentos grandes o redes lentas pueden requerir ajustar este valor directamente en el código.
  • Las credenciales (username, password, pin) corresponden a la identidad digital del certificado de firma, no a credenciales de Athento.
  • La contraseña de facturación (billing_password) puede enviarse en texto plano o en base64 según la configuración del Optimizer.
  • La operación no gestiona OTP ni sesiones de firma. Si el certificado configurado requiere OTP, será necesario extender la operación con los endpoints /api/v1/otp y /api/v1/open_session.
  • La operación es de tipo síncrona: no usa url_out ni urlback. Para volúmenes altos o documentos pesados, considerar el modo asíncrono en una versión futura.