API e integraciones (CRM, Make, n8n)

Puede listar y consultar ese recurso. Cualquier intento de crear, modificar o archivar recibe una error 403 con el código PERMISO_DENEGADO y el permiso que le falta.

Además de consultar, puede crear, actualizar y archivar en ese recurso. Es el permiso que necesita una sincronización bidireccional.

Los permisos son por recurso, y eso ya se ha notado: al añadir los proveedores, las claves que existían —todas de clientes— NO ganaron acceso a ellos. Hubo que marcarlo. Lo mismo valdrá para cualquier recurso que se añada después: una integración nunca ve más de lo que le concediste.

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. El identificador 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 se rompa. Ojo con el nombre: nombre es el nombre de pila (o el nombre comercial si es una empresa) y el apellido va aparte, en apellidos, en plural.

Si el cuerpo trae una clave que no existe (por ejemplo firstName en vez de nombre, o apellido en singular en vez de apellidos), la petición no se rechaza, pero ese dato no se guarda. Para que no pase desapercibido, la respuesta de alta y de edición de clientes incluye avisos.camposIgnorados con la lista de esas claves; las de la dirección llevan su ruta, como direccion.ciudad. Si te 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, cambiarlo y devolverlo entero.

Solo nombre es obligatorio. Opcionales: codigo, cif, email, telefono, telefonoSecundario, web, direccion (en una sola línea, 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 es al contado), cuentaCliente y notas. Cada contacto lleva nombre —obligatorio—, cargo, telefono, email y notas; los contactos no tienen identificador propio.

La lista que envías REEMPLAZA la que había. Si envías una lista vacía, se borran todos los contactos; si no envías la clave (o envías null), se quedan como estaban. Es lo que hace que puedas leer un proveedor, cambiarle un campo y devolverlo entero sin efectos raros.

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

Cada ficha 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 aparato (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), el presupuesto (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 resguardo. Nunca salen las notas internas, las firmas, las fotos, los documentos ni las contraseñas del aparato.

Si tu CRM o tu centralita 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 e ignora cómo esté escrito: espacios, guiones, el prefijo internacional de tu país (+34 o 0034) y el 0 inicial. Así «612 345 678» encuentra a un cliente guardado como «+34 612-345-678». Hacen falta al menos 6 dígitos.

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

Los listados aceptan page (desde 1) y limit (25 por defecto, 100 como máximo; si pides más se recorta a 100). El campo busqueda busca en nombre, apellidos, razón social, identificador fiscal, email, código y teléfono.

120 peticiones por minuto y clave (de sobra para una sincronización periódica; frena un bucle accidental). 10 claves activas por organización. Los listados devuelven como máximo 100 registros por página. Si la organización está en el plan gratuito con el cupo mensual agotado, el alta de clientes se corta igual que en la aplicación.

Así puedes revocar una sin romper 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 una web, considérala filtrada.

La revocación es inmediata: la clave antigua 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. Sin más sale en español; añade ?lang= con tu idioma para tenerla traducida (por ejemplo /api/v1/openapi.json?lang=en o ?lang=ro). Puedes importarla en Postman, Insomnia, Make o n8n para tener todas las llamadas preparadas.