API és integrációk (CRM, Make, n8n)

Listázhatja és lekérdezheti az adott erőforrást. Minden létrehozási, módosítási vagy archiválási kísérlet 403-as hibát kap PERMISO_DENEGADO kóddal és a hiányzó jogosultsággal.

A lekérdezés mellett az adott erőforrásban létrehozhat, frissíthet és archiválhat. Ez a jogosultság kell a kétirányú szinkronizáláshoz.

A jogosultságok erőforrásonként érvényesek, és ez már meg is mutatkozott: amikor a beszállítók megjelentek, a már létező kulcsok — mind ügyfelekhez készült — NEM kaptak hozzájuk hozzáférést. Be kellett jelölni nekik. Ugyanez lesz minden később hozzáadott erőforrással: egy integráció soha nem lát többet, mint amit megadtál neki.

A mezők ugyanazok, mint az ügyfél adatlapján: a nombre és a tipo (particular vagy empresa) kötelező; a nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) és notas opcionális. Az adóazonosítót nagybetűvel, az e-mailt kisbetűvel tároljuk. A válaszban minden kulcs mindig jelen van, null értékkel, ha nincs adat, hogy az eszközödben a mezők leképezése ne törjön el. Figyeljen a névre: a nombre a keresztnév (cégnél a cégnév), a vezetéknév külön, az apellidos mezőbe kerül, többes számban.

Ha a kérés törzsében olyan kulcs van, amely nem létezik (például firstName a nombre helyett, vagy egyes számú apellido az apellidos helyett), a kérést nem utasítjuk el, de az adat nem mentődik. Hogy ez ne maradjon észrevétlen, az ügyfél létrehozásakor és szerkesztésekor a válasz tartalmazza az avisos.camposIgnorados listát ezekkel a kulcsokkal; a cím mezői az útvonalukkal szerepelnek, például direccion.ciudad. Ha megjelenik, ellenőrizze az integráció mezőmegfeleltetését. Az API által visszaadott mezők (id, codigo, createdAt…) soha nem váltanak ki figyelmeztetést, így egy ügyfelet beolvashat, módosíthat és egészben visszaküldhet.

Csak a nombre kötelező. Opcionális: codigo, cif, email, telefono, telefonoSecundario, web, direccion (egyetlen sorban, nem objektum, mint az ügyfeleknél), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica vagy otro), formaPago, plazoPago (napokban; a 0 az azonnali fizetés), cuentaCliente és notas. Minden kapcsolattartónak van nombre mezője — ez kötelező —, valamint cargo, telefono, email és notas; a kapcsolattartóknak nincs saját azonosítójuk.

Az elküldött lista LECSERÉLI a korábbit. Ha üres listát küldesz, az összes kapcsolattartó törlődik; ha nem küldöd el a kulcsot (vagy null értéket küldesz), minden marad a régiben. Épp ettől tudsz beolvasni egy beszállítót, átírni benne egy mezőt, és az egész objektumot visszaküldeni furcsa mellékhatások nélkül.

Az ügyfélkóddal ellentétben a beszállítói kód (PROV-004) nem egyedi: akár a saját műhelyeden belül is ismétlődhet. Ezért a GET /proveedores/{id} csak az id-t fogadja el. Ha az ERP-d csak a kódot tárolja, használd a lista szűrőjét: a GET /proveedores?codigo=PROV-004 visszaadja az összes találatot, és te döntöd el, melyik az.

Minden munkalap tartalmazza a következőket: numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, a folyamat dátumai (átvétel, a hibafeltárás és a javítás kezdete és vége, az ügyfél értesítése, a kiadás és az ultimoCambioEstado, vagyis hogy a munkalap mikor került a jelenlegi állapotába), az ügyfél összefoglalója (id, codigo, codigoVisible, nombre, apellidos, razonSocial), a készülék (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), az árajánlat (numero, total, estado, fechaEnvio és fechaRespuesta, vagy null, ha nincs), a hozzárendelt technikus (csak a neve) és a plazoEntregaEstimado, vagyis az átvételi elismervényen az ügyfélnek megadott várható elkészülési idő. A belső jegyzetek, aláírások, fotók, dokumentumok és a készülék jelszavai soha nem kerülnek ki.

Ha a CRM-ed vagy a telefonközpontod bejövő hívásnál megnyitja az ügyfél adatlapját, használd a GET /clientes?telefono=<szám> hívást. A keresés a fő és a másodlagos telefonszámban is fut, és nem számít, hogyan van leírva a szám: a szóközöket, a kötőjeleket és az országhívószámot (+36 vagy 0036) figyelmen kívül hagyja. Így a „30 123 4567” megtalálja a „+36 30-123-4567” formában mentett ügyfelet. Legalább 6 számjegy kell.

A GET /clientes/{id}/resumen egyetlen hívással visszaadja azt, amit egy CRM általában az ügyfél adatlapján mutat: totalReparaciones, reparacionesAbiertas (a készülék még a műhelyben van), porEstado, totalPresupuestado és totalPresupuestosAprobados (a műhely pénznemében, amely a moneda mezőben érkezik), primeraReparacion, ultimaReparacion és ultimaActividad (az utolsó változás bármelyik munkalapján). A munkalapokhoz hasonlóan a Javítások erőforrás kell hozzá.

A listák elfogadják a page (1-től) és a limit (alapértelmezés 25, legfeljebb 100; ha többet kérsz, 100-ra vágjuk) paramétert. A busqueda mező a névben, vezetéknévben, cégnévben, adóazonosítóban, e-mailben, kódban és telefonszámban keres.

120 kérés percenként és kulcsonként (bőven elég egy időszakos szinkronizáláshoz; megfékez egy véletlen végtelen ciklust). Szervezetenként 10 aktív kulcs. A listák oldalanként legfeljebb 100 rekordot adnak vissza. Ha a szervezet az ingyenes csomagban van, és a havi keret elfogyott, az ügyfelek felvétele ugyanúgy leáll, mint az alkalmazásban.

Így egyet visszavonhatsz a többi megtörése nélkül, és a listában látod, mikor használták utoljára az egyes kulcsokat.

Tárold az eszközöd hitelesítő-tárolójában (Make-kapcsolatok, n8n-hitelesítő adatok, környezeti változók). Ha feltöltöd egy tárolóba vagy egy weboldalra, tekintsd kiszivárgottnak.

A visszavonás azonnali: a régi kulcs 401 CLAVE_REVOCADA választ kezd kapni. Frissítsd az újat az eszközödben, és kész.

A teljes műszaki referencia (útvonalak, paraméterek, sémák és hibakódok) nyílt formátumban érhető el a /api/v1/openapi.json címen, kulcs nélkül. Alapértelmezés szerint spanyolul jelenik meg; fűzd hozzá a ?lang= paramétert a nyelved kódjával, és lefordítva kapod meg (például ?lang=hu vagy /api/v1/openapi.json?lang=en). Importálhatod a Postman, Insomnia, Make vagy n8n eszközökbe, hogy minden hívás készen álljon.