Errore Zoho Books API 41029 – QR Code Firmato Rifiutato

Questo errore significa che Zoho Books ha rifiutato il QR code firmato che hai inviato durante la chiamata all'endpoint di push della fattura elettronica perché il servizio non è riuscito a verificare la firma digitale del QR code. L'API accetta la fattura ma fallisce quando il valore signedqrcode non corrisponde al formato o ai byte della firma che il verificatore si aspetta ^[1].

Cosa significa

Zoho Books esegue la validazione della firma sul valore signedqrcode che fornisci a POST /books/v3/invoices/{invoiceid}/einvoice/status/push; se il payload del QR o la sua codifica differiscono dall'output originale dell'IRP, il verificatore di Books restituisce il codice 41029 e il messaggio che il QR Code non è valido ^[1]. In pratica, ciò significa che l'API ha confrontato il signedqr_code inviato con i dati firmati attesi e ha fallito la verifica, piuttosto che fallire per autenticazione o campi mancanti ^[1].

Cause comuni

• Hai modificato la stringa del QR decodificandola/ricodificandola, troncandola o riformattandola (interruzioni di riga, spazi extra, codifica URL) prima di inviarla. L'utente nella community ha segnalato di aver passato il QR originale ma l'API lo ha accettato solo quando omesso, suggerendo una discrepanza di codifica/formato ^[1].
• Varianti del set di caratteri o di base64: l'output dell'IRP potrebbe utilizzare una forma specifica di base64 URL-safe o con padding; cambiarla interrompe la verifica.
• Il signedqrcode non corrisponde all'IRN/fattura che hai allegato in Zoho Books (identificatori o numeri di fattura non corrispondenti).
• L'API o il trasporto intermedio (proxy, webhook, librerie di codice) hanno alterato i byte: escaping automatico, differenze nella codifica JSON o serializzazione del form del client HTTP.

(Ogni causa sopra è osservata o implicita nel rapporto della community di verifica fallita durante l'invio del QR firmato IRP) ^[1].

Come risolverlo

1. Invia la stringa esatta del QR firmato grezzo restituita dall'IRP senza decodificare, ricodificare o modificare i caratteri. Incolla il valore della risposta IRP nel corpo della tua richiesta esattamente come ricevuto, inclusi eventuali padding o simboli ^[1].
2. Assicurati che il tuo client non alteri i caratteri: imposta Content-Type su application/json, evita la codifica URL automatica di quel campo e verifica che la tua libreria HTTP non modifichi interruzioni di riga o spazi bianchi.
3. Confronta byte per byte: calcola un hash (SHA256) del signedqrcode dell'IRP e del valore che trasmetti effettivamente; devono corrispondere. Se differiscono, identifica dove il tuo codice lo trasforma e interrompi quel passaggio.
4. Verifica che il signedqrcode corrisponda alla fattura/IRN che stai associando in Zoho Books. Se hai registrato la fattura con l'IRP, conferma che l'IRN e il QR appartengano alla stessa fattura e che tu abbia utilizzato l' invoice_id corretto nell'endpoint.
5. Se ricevi ancora 41029, riproduci la richiesta includendo header e corpo, e includi sia il QR firmato IRP originale sia il valore trasmesso esatto in un ticket di supporto in modo che il team di Books possa ispezionare i log di validazione.

Quando escalare

Apri un ticket di supporto Zoho con un esempio minimo e riproducibile (QR firmato IRP originale, la richiesta HTTP esatta che hai inviato, invoice_id/IRN) se la stringa del QR che trasmetti corrisponde byte per byte all'output dell'IRP e l'API la rifiuta ancora — l'ingegneria Zoho avrà bisogno dei log della richiesta per eseguire il debug della verifica lato server ^[1].

^[1]: Zoho Books API Error 41029 – Signed QR Code Rejected (discussione della community)