XamiLib Go — Referencia de clases

Paquete: xamisdk. El punto de entrada es XamiSDK, creado con xamisdk.New(cfg). Todos los métodos devuelven error como último valor; el error concreto es *xamisdk.XamiException.

XamiSDK

Punto de entrada de la librería.

Constructor

xamisdk.New(cfg xamisdk.Config) *XamiSDK

Config acepta:

Métodos

Pades

Firma de documentos PDF (PAdES).

Métodos

Sign(pdfBytes []byte, opts PadesSignOptions) (string, error)

Envía un PDF a firmar. Devuelve el request_id. PadesSignOptions: CredentialKey (requerido), DesignKey, Variables, Reason, Location, SignerName.

Result(requestID string) (map[string]interface{}, error)

Consulta el estado. Cuando está DONE, incluye el PDF firmado en pdf_base64.

Wait(requestID string, timeoutSeconds int, pollSeconds float64) ([]byte, error)

Bloquea hasta que la firma esté lista y devuelve el PDF firmado.

SignAndWait(pdfBytes []byte, opts PadesSignOptions, timeoutSeconds int) ([]byte, error)

Atajo: Sign() + Wait(). Devuelve el PDF firmado.

Ejemplo

pdfBytes, _ := os.ReadFile("documento.pdf")

firmado, err := xami.Pades().SignAndWait(pdfBytes, xamisdk.PadesSignOptions{
    CredentialKey: "TU_CREDENCIAL",
    SignerName:    "Tu Nombre",
    Reason:        "Aprobación",
    Variables:     map[string]interface{}{"name": "Tu Nombre"},
}, 60)
if err != nil {
    var xe *xamisdk.XamiException
    if errors.As(err, &xe) {
        fmt.Println("Error al firmar:", xe.Message, xe.Code)
    }
    return
}
os.WriteFile("documento_firmado.pdf", firmado, 0o644)

Blockchain

Firma de transacciones / mensajes EVM. El chip actúa como wallet y devuelve r/s/v; tú ensamblas la transacción con tu librería EVM.

Métodos

Sign(txHash string, opts BlockchainSignOptions) (string, error)

Envía el hash a firmar. Devuelve el request_id. BlockchainSignOptions: CredentialKey (requerido, credencial EVM), ChainID.

Result(requestID string) (map[string]interface{}, error)

Consulta el estado.

Wait(requestID string, timeoutSeconds int, pollSeconds float64) (map[string]interface{}, error)

Bloquea hasta tener la firma. Devuelve el mapa con r/s/v/signature.

SignAndWait(txHash string, opts BlockchainSignOptions, timeoutSeconds int) (map[string]interface{}, error)

Atajo: Sign() + Wait().

Ejemplo

firma, err := xami.Blockchain().SignAndWait("0xHASH_DE_LA_TX", xamisdk.BlockchainSignOptions{
    CredentialKey: "TU_CREDENCIAL_EVM",
    ChainID:       648541,
}, 60)
// firma["r"], firma["s"], firma["v"]

Credentials

Consulta de credenciales en la caché local.

Designs

Consulta de diseños de sello en la caché local.

Health

Results

Requiere xamiSDK ≥ 0.2.0.

Pades.Result() necesita que conserves el requestID. Si tu proceso se reinició o el push no llegó, ese documento quedaba inalcanzable desde la librería. Con Results puedes recuperar lo firmado sin depender de tu propio almacenamiento.

pendientes, _ := xami.Results().Pending(50)
for _, it := range pendientes {
    r := it.(map[string]interface{})
    fmt.Println(r["request_id"], "lleva esperando desde", r["created_at"])
}

Errors

Requiere xamiSDK ≥ 0.2.0.

Devuelve el mensaje corto y el error_id de cada fallo. Nunca devuelve el traceback: el detalle técnico solo sale del equipo del cliente cuando alguien ejecuta xamisdk report. Está pensado para que tu aplicación pueda decirle al usuario qué falló y con qué identificador pedir soporte.

fallos, _ := xami.Errors().ForRequest(requestID)
if len(fallos) > 0 {
    f := fallos[0].(map[string]interface{})
    fmt.Println("No se pudo firmar:", f["short"])
    fmt.Println("Menciona", f["error_id"], "al pedir soporte.")
}

Compatibilidad de versiones

Los métodos marcados con xamiSDK ≥ 0.2.0 devuelven 404 contra un servicio anterior. Compruébalo antes si no controlas la versión instalada:

v, _ := xami.Health().APIVersion()
if v >= 2 {
    xami.Sync()
}

Manejo de errores

Todos los métodos devuelven error; el error concreto es *xamisdk.XamiException (campos Message, Code, Code == 0 cuando no aplica, p. ej. error de red).

firmado, err := xami.Pades().SignAndWait(pdfBytes, opts, 60)
if err != nil {
    var xe *xamisdk.XamiException
    if errors.As(err, &xe) {
        log.Printf("Error al firmar: %s (%d)", xe.Message, xe.Code)
    }
    return
}