API e integrazioni (CRM, Make, n8n)

Può elencare e consultare quella risorsa. Qualsiasi tentativo di creare, modificare o archiviare riceve un errore 403 con il codice PERMISO_DENEGADO e il permesso che manca.

Oltre a consultare, può creare, aggiornare e archiviare in quella risorsa. È il permesso di cui ha bisogno una sincronizzazione bidirezionale.

I permessi sono per risorsa, e si è già visto: quando sono stati aggiunti i fornitori, le chiavi che esistevano — tutte per i clienti — NON hanno ottenuto l'accesso. È stato necessario spuntarlo. Lo stesso varrà per qualsiasi risorsa aggiunta in seguito: un'integrazione non vede mai più di quanto le hai concesso.

I campi sono gli stessi della scheda cliente: nombre e tipo (particular o empresa) sono obbligatori; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) e notas sono facoltativi. L'identificativo fiscale viene salvato in maiuscolo e l'email in minuscolo. Nella risposta tutte le chiavi sono sempre presenti, con null quando non c'è valore, così la mappatura dei campi nel tuo strumento non si rompe. Attenzione al nome: nombre è il nome di battesimo (o la denominazione commerciale per un'azienda) e il cognome va a parte, in apellidos, al plurale.

Se il corpo contiene una chiave che non esiste (ad esempio firstName invece di nombre, o apellido al singolare invece di apellidos), la richiesta non viene rifiutata, ma quel dato non viene salvato. Perché non passi inosservato, la risposta alla creazione e alla modifica di un cliente include avisos.camposIgnorados con l'elenco di quelle chiavi; quelle dell'indirizzo riportano il percorso, come direccion.ciudad. Se compare, controlla la mappatura dei campi della tua integrazione. I campi restituiti dall'API stessa (id, codigo, createdAt…) non generano mai l'avviso, quindi puoi leggere un cliente, modificarlo e rimandarlo intero.

Solo nombre è obbligatorio. Facoltativi: codigo, cif, email, telefono, telefonoSecundario, web, direccion (su una sola riga, non è un oggetto come nei clienti), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica o otro), formaPago, plazoPago (in giorni; 0 significa pagamento immediato), cuentaCliente e notas. Ogni contatto ha nombre —obbligatorio—, cargo, telefono, email e notas; i contatti non hanno un identificativo proprio.

L'elenco che invii SOSTITUISCE quello presente. Se invii un elenco vuoto, vengono cancellati tutti i contatti; se non invii la chiave (o invii null), restano come erano. È questo che ti permette di leggere un fornitore, cambiargli un campo e rimandarlo indietro per intero senza effetti strani.

A differenza di quello del cliente, il codice del fornitore (PROV-004) non è univoco: può ripetersi anche all'interno del tuo stesso laboratorio. Per questo GET /proveedores/{id} accetta solo l'id. Se il tuo ERP conserva solo il codice, usa il filtro dell'elenco: GET /proveedores?codigo=PROV-004 restituisce tutti quelli che corrispondono e decidi tu.

Ogni scheda contiene numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, le date del ciclo (accettazione, inizio e fine di diagnosi e riparazione, avviso al cliente, riconsegna e ultimoCambioEstado, il momento in cui è passata allo stato attuale), un riepilogo del cliente (id, codigo, codigoVisible, nombre, apellidos, razonSocial), il dispositivo (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), il preventivo (numero, total, estado, fechaEnvio e fechaRespuesta, oppure null se non c’è), il tecnico assegnato (solo il nome) e plazoEntregaEstimado, i tempi di consegna indicati al cliente sulla ricevuta di accettazione. Note interne, firme, foto, documenti e password del dispositivo non vengono mai restituiti.

Se il tuo CRM o il tuo centralino apre la scheda del cliente quando arriva una chiamata, usa GET /clientes?telefono=<numero>. Cerca nel telefono principale e in quello secondario e ignora come è scritto il numero: spazi, trattini e il prefisso internazionale del tuo paese (+39 o 0039). Così «347 123 4567» trova un cliente salvato come «+39 347-123-4567». Servono almeno 6 cifre.

GET /clientes/{id}/resumen restituisce in una sola chiamata quello che di solito un CRM mostra nella scheda del cliente: totalReparaciones, reparacionesAbiertas (il dispositivo è ancora in laboratorio), porEstado, totalPresupuestado e totalPresupuestosAprobados (nella valuta del laboratorio, indicata in moneda), primeraReparacion, ultimaReparacion e ultimaActividad (l'ultima modifica su una qualsiasi delle sue schede). Richiede la risorsa Riparazioni, come le schede.

Gli elenchi accettano page (da 1) e limit (25 per impostazione predefinita, 100 al massimo; se chiedi di più viene ridotto a 100). Il campo busqueda cerca in nome, cognome, ragione sociale, identificativo fiscale, email, codice e telefono.

120 richieste al minuto per chiave (più che sufficienti per una sincronizzazione periodica; frenano un ciclo accidentale). 10 chiavi attive per organizzazione. Gli elenchi restituiscono al massimo 100 record per pagina. Se l'organizzazione è nel piano gratuito con la quota mensile esaurita, la creazione di clienti viene bloccata come nell'applicazione.

Così puoi revocarne una senza rompere le altre, e nell'elenco vedi quando ciascuna è stata usata l'ultima volta.

Conservala nell'archivio credenziali del tuo strumento (connessioni di Make, credenziali di n8n, variabili d'ambiente). Se finisce in un repository o su un sito web, considerala compromessa.

La revoca è immediata: la vecchia chiave inizia a ricevere 401 CLAVE_REVOCADA. Aggiorna la nuova nel tuo strumento e hai finito.

Il riferimento tecnico completo (percorsi, parametri, schemi e codici di errore) è pubblicato in formato aperto su /api/v1/openapi.json, senza bisogno di chiave. Di base è in spagnolo; aggiungi ?lang= con la tua lingua per averlo tradotto (per esempio /api/v1/openapi.json?lang=it, ?lang=en o ?lang=ro). Puoi importarlo in Postman, Insomnia, Make o n8n per avere tutte le chiamate pronte.