Host embebido con callbacks

Cuando usar este modo

Es el modo correcto cuando el producto ya tiene una aplicacion propia y quiere usar el cliente local como motor embebido.

Ejemplos:

• ERP de escritorio
• POS nativo
• app movil con firma delegada al sistema
• servicio companion que resuelve criptografia propia

Idea central

El host no deberia reimplementar logica de numeracion, rangos, validacion o outbox. Su rol es:

• pasar configuracion
• invocar la FFI
• resolver callbacks de firma o store seguro
• mapear respuestas al modelo UX propio

Superficies recomendadas

Alto nivel

Usar cuando el host quiere resolver rapido:

• bootstrap
• sync_terminal
• emit_xml
• flush_outbox
• get_state

Granular

Usar cuando el host necesita control fino:

• prepare_draft
• sign_only
• enqueue_signed
• retry_failed
• reconcile_state
• reprint_cfe
• test_printer

Callbacks de firma

Cuando la firma no se hace por pkcs12, el host debe proveer callbacks consistentes para:

• localizar el certificado correcto
• firmar el XML
• devolver metadatos verificables del certificado

El callback no deberia devolver solo un XML firmado. Tambien deberia poder informar:

• thumbprint
• alias o subject
• errores tipificados
• imposibilidad de acceso al store o al dispositivo seguro

Recomendaciones de contrato

• tratar siempre code, stage y retryable como fuente de verdad
• no decidir por parsing de mensajes libres
• registrar uuid, profile_id, tipo_cfe, serie y numero cuando existan
• encapsular toda la FFI en un bridge propio del host

Recomendaciones de robustez

• serializar todas las llamadas a firma si el store o dispositivo no soporta concurrencia real
• ejecutar operaciones pesadas fuera del hilo UI
• agregar timeouts y circuitos de recuperacion para callbacks externos
• validar mismatch entre el certificado esperado y el devuelto por el host

Modo recomendado de construccion

1. Crear un wrapper host unico.
2. Centralizar marshaling JSON y errores.
3. Centralizar carga de runtime y configuracion por perfil.
4. Exponer solo operaciones de negocio al resto del producto.

Criterio de cierre

Una integracion embebida esta bien cerrada cuando:

• el resto del producto no conoce detalles de SQLite ni outbox
• los callbacks de firma son estables y auditables
• los errores se traducen a estados de negocio claros
• existe reconciliacion y retry sin depender de la UI