Error UNAPPROVABLE en la API de Zoho CRM para el endpoint de Aprobaciones

El error UNAPPROVABLE es devuelto por la API de Aprobaciones de Zoho CRM cuando un registro no puede entrar o progresar a través de un flujo de aprobación porque falla la validación, carece de la configuración requerida o viola las condiciones de aprobación. Este error señala un problema de regla de negocio o configuración en lugar de una falla de autenticación o red.

Qué significa — explicación concreta ligada a la superficie de la API de Zoho

UNAPPROVABLE ocurre cuando el endpoint de Aprobaciones (por ejemplo, POST /crmv2/Approvals o las APIs de aprobaciones específicas del módulo) determina que el registro de destino no puede ser aprobado bajo las reglas actuales. Las comprobaciones típicas a nivel de API incluyen campos requeridos faltantes para la regla de aprobación, el estado del registro no coincide con los criterios de la regla, o el flujo de trabajo de aprobación no está habilitado o está configurado incorrectamente para ese módulo o tipo de registro ^[3][4].

Causas comunes

• Un campo requerido utilizado por la regla de aprobación está vacío o contiene datos inválidos, lo que provoca que la evaluación de la regla falle ^[4].
• Los criterios de la regla de aprobación no coinciden con el estado del registro (estado, etapa, valor de selección), por lo que el flujo de trabajo se niega a iniciarse ^[3].
• El flujo de trabajo o proceso de aprobación está deshabilitado, eliminado o no asignado al perfil/rol del registro, lo que impide que la API de Aprobaciones enrute la solicitud ^[3].
• La solicitud de API hace referencia al módulo, ID de registro o nombre de API de campo personalizado incorrecto, por lo que Zoho trata el registro como no aplicable a ninguna regla de aprobación ^[3][4].

Cómo solucionarlo

1. Reproduce el fallo en la UI para el mismo registro. Abre el registro en CRM e intenta la misma acción de aprobación para ver advertencias de la UI o campos faltantes.
2. Verifica la configuración de la regla de aprobación: ve a Configuración > Automatización > Aprobaciones y confirma que el proceso está activo, aplicado al módulo correcto y dirigido al perfil/rol del registro. Verifica que las reglas de asignación y los criterios de entrada coincidan exactamente con los valores del registro ^[3].
3. Valida los campos requeridos y los tipos de datos utilizados por la aprobación: confirma que los campos requeridos estén poblados y que los valores de selección/API coincidan con las cadenas esperadas. Usa la llamada GET del registro (GET /crm/v3/Modules/{module}/records/{id}) para inspeccionar las claves de campo y los valores utilizados en el payload de la API ^[4].
4. Confirma que el payload de la solicitud de API utiliza los nombres de API de campo y el ID de registro correctos. Compara las claves del payload con Configuración > Personalización > Módulos y Campos para evitar nombres de API que no coincidan. Si envías mapas anidados, asegúrate de que la estructura JSON coincida con el esquema de la API de Aprobaciones de Zoho.
5. Si la aprobación depende de registros relacionados (campos de búsqueda), confirma que el registro relacionado existe y cumple sus propios criterios. Vuelve a ejecutar la API después de corregir los campos o habilitar el flujo de trabajo.
6. Agrega registro para el cuerpo de la respuesta de la API y cualquier objeto de "detalles" devuelto; a menudo incluyen el campo o el nombre de la regla que falla. Usa ese detalle para enfocar las correcciones y reintentar.

Cuándo escalar

Si verificaste que el proceso de aprobación está activo, los campos del registro son correctos y el payload de la API coincide con los nombres de los campos del módulo, pero el error persiste, contacta al soporte de Zoho con el ID de la solicitud, la solicitud/respuesta completa de la API (redacta secretos) y capturas de pantalla de la configuración de aprobación. El soporte puede inspeccionar la evaluación de reglas del lado del servidor y los registros más allá de la respuesta de la API.

^[3]: CRM | Solución de problemas | Base de conocimientos (https://help.zoho.com/portal/en/kb/crm/troubleshooting)

^[4]: Zoho Learn / ejemplos de la comunidad que muestran datos inválidos y errores de campos de API (https://help.zoho.com/portal/en/community)