API și integrări (CRM, Make, n8n)

Poate lista și consulta acea resursă. Orice încercare de a crea, modifica sau arhiva primește o eroare 403 cu codul PERMISO_DENEGADO și permisiunea care îi lipsește.

Pe lângă consultare, poate crea, actualiza și arhiva în acea resursă. Este permisiunea de care are nevoie o sincronizare bidirecțională.

Permisiunile sunt pe resursă, iar asta s-a și văzut: la adăugarea furnizorilor, cheile care existau — toate pentru clienți — NU au primit acces la ei. A trebuit bifat. La fel va fi cu orice resursă adăugată după aceea: o integrare nu vede niciodată mai mult decât i-ai acordat.

Câmpurile sunt aceleași ca în fișa clientului: nombre și tipo (particular sau empresa) sunt obligatorii; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) și notas sunt opționale. Codul fiscal se salvează cu majuscule, iar e-mailul cu minuscule. În răspuns toate cheile sunt mereu prezente, cu null când nu există valoare, ca maparea câmpurilor din instrumentul tău să nu se strice. Atenție la nume: nombre este prenumele (sau denumirea comercială, pentru o firmă), iar numele de familie se trece separat, în apellidos, la plural.

Dacă corpul conține o cheie care nu există (de exemplu firstName în loc de nombre, sau apellido la singular în loc de apellidos), cererea nu este respinsă, dar valoarea respectivă nu se salvează. Ca să nu treacă neobservat, răspunsul la crearea și editarea unui client include avisos.camposIgnorados cu lista acestor chei; cele din adresă apar cu calea lor, de exemplu direccion.ciudad. Dacă îl vedeți, verificați maparea câmpurilor din integrarea dumneavoastră. Câmpurile pe care le returnează chiar API-ul (id, codigo, createdAt…) nu generează niciodată avertismentul, deci puteți citi un client, îl puteți modifica și trimite înapoi complet.

Doar nombre este obligatoriu. Opționale: codigo, cif, email, telefono, telefonoSecundario, web, direccion (pe un singur rând, nu este un obiect ca la clienți), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica sau otro), formaPago, plazoPago (în zile; 0 înseamnă plata pe loc), cuentaCliente și notas. Fiecare contact are nombre —obligatoriu—, cargo, telefono, email și notas; contactele nu au identificator propriu.

Lista pe care o trimiți ÎNLOCUIEȘTE lista existentă. Dacă trimiți o listă goală, se șterg toate contactele; dacă nu trimiți cheia (sau trimiți null), rămân așa cum erau. Tocmai asta îți permite să citești un furnizor, să-i schimbi un câmp și să-l trimiți înapoi întreg, fără efecte ciudate.

Spre deosebire de cel al clientului, codul furnizorului (PROV-004) nu este unic: se poate repeta chiar și în interiorul atelierului tău. De aceea GET /proveedores/{id} acceptă doar id-ul. Dacă ERP-ul tău păstrează numai codul, folosește filtrul listării: GET /proveedores?codigo=PROV-004 îi returnează pe toți cei care se potrivesc și alegi tu.

Fiecare fișă conține numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, datele ciclului (intrare, început și sfârșit de diagnostic și de reparație, anunțarea clientului, ridicare și ultimoCambioEstado, momentul în care a trecut în starea actuală), un rezumat al clientului (id, codigo, codigoVisible, nombre, apellidos, razonSocial), aparatul (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), devizul (numero, total, estado, fechaEnvio și fechaRespuesta, sau null dacă nu există), tehnicianul alocat (doar numele lui) și plazoEntregaEstimado, termenul comunicat clientului pe bonul de primire. Notele interne, semnăturile, fotografiile, documentele și parolele aparatului nu sunt returnate niciodată.

Dacă CRM-ul sau centrala ta telefonică deschide fișa clientului când intră un apel, folosește GET /clientes?telefono=<număr>. Caută în telefonul principal și în cel secundar și nu contează cum e scris: spații, cratime, prefixul internațional al țării tale (+40 sau 0040) și 0-ul de la început. Astfel, «0722 123 456» găsește un client salvat ca «+40 722-123-456». Sunt necesare cel puțin 6 cifre.

GET /clientes/{id}/resumen returnează într-un singur apel ce arată de obicei un CRM în fișa clientului: totalReparaciones, reparacionesAbiertas (aparatul e încă în service), porEstado, totalPresupuestado și totalPresupuestosAprobados (în moneda service-ului, care vine în moneda), primeraReparacion, ultimaReparacion și ultimaActividad (ultima modificare în oricare dintre fișele lui). Are nevoie de resursa Reparații, la fel ca fișele.

Listările acceptă page (de la 1) și limit (25 implicit, maximum 100; dacă ceri mai mult, se reduce la 100). Câmpul busqueda caută în prenume, nume, denumirea firmei, cod fiscal, e-mail, cod și telefon.

120 de cereri pe minut per cheie (mai mult decât suficient pentru o sincronizare periodică; oprește o buclă accidentală). 10 chei active per organizație. Listările returnează cel mult 100 de înregistrări pe pagină. Dacă organizația este pe planul gratuit și cota lunară e epuizată, crearea de clienți este blocată, la fel ca în aplicație.

Astfel poți revoca una fără să le strici pe celelalte, iar în listă vezi când a fost folosită ultima dată fiecare.

Păstrează-o în seiful de credențiale al instrumentului tău (conexiuni Make, credențiale n8n, variabile de mediu). Dacă ajunge într-un repository sau pe un site, consideră-o compromisă.

Revocarea este imediată: cheia veche începe să primească 401 CLAVE_REVOCADA. Actualizează cheia nouă în instrumentul tău și gata.

Referința tehnică completă (rute, parametri, scheme și coduri de eroare) este publicată într-un format deschis la /api/v1/openapi.json, fără să ai nevoie de cheie. Implicit este în spaniolă; adaugă ?lang= cu limba ta ca s-o ai tradusă (de exemplu /api/v1/openapi.json?lang=ro sau ?lang=en). O poți importa în Postman, Insomnia, Make sau n8n ca să ai toate apelurile pregătite.