Error 41029 de Zoho Books API: Código QR Firmado Rechazado

Este error significa que Zoho Books rechazó el código QR firmado que enviaste al llamar al endpoint de envío de factura electrónica porque el servicio no pudo verificar la firma digital del código QR. La API acepta la factura pero falla cuando el valor signedqrcode no coincide con el formato o los bytes de la firma que espera el verificador ^[1].

Qué significa

Zoho Books realiza una validación de firma en el valor signedqrcode que proporcionas a POST /books/v3/invoices/{invoiceid}/einvoice/status/push; si la carga útil del QR o su codificación difiere de la salida original del IRP, el verificador de Books devuelve el código 41029 y el mensaje de que el Código QR no es válido ^[1]. En la práctica, esto significa que la API comparó el signedqr_code enviado con los datos firmados esperados y falló la verificación, en lugar de fallar por autenticación o campos faltantes ^[1].

Causas comunes

• Modificaste la cadena del QR decodificándola/recodificándola, recortándola o reformateándola (saltos de línea, espacios extra, codificación URL) antes de enviarla. El usuario en la comunidad informó haber pasado el QR original pero que la API solo lo aceptó cuando se omitió, lo que sugiere una discrepancia en la codificación/formato ^[1].
• Variantes de conjunto de caracteres o base64: la salida del IRP puede usar una forma específica de URL-safe base64 o con relleno; cambiar eso rompe la verificación.
• El signedqrcode no corresponde al IRN/factura que adjuntaste en Zoho Books (identificadores o números de factura no coincidentes).
• La API o el transporte intermedio (proxy, webhook, bibliotecas de código) alteraron los bytes: escape automático, diferencias en la codificación JSON o serialización de formularios del cliente HTTP.

(Cada causa anterior se observa o se infiere en el informe de la comunidad de verificación fallida al enviar el QR firmado del IRP) ^[1].

Cómo solucionarlo

1. Envía la cadena exacta del QR firmado en bruto devuelta por el IRP sin decodificarla, recodificarla ni modificar caracteres. Pega el valor de respuesta del IRP en el cuerpo de tu solicitud exactamente como lo recibiste, incluyendo cualquier relleno o símbolo ^[1].
2. Asegúrate de que tu cliente no altere los caracteres: establece Content-Type a application/json, evita la codificación URL automática de ese campo y verifica que tu biblioteca HTTP no cambie los saltos de línea o los espacios en blanco.
3. Compara byte por byte: calcula un hash (SHA256) del signedqrcode del IRP y del valor que transmites realmente; deben coincidir. Si difieren, identifica dónde tu código lo transforma y detén ese paso.
4. Verifica que el signedqrcode coincida con la factura/IRN que estás asociando en Zoho Books. Si registraste la factura con el IRP, confirma que el IRN y el QR pertenecen a la misma factura y que utilizaste el invoice_id correcto en el endpoint.
5. Si aún recibes 41029, reproduce la solicitud incluyendo encabezados y cuerpo, y adjunta tanto el QR firmado original del IRP como el valor transmitido exacto en un ticket de soporte para que el equipo de Books pueda inspeccionar los registros de validación.

Cuándo escalar

Abre un ticket de soporte de Zoho con un ejemplo mínimo y reproducible (QR firmado original del IRP, la solicitud HTTP exacta que enviaste, invoice_id/IRN) si la cadena del QR que transmites coincide byte por byte con la salida del IRP y la API aún la rechaza — la ingeniería de Zoho necesitará los registros de la solicitud para depurar la verificación del lado del servidor ^[1].

^[1]: Zoho Books API Error 41029 – Signed QR Code Rejected (hilo de la comunidad)