1. Síntoma o Necesidad

El cliente experimenta fallos al intentar automatizar la creación de registros en el CRM desde sistemas externos. Los síntomas principales son:

• Recepción de un mensaje de error en el momento de insertar casos: Error api de inserción de casos.
• Casos que no se visualizan en el CRM a pesar de que el sistema externo reporta el envío.
• Fallos en la asignación de contactos o en la comunicación entre sistemas externos (vía Webhooks/APIs, etc) y CRM.

2. Contexto / Escenarios

Este incidente ocurre durante la integración de herramientas de terceros (sitios web, formularios, sistemas de gestión) con el CRM de Wolkvox. Se presenta típicamente al configurar nuevas integraciones o al renovar tokens de seguridad.

3. Respuesta / Solución

Para corregir el error, se deben validar y ajustar los siguientes cuatro pilares de la petición API:

A. Validaciones previas

• Pruebas Previas: Antes de programar la integración final, realice pruebas exitosas utilizando la herramienta Postman - Insertar casos CRM (autenticarse con una cuenta de correo según sea necesario).
• Compare siempre su estructura de solicitud con la documentación oficial del API de Wolkvox.
• Valide que el token esté vigente y correctamente copiado.
• Campos Requeridos: Verifique que todos los campos marcados como obligatorios en el CRM estén presentes en la petición API.
• Confirme que no existan errores tipográficos en los nombres de los campos. 
• Dominio: Asegúrese de que el {{crm_server}} no incluya el prefijo https:// doblemente al concatenar la URL.

B. Configuración del Endpoint

• Método: El consumo del servicio debe ser estrictamente mediante el método POST.
• URL: Debe estar construida correctamente usando servidor de CRM: https://{{crm_server}}/server/API/v2/cases/insert.php 

(Ejemplo: En la variable {{crm_server}}, se debe reemplazar por el dominio real del CRM crm0000.wolkvox.com).

C. Configuración de Autenticación (Token)

Se debe incluir correctamente el Token de acceso en los headers o encabezados:

Header requerido:

• Key: Wolkvox-Token
• Value: [Token generado desde el CRM].

Para obtener el token

• Ingresa a CRM.
• Ve a Configuración. 
• Accede a la sección Integraciones y Tokens.
• Copia un token existente o genera un nuevo según sea el uso (interno o externo). 

D. Estructura del Cuerpo del API (Body)

Para evitar errores en la inserción de registros se deben tener en cuenta los siguientes parámetros: 

• Formato: El cuerpo del API debe enviarse en formato form-data.
• Definición de campos: Se debe validar que todos los campos requeridos estén definidos correctamente.

E. Validación de Datos en Campos

• Campo Operación: Se debe incluir el nombre exacto de la operación en el cuerpo del API, ya que su ausencia o error en el nombre, puede generar fallos inmediatos en la creación del caso.
• Campos Predeterminados del sistema: Los valores (como estados o prioridades nativas) deben enviarse en inglés.
• Campos Personalizados: Deben coincidir exactamente con el nombre configurado en el módulo de casos del CRM (respetando mayúsculas, minúsculas, espacios y formato).

4. Posibles Causas

• Token Incorrecto o Expirado: Uso de una clave de autenticación inválida o mal copiada.
• Formato de Envío Erróneo: Intentar enviar la información en JSON o x-www-form-urlencoded en lugar de form-data.
• Errores Tipográficos: Discrepancia entre los nombres de los campos en el API y los nombres configurados en el módulo de casos.
• Método Incorrecto: Uso de GET o PUT en lugar de POST.

5. Recomendaciones

• Seguridad: No comparta el Wolkvox-Token en canales públicos o chats no cifrados.