Integrar CRM.ES mediante REST API (Webservice)

La API REST de CRM.ES permite conectar formularios, ERP, comercio electrónico, aplicaciones de soporte, automatizaciones y procesos de sincronización. Puedes utilizarla para descubrir la estructura del CRM y para consultar, crear, actualizar o eliminar registros respetando los permisos del usuario de integración.

Base técnica

CRM.ES utiliza el Webservice publicado por Vtiger. Por eso los nombres internos de las operaciones y de algunos módulos siguen esa especificación. En esta guía hablamos siempre de CRM.ES y señalamos los nombres técnicos únicamente cuando son necesarios para construir una petición.

Objetivo

Conectar una aplicación de servidor con CRM.ES, iniciar una sesión de forma segura y completar las operaciones habituales sin depender de nombres de campo supuestos ni de consultas directas a la base de datos.

Antes de empezar

Necesitas:

• La URL HTTPS de tu instalación de CRM.ES.
• Un usuario exclusivo para la integración, con acceso solo a los módulos y registros necesarios.
• La Clave de acceso de ese usuario. Habitualmente se encuentra en Menú de usuario > Mis preferencias > Clave de acceso; la ubicación puede variar según la personalización de tu instalación.
• Un proceso de servidor capaz de guardar secretos. No llames a esta API directamente desde JavaScript ejecutado en el navegador.

El endpoint se encuentra normalmente en la raíz del CRM:

https://crm.empresa.es/webservice.php

Sustituye ese dominio por el de tu instalación. Las peticiones utilizan GET o POST con formato application/x-www-form-urlencoded y las respuestas son JSON.

Protege la clave y la sesión

No subas la clave de acceso, el hash de inicio de sesión ni sessionName a Git. Guárdalos en el gestor de secretos o en variables de entorno del servidor. Usa siempre HTTPS y evita registrar URL completas que contengan una sesión activa.

Cómo funciona una sesión

El recorrido tiene cuatro fases:

1. Solicitar un desafío temporal con getchallenge.
2. Calcular md5(token + claveDeAcceso) en el servidor.
3. Intercambiar ese hash por un sessionName mediante login.
4. Enviar sessionName en las operaciones siguientes y cerrar con logout.

El hash MD5 forma parte del protocolo heredado; no sustituye el cifrado del transporte. HTTPS sigue siendo obligatorio.

1. Obtener el desafío temporal

Solicita el token para el nombre de usuario de la integración:

curl --get "https://crm.empresa.es/webservice.php" \
  --data-urlencode "operation=getchallenge" \
  --data-urlencode "username=USUARIO_INTEGRACION"

Respuesta abreviada:

{
  "success": true,
  "result": {
    "token": "TOKEN_TEMPORAL",
    "serverTime": 1720000000,
    "expireTime": 1720000300
  }
}

Utiliza el token antes de expireTime. Si caduca, solicita uno nuevo.

2. Iniciar sesión

En el servidor de tu integración calcula:

HASH_ACCESO = md5(TOKEN_TEMPORAL + CLAVE_DE_ACCESO)

Envía el resultado; el parámetro se llama accessKey, aunque contiene el hash calculado y no la clave original:

curl -X POST "https://crm.empresa.es/webservice.php" \
  --data-urlencode "operation=login" \
  --data-urlencode "username=USUARIO_INTEGRACION" \
  --data-urlencode "accessKey=HASH_ACCESO"

Una respuesta correcta devuelve la sesión y el identificador del usuario:

{
  "success": true,
  "result": {
    "sessionName": "SESION_TEMPORAL",
    "userId": "19x1",
    "version": "0.22",
    "vtigerVersion": "7.5.0"
  }
}

Conserva sessionName solo durante la sesión. El valor userId es útil como usuario asignado al crear registros.

3. Descubrir módulos y campos

No programes una integración suponiendo nombres de módulos, campos obligatorios o valores de listas. Pueden cambiar entre instalaciones.

Listar los módulos disponibles

listtypes devuelve únicamente los tipos accesibles para el usuario autenticado:

curl --get "https://crm.empresa.es/webservice.php" \
  --data-urlencode "operation=listtypes" \
  --data-urlencode "sessionName=SESION_TEMPORAL"

Nombres técnicos habituales:

CRM.ES	Nombre técnico habitual
Cuentas	Accounts
Contactos	Contacts
Potenciales	Leads
Oportunidades	Potentials
Incidencias	HelpDesk
Productos	Products

Comprueba siempre la respuesta de listtypes: los módulos adicionales o personalizados pueden utilizar otros nombres.

Describir un módulo

describe informa de los campos, tipos, obligatoriedad, referencias y valores admitidos:

curl --get "https://crm.empresa.es/webservice.php" \
  --data-urlencode "operation=describe" \
  --data-urlencode "sessionName=SESION_TEMPORAL" \
  --data-urlencode "elementType=Contacts"

Ejecuta describe durante el desarrollo y vuelve a comprobarlo cuando se añadan campos personalizados o cambie una lista de selección.

4. Entender los identificadores

La API utiliza identificadores de Webservice con este formato:

4x123

La parte anterior a x identifica el tipo y la posterior identifica el registro. No elimines el prefijo ni envíes únicamente el número interno. Las relaciones también usan IDs de Webservice:

{
  "lastname": "García",
  "account_id": "3x120"
}

5. Crear un registro

Este ejemplo crea un contacto ficticio. Sustituye los campos por los devueltos por describe:

curl -X POST "https://crm.empresa.es/webservice.php" \
  --data-urlencode "operation=create" \
  --data-urlencode "sessionName=SESION_TEMPORAL" \
  --data-urlencode "elementType=Contacts" \
  --data-urlencode 'element={"lastname":"Ejemplo García","firstname":"Ana","email":"ana.ejemplo@example.com","assigned_user_id":"19x1"}'

element contiene JSON, pero se transmite como un campo de formulario codificado. La respuesta incluye el ID de Webservice creado.

Evita asignaciones incorrectas

No fijes 19x1 en producción. Utiliza el userId obtenido en el login o un ID de usuario que hayas confirmado previamente.

6. Recuperar un registro

curl --get "https://crm.empresa.es/webservice.php" \
  --data-urlencode "operation=retrieve" \
  --data-urlencode "sessionName=SESION_TEMPORAL" \
  --data-urlencode "id=4x123"

Si devuelve permiso denegado, revisa el rol, el perfil y las reglas de acceso del usuario de integración; no intentes eludirlos con una consulta directa a la base de datos.

7. Actualizar un registro

Recupera primero el registro, modifica solo los valores necesarios y conserva su id y los campos obligatorios que indique describe:

curl -X POST "https://crm.empresa.es/webservice.php" \
  --data-urlencode "operation=update" \
  --data-urlencode "sessionName=SESION_TEMPORAL" \
  --data-urlencode 'element={"id":"4x123","lastname":"Ejemplo García","firstname":"Ana","phone":"+34 600 000 000","assigned_user_id":"19x1"}'

Después, utiliza retrieve para comprobar el resultado guardado.

8. Buscar con query

La consulta tiene una sintaxis parecida a SQL, pero no es SQL completo. Debe terminar en punto y coma:

curl --get "https://crm.empresa.es/webservice.php" \
  --data-urlencode "operation=query" \
  --data-urlencode "sessionName=SESION_TEMPORAL" \
  --data-urlencode "query=SELECT id, firstname, lastname, email FROM Contacts WHERE email = 'ana.ejemplo@example.com';"

Ejemplo de paginación:

SELECT id, lastname, modifiedtime FROM Contacts
ORDER BY modifiedtime DESC
LIMIT 0, 50;

Limitaciones del lenguaje de consulta:

• Consulta un solo módulo cada vez.
• No admite JOIN.
• Devuelve como máximo 100 registros por consulta; utiliza LIMIT con desplazamiento para paginar.
• Las condiciones se procesan de izquierda a derecha y no admiten agrupaciones complejas con paréntesis.

No insertes texto recibido de un usuario directamente en la consulta. Valida los campos permitidos y escapa los valores en el servidor de la integración.

9. Eliminar un registro

curl -X POST "https://crm.empresa.es/webservice.php" \
  --data-urlencode "operation=delete" \
  --data-urlencode "sessionName=SESION_TEMPORAL" \
  --data-urlencode "id=4x123"

Prueba primero con un registro identificable. El comportamiento posterior —papelera, conservación y relaciones— depende de la configuración de CRM.ES. No uses delete como mecanismo habitual de sincronización sin acordar una política de bajas.

10. Sincronizar cambios incrementales

sync permite solicitar cambios desde un instante Unix para un módulo:

curl --get "https://crm.empresa.es/webservice.php" \
  --data-urlencode "operation=sync" \
  --data-urlencode "sessionName=SESION_TEMPORAL" \
  --data-urlencode "modifiedTime=1720000000" \
  --data-urlencode "elementType=Contacts"

Guarda en tu aplicación el último instante procesado y diseña la sincronización para poder repetir un lote sin duplicarlo. Verifica también cómo representa la respuesta los registros eliminados antes de automatizar una sincronización bidireccional.

11. Cerrar la sesión

curl -X POST "https://crm.empresa.es/webservice.php" \
  --data-urlencode "operation=logout" \
  --data-urlencode "sessionName=SESION_TEMPORAL"

Cierra la sesión cuando termine el proceso y vuelve a autenticar si una operación informa de que la sesión ha caducado.

Interpretar errores

Todas las respuestas incluyen success. Cuando es false, revisa error.code y error.message:

{
  "success": false,
  "error": {
    "code": "CÓDIGO_ERROR",
    "message": "Descripción del problema"
  }
}

Síntoma	Qué comprobar
Falla el login	Usuario, token no caducado, orden token + clave y hash MD5.
Módulo desconocido	Resultado de listtypes y nombre técnico exacto.
Falta un campo obligatorio	Respuesta de describe y valores de listas de selección.
Permiso denegado	Rol, perfil, reglas de acceso y propiedad del registro.
ID no válido	Formato completo de Webservice, por ejemplo 4x123.
Consulta vacía o truncada	Punto y coma final, límite de 100 y paginación.

Lista de comprobación para producción

• Usa HTTPS y un usuario de integración con permisos mínimos.
• Guarda clave y sesión en un gestor de secretos; no las registres en logs.
• Ejecuta listtypes y describe antes de mapear campos.
• Implementa tiempos de espera, reintentos limitados y renovación de sesión.
• Usa una clave de idempotencia propia o una referencia externa para no crear duplicados.
• Pagina las consultas y registra el último lote procesado.
• Prueba crear, recuperar, actualizar y eliminar únicamente registros ficticios antes de usar datos reales.
• No consultes directamente la base de datos: el Webservice aplica permisos y la lógica del CRM.

Fuentes técnicas

La especificación del protocolo está publicada por Vtiger y es la base utilizada por CRM.ES:

• Integración con aplicaciones externas (REST APIs)
• APIs de servidor y control de permisos

Documentación relacionada

• Importación masiva de datos desde CSV
• Roles, perfiles y reglas de acceso
• Calendario
• Contacto y soporte

Siguiente paso recomendado

Empieza con listtypes y describe en un entorno de prueba. Cuando tengas confirmado el módulo y su esquema, crea un único registro ficticio y recupéralo por su ID antes de automatizar lotes.