Erreur Zoho Books 41029 – QR Code signé rejeté

Cette erreur signifie que Zoho Books a rejeté le QR code signé que vous avez envoyé lors de l'appel du point de terminaison de poussée de facture électronique, car le service n'a pas pu vérifier la signature numérique du QR code. L'API accepte la facture mais échoue lorsque la valeur signedqrcode ne correspond pas au format de signature ou aux octets attendus par le vérificateur ^[1].

Ce que cela signifie

Zoho Books effectue une validation de signature sur la valeur signedqrcode que vous fournissez à POST /books/v3/invoices/{invoiceid}/einvoice/status/push ; si la charge utile du QR code ou son encodage diffère de la sortie IRP d'origine, le vérificateur Books renvoie le code 41029 et le message indiquant que le QR Code n'est pas valide ^[1]. En pratique, cela signifie que l'API a comparé le signedqr_code soumis aux données signées attendues et a échoué à la vérification plutôt qu'à une authentification ou à des champs manquants ^[1].

Causes courantes

• Vous avez modifié la chaîne QR en la décodant/réencodant, en la tronquant ou en la reformatant (sauts de ligne, espaces supplémentaires, encodage URL) avant de l'envoyer. L'utilisateur dans la communauté a signalé avoir transmis le QR original mais que l'API n'a accepté que lorsqu'il a été omis, suggérant une incompatibilité d'encodage/format ^[1].
• Variantes de jeu de caractères ou de base64 : la sortie IRP peut utiliser une forme spécifique de base64 URL-safe ou rembourrée ; la modification de celle-ci casse la vérification.
• Le signedqrcode ne correspond pas à l'IRN/facture que vous avez joint dans Zoho Books (identifiants de facture ou numéros incorrects).
• L'API ou le transport intermédiaire (proxy, webhook, bibliothèques de code) a altéré les octets : échappement automatique, différences d'encodage JSON ou sérialisation de formulaire du client HTTP.

(Chaque cause ci-dessus est observée ou implicite dans le rapport de la communauté d'échec de vérification lors de l'envoi du QR signé IRP) ^[1].

Comment le résoudre

1. Envoyez la chaîne QR signée brute exacte renvoyée par l'IRP sans décoder, réencoder ou modifier les caractères. Collez la valeur de réponse IRP dans le corps de votre requête exactement comme vous l'avez reçue, y compris tout remplissage ou symbole ^[1].
2. Assurez-vous que votre client ne modifie pas les caractères : définissez Content-Type sur application/json, évitez l'encodage URL automatique de ce champ, et vérifiez que votre bibliothèque HTTP ne modifie pas les sauts de ligne ou les espaces blancs.
3. Comparez octet par octet : calculez un hachage (SHA256) du signedqrcode IRP et de la valeur que vous transmettez réellement ; ils doivent correspondre. S'ils diffèrent, identifiez où votre code le transforme et arrêtez cette étape.
4. Vérifiez que le signedqrcode correspond à la facture/IRN que vous associez dans Zoho Books. Si vous avez enregistré la facture auprès de l'IRP, confirmez que l'IRN et le QR appartiennent à la même facture et que vous avez utilisé le bon invoice_id dans le point de terminaison.
5. Si vous recevez toujours 41029, reproduisez la requête, y compris les en-têtes et le corps, et incluez à la fois le QR signé IRP d'origine et la valeur transmise exacte dans un ticket de support afin que l'équipe Books puisse inspecter les journaux de validation.

Quand escalader

Ouvrez un ticket de support Zoho avec un exemple minimal et reproductible (QR signé IRP d'origine, la requête HTTP exacte que vous avez envoyée, invoice_id/IRN) si la chaîne QR que vous transmettez correspond octet par octet à la sortie IRP et que l'API la rejette toujours — l'ingénierie Zoho aura besoin des journaux de requête pour déboguer la vérification côté serveur ^[1].

^[1]: Zoho Books API Error 41029 – Signed QR Code Rejected (fil de discussion communautaire)