API i integracions (CRM, Make, n8n)

Pot llistar i consultar eixe recurs. Qualsevol intent de crear, modificar o arxivar rep un error 403 amb el codi PERMISO_DENEGADO i el permís que li falta.

A més de consultar, pot crear, actualitzar i arxivar en eixe recurs. És el permís que necessita una sincronització bidireccional.

Els permisos són per recurs, i això ja s'ha notat: quan es van afegir els proveïdors, les claus que existien —totes de clients— NO hi van guanyar accés. Va caldre marcar-ho. El mateix valdrà per a qualsevol recurs que s'afija més avant: una integració mai no veu més del que li vas concedir.

Els camps són els mateixos que en la fitxa del client: nombre i tipo (particular o empresa) són obligatoris; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) i notas són opcionals. L'identificador fiscal es guarda en majúscules i el correu en minúscules. En la resposta totes les claus hi són sempre, amb null quan no hi ha valor, perquè el mapatge de camps en la teua ferramenta no es trenque. Compte amb el nom: nombre és el nom de pila (o el nom comercial si és una empresa) i el cognom va a banda, en apellidos, en plural.

Si el cos porta una clau que no existix (per exemple firstName en lloc de nombre, o apellido en singular en lloc de apellidos), la petició no es rebutja, però eixa dada no es guarda. Perquè no passe desapercebut, la resposta d'alta i d'edició de clients inclou avisos.camposIgnorados amb la llista d'eixes claus; les de l'adreça porten la seua ruta, com direccion.ciudad. Si t'apareix, revisa el mapatge de camps de la teua integració. Els camps que retorna la mateixa API (id, codigo, createdAt…) no generen avís, així que pots llegir un client, canviar-lo i tornar-lo sencer.

Només nombre és obligatori. Opcionals: codigo, cif, email, telefono, telefonoSecundario, web, direccion (en una sola línia, no és un objecte com en clients), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica o otro), formaPago, plazoPago (en dies; 0 és al comptat), cuentaCliente i notas. Cada contacte porta nombre —obligatori—, cargo, telefono, email i notas; els contactes no tenen identificador propi.

La llista que envies SUBSTITUÏX la que hi havia. Si envies una llista buida, s'esborren tots els contactes; si no envies la clau (o envies null), es queden com estaven. Això és el que fa que pugues llegir un proveïdor, canviar-li un camp i tornar-lo sencer sense efectes estranys.

A diferència del de client, el codi del proveïdor (PROV-004) no és únic: es pot repetir fins i tot dins del teu propi taller. Per això GET /proveedores/{id} només accepta l'id. Si el teu ERP només guarda el codi, utilitza el filtre del llistat: GET /proveedores?codigo=PROV-004, que retorna tots els que hi coincidisquen i decidixes tu.

Cada fitxa porta numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, les dates del cicle (entrada, inici i fi del diagnòstic i de la reparació, avís al client, lliurament i ultimoCambioEstado, quan va passar al seu estat actual), un resum del client (id, codigo, codigoVisible, nombre, apellidos, razonSocial), l'aparell (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), el pressupost (numero, total, estado, fechaEnvio i fechaRespuesta, o null si no en té), el tècnic assignat (només el seu nom) i plazoEntregaEstimado, el termini que es va indicar al client en el resguard. No ixen mai les notes internes, les firmes, les fotos, els documents ni les contrasenyes de l'aparell.

Si el teu CRM o la teua centraleta obri la fitxa del client quan entra una cridada, utilitza GET /clientes?telefono=<número>. Busca en el telèfon principal i en el secundari i ignora com estiga escrit: espais, guions, el prefix internacional del teu país (+34 o 0034) i el 0 inicial. Així «612 345 678» troba un client guardat com a «+34 612-345-678». Calen com a mínim 6 dígits.

GET /clientes/{id}/resumen retorna en una sola crida el que sol mostrar un CRM en la fitxa del client: totalReparaciones, reparacionesAbiertas (l'aparell continua en el taller), porEstado, totalPresupuestado i totalPresupuestosAprobados (en la moneda del taller, que arriba en moneda), primeraReparacion, ultimaReparacion i ultimaActividad (l'últim canvi en qualsevol de les seues fitxes). Necessita el recurs Reparacions, igual que les fitxes.

Els llistats accepten page (des d'1) i limit (25 per defecte, 100 com a màxim; si en demanes més es retalla a 100). El camp busqueda busca en el nom, cognoms, raó social, identificador fiscal, correu, codi i telèfon.

120 peticions per minut i clau (de sobra per a una sincronització periòdica; frena un bucle accidental). 10 claus actives per organització. Els llistats retornen com a màxim 100 registres per pàgina. Si l'organització està en el pla gratuït amb la quota mensual exhaurida, l'alta de clients es talla igual que en l'aplicació.

Així pots revocar-ne una sense trencar les altres, i en la llista veus quan es va utilitzar cadascuna per última vegada.

Guarda-la en el magatzem de credencials de la teua ferramenta (connexions de Make, credencials de n8n, variables d'entorn). Si la puges a un repositori o a una web, considera-la filtrada.

La revocació és immediata: la clau antiga comença a rebre 401 CLAVE_REVOCADA. Actualitza la nova en la teua ferramenta i ja està.

La referència tècnica completa (rutes, paràmetres, esquemes i codis d'error) està publicada en format obert en /api/v1/openapi.json, sense necessitat de clau. Per defecte ix en castellà; afig ?lang= amb el teu idioma per a tindre-la traduïda (per exemple /api/v1/openapi.json?lang=en o ?lang=ro). Pots importar-la en Postman, Insomnia, Make o n8n per a tindre totes les crides preparades.