API e integraciones con CRM, Make y n8n

Puede listar y consultar ese recurso. Si intenta crear, modificar o archivar, recibe un error 403 con el código PERMISO_DENEGADO y el permiso que le hace falta.

Además de consultar, puede crear, actualizar y archivar dentro de ese recurso. Es el permiso que requiere una sincronización en ambos sentidos.

Los permisos son por recurso, y ya se notó: al agregar los proveedores, las claves que ya existían —todas de clientes— NO obtuvieron acceso a ellos. Hubo que marcarlo. Lo mismo va a pasar con cualquier recurso que se agregue después: una integración nunca ve más de lo que le otorgaste.

Los campos son los mismos que en la ficha del cliente: nombre y tipo (particular o empresa) son obligatorios; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) y notas son opcionales. La identificación fiscal se guarda en mayúsculas y el email en minúsculas. En la respuesta todas las claves están siempre presentes, con null cuando no hay valor, para que el mapeo de campos en tu herramienta no falle. Atención con el nombre: nombre es el nombre de pila (o el nombre comercial si es una empresa) y el apellido va por separado, en apellidos, en plural.

Si el cuerpo incluye una clave que no existe (por ejemplo firstName en lugar de nombre, o apellido en singular en lugar de apellidos), la solicitud no se rechaza, pero ese dato no se guarda. Para que no pase inadvertido, la respuesta al crear y editar clientes incluye avisos.camposIgnorados con la lista de esas claves; las de la dirección llevan su ruta, como direccion.ciudad. Si aparece, revisa el mapeo de campos de tu integración. Los campos que devuelve la propia API (id, codigo, createdAt…) no generan aviso, así que puedes leer un cliente, modificarlo y enviarlo completo de vuelta.

Solo nombre es obligatorio. Son opcionales codigo, cif, email, telefono, telefonoSecundario, web, direccion (en una sola línea; aquí no es un objeto como en clientes), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica u otro), formaPago, plazoPago (en días; 0 significa de contado), cuentaCliente y notas. Cada contacto lleva nombre —obligatorio—, cargo, telefono, email y notas; los contactos no tienen identificador propio.

La lista que mandas REEMPLAZA a la anterior. Si mandas una lista vacía, se eliminan todos los contactos; si no mandas la clave (o mandas null), quedan tal como estaban. Gracias a eso puedes leer un proveedor, cambiarle un campo y devolverlo completo sin efectos inesperados.

A diferencia del código de cliente, el del proveedor (PROV-004) no es único: puede repetirse incluso dentro de tu propio taller. Por eso GET /proveedores/{id} acepta únicamente el id. Si tu ERP solo guarda el código, apóyate en el filtro de la lista: GET /proveedores?codigo=PROV-004 devuelve todos los que coincidan y tú decides cuál es.

Cada orden trae numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, las fechas del ciclo (entrada, inicio y fin del diagnóstico y de la reparación, aviso al cliente, entrega y ultimoCambioEstado, cuándo pasó a su estado actual), un resumen del cliente (id, codigo, codigoVisible, nombre, apellidos, razonSocial), el equipo (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), la cotización (numero, total, estado, fechaEnvio y fechaRespuesta, o null si no tiene), el técnico asignado (solo su nombre) y plazoEntregaEstimado, el plazo que se le indicó al cliente en el comprobante de recepción. Nunca se exponen las notas internas, las firmas, las fotos, los documentos ni las contraseñas del equipo.

Si tu CRM o tu conmutador abre la ficha del cliente al entrar una llamada, usa GET /clientes?telefono=<número>. Busca en el teléfono principal y en el secundario, sin importar cómo esté escrito: ignora espacios, guiones y el prefijo internacional de tu país (+52 o 0052). Así «55 1234 5678» encuentra a un cliente guardado como «+52 55-1234-5678». Se necesitan al menos 6 dígitos.

GET /clientes/{id}/resumen devuelve en una sola llamada lo que suele mostrar un CRM en la ficha del cliente: totalReparaciones, reparacionesAbiertas (el equipo sigue en el taller), porEstado, totalPresupuestado y totalPresupuestosAprobados (en la moneda del taller, que viene en moneda), primeraReparacion, ultimaReparacion y ultimaActividad (el último cambio en cualquiera de sus órdenes). Necesita el recurso Reparaciones, igual que las órdenes.

Las listas aceptan page (desde 1) y limit (25 de forma predeterminada, 100 como máximo; si pides más se recorta a 100). El campo busqueda busca en nombre, apellidos, razón social, identificación fiscal, email, código y teléfono.

120 solicitudes por minuto por clave (más que suficiente para una sincronización periódica; frena un bucle accidental). 10 claves activas por organización. Las listas devuelven como máximo 100 registros por página. Si la organización está en el plan gratuito con el cupo mensual agotado, la creación de clientes se bloquea igual que en la aplicación.

Así puedes revocar una sin afectar a las demás, y en la lista ves cuándo se usó cada una por última vez.

Guárdala en el almacén de credenciales de tu herramienta (conexiones de Make, credenciales de n8n, variables de entorno). Si la subes a un repositorio o a un sitio web, considérala filtrada.

La revocación es inmediata: la clave anterior empieza a recibir 401 CLAVE_REVOCADA. Actualiza la nueva en tu herramienta y listo.

La referencia técnica completa (rutas, parámetros, esquemas y códigos de error) está publicada en formato abierto en /api/v1/openapi.json, sin necesidad de clave. De forma predeterminada se muestra en español de España; agrega ?lang= con tu idioma para verla adaptada (por ejemplo /api/v1/openapi.json?lang=es-LA, o ?lang=en para tenerla en inglés). Puedes importarla en Postman, Insomnia, Make o n8n para tener todas las llamadas listas.