API ja integratsioonid (CRM, Make, n8n)

Saab selle ressursi kirjeid loetleda ja vaadata. Iga katse luua, muuta või arhiveerida saab vastuseks vea 403 koodiga PERMISO_DENEGADO ja puuduva õiguse nimega.

Lisaks päringutele saab selles ressursis luua, uuendada ja arhiveerida. Seda õigust vajab kahesuunaline sünkroonimine.

Õigused antakse ressursi kaupa ja see on juba ka praktikas näha olnud: kui lisati tarnijad, ei saanud olemasolevad võtmed — kõik klientide jaoks — neile ligipääsu. Selle pidi eraldi märkima. Sama kehtib iga hiljem lisatava ressursi kohta: integratsioon ei näe kunagi rohkem, kui sa talle lubasid.

Väljad on samad mis kliendikaardil: nombre ja tipo (eraisik või ettevõte) on kohustuslikud; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) ja notas on valikulised. Maksukohustuslase number salvestatakse suurtähtedega ja e-post väiketähtedega. Vastuses on alati olemas kõik võtmed, väärtuse puudumisel null, et väljade vastendus sinu tööriistas katki ei läheks. Pane tähele nime: nombre on eesnimi (või ettevõtte puhul ärinimi) ja perekonnanimi läheb eraldi välja apellidos, mitmuses.

Kui päringu kehas on võti, mida ei eksisteeri (näiteks firstName nombre asemel või ainsuses apellido apellidos asemel), päringut tagasi ei lükata, kuid seda väärtust ei salvestata. Et see märkamata ei jääks, sisaldab kliendi loomise ja muutmise vastus välja avisos.camposIgnorados nende võtmete loendiga; aadressi võtmed on koos teega, näiteks direccion.ciudad. Kui see ilmub, kontrolli oma integratsiooni väljade vastendust. API enda tagastatavad väljad (id, codigo, createdAt…) hoiatust ei tekita, seega võid kliendi lugeda, muuta ja tervikuna tagasi saata.

Kohustuslik on ainult nombre. Valikulised: codigo, cif, email, telefono, telefonoSecundario, web, direccion (ühel real, mitte objektina nagu klientidel), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica või otro), formaPago, plazoPago (päevades; 0 tähendab kohe makstes), cuentaCliente ja notas. Igal kontaktil on nombre — kohustuslik —, cargo, telefono, email ja notas; kontaktidel ei ole oma identifikaatorit.

Saadetud loend ASENDAB varasema. Kui saadad tühja loendi, kustutatakse kõik kontaktid; kui võtit ei saada (või saadad null), jäävad need muutmata. Tänu sellele saad tarnija lugeda, muuta ühte välja ja saata selle tervikuna tagasi ilma ootamatute kõrvalmõjudeta.

Erinevalt kliendi koodist ei ole tarnija kood (PROV-004) unikaalne: see võib korduda isegi sinu enda töökojas. Seetõttu aktsepteerib GET /proveedores/{id} ainult id-d. Kui sinu ERP salvestab ainult koodi, kasuta loendi filtrit: GET /proveedores?codigo=PROV-004, mis tagastab kõik sobivad kirjed ja otsustad ise.

Igal tellimusel on numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, elutsükli kuupäevad (vastuvõtt, diagnostika ja remondi algus ja lõpp, kliendi teavitamine, üleandmine ning ultimoCambioEstado ehk millal praegusesse olekusse mindi), kliendi kokkuvõte (id, codigo, codigoVisible, nombre, apellidos, razonSocial), seade (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), hinnapakkumine (numero, total, estado, fechaEnvio ja fechaRespuesta või null, kui seda pole), määratud tehnik (ainult nimi) ja plazoEntregaEstimado ehk vastuvõtuaktis kliendile teatatud tähtaeg. Sisemisi märkmeid, allkirju, fotosid, dokumente ega seadme paroole ei väljastata kunagi.

Kui sinu CRM või telefonikeskjaam avab kõne saabumisel kliendikaardi, kasuta GET /clientes?telefono=<helistaja number>. Otsitakse põhi- ja teisest telefoninumbrist ning kirjutusviis ei loe: tühikud, sidekriipsud, sinu riigi rahvusvaheline suunakood (+34 või 0034) ja algne 0. Nii leiab «612 345 678» kliendi, kes on salvestatud kujul «+34 612-345-678». Vaja on vähemalt 6 numbrit.

GET /clientes/{id}/resumen tagastab ühe päringuga selle, mida CRM tavaliselt kliendikaardil näitab: totalReparaciones, reparacionesAbiertas (seade on veel töökojas), porEstado, totalPresupuestado ja totalPresupuestosAprobados (töökoja valuutas, mis tuleb väljal moneda), primeraReparacion, ultimaReparacion ja ultimaActividad (viimane muudatus ükskõik millises tema tellimuses). Vajab ressurssi Remondid, nagu ka tellimused.

Loendid aktsepteerivad parameetreid page (alates 1) ja limit (vaikimisi 25, maksimaalselt 100; kui küsid rohkem, piiratakse see 100-ni). Väli busqueda otsib eesnimest, perekonnanimest, ärinimest, maksukohustuslase numbrist, e-postist, koodist ja telefonist.

120 päringut minutis võtme kohta (perioodiliseks sünkroonimiseks rohkem kui küllalt; peatab kogemata tekkinud tsükli). 10 aktiivset võtit organisatsiooni kohta. Loendid tagastavad lehel kuni 100 kirjet. Kui organisatsioon on tasuta paketis ja kuulimiit on täis, peatub klientide lisamine samamoodi nagu rakenduses.

Nii saad ühe tühistada teisi katki tegemata ja loendist näed, millal igaüht viimati kasutati.

Hoia seda oma tööriista volituste hoidlas (Make'i ühendused, n8n-i credentials, keskkonnamuutujad). Kui laadid selle repositooriumi või veebilehele, pea seda lekkinuks.

Tühistamine on kohene: vana võti hakkab saama vastuseks 401 CLAVE_REVOCADA. Uuenda uus võti oma tööriistas ja ongi valmis.

Täielik tehniline viide (teed, parameetrid, skeemid ja veakoodid) on avaldatud avatud vormingus aadressil /api/v1/openapi.json, võtit pole vaja. Vaikimisi on see hispaania keeles; lisa ?lang= oma keelega, et saada tõlgitud versioon (näiteks /api/v1/openapi.json?lang=en või ?lang=ro). Saad selle importida Postmani, Insomniasse, Make'i või n8n-i, et kõik päringud oleksid valmis.