API i integracions (CRM, Make, n8n)

Pot llistar i consultar aquell 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 aquell 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'afegeixi més endavant: una integració mai no veu més del que li vas concedir.

Els camps són els mateixos que a 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 desa en majúscules i el correu en minúscules. A la resposta totes les claus hi són sempre, amb null quan no hi ha valor, perquè el mapatge de camps a la teva eina no es trenqui. Compte amb el nom: nombre és el nom de pila (o el nom comercial si és una empresa) i el cognom va a part, a apellidos, en plural.

Si el cos porta una clau que no existeix (per exemple firstName en lloc de nombre, o apellido en singular en lloc de apellidos), la petició no es rebutja, però aquella dada no es desa. Perquè no passi desapercebut, la resposta d'alta i d'edició de clients inclou avisos.camposIgnorados amb la llista d'aquestes claus; les de l'adreça porten la seva ruta, com direccion.ciudad. Si t'apareix, revisa el mapatge de camps de la teva 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 SUBSTITUEIX 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 puguis 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 desa el codi, fes servir el filtre del llistat: GET /proveedores?codigo=PROV-004, que retorna tots els que hi coincideixin i decideixes 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 al resguard. No surten mai les notes internes, les signatures, les fotos, els documents ni les contrasenyes de l'aparell.

Si el teu CRM o la teva centraleta obre la fitxa del client quan entra una trucada, fes servir GET /clientes?telefono=<número>. Busca al telèfon principal i al secundari i ignora com estigui escrit: espais, guions, el prefix internacional del teu país (+34 o 0034) i el 0 inicial. Així «612 345 678» troba un client desat 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 a la fitxa del client: totalReparaciones, reparacionesAbiertas (l'aparell continua al taller), porEstado, totalPresupuestado i totalPresupuestosAprobados (en la moneda del taller, que arriba a moneda), primeraReparacion, ultimaReparacion i ultimaActividad (l'últim canvi en qualsevol de les seves fitxes). Necessita el recurs Reparacions, igual que les fitxes.

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

120 peticions per minut i clau (de sobres 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ó és al pla gratuït amb la quota mensual exhaurida, l'alta de clients es talla igual que a l'aplicació.

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

Desa-la al magatzem de credencials de la teva eina (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 a la teva eina i llestos.

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