API και ενσωματώσεις (CRM, Make, n8n)

Μπορεί να εμφανίζει λίστες και να προβάλλει αυτόν τον πόρο. Κάθε απόπειρα δημιουργίας, τροποποίησης ή αρχειοθέτησης λαμβάνει σφάλμα 403 με τον κωδικό PERMISO_DENEGADO και το δικαίωμα που του λείπει.

Εκτός από την προβολή, μπορεί να δημιουργεί, να ενημερώνει και να αρχειοθετεί σε αυτόν τον πόρο. Είναι το δικαίωμα που χρειάζεται ένας αμφίδρομος συγχρονισμός.

Τα δικαιώματα είναι ανά πόρο, και αυτό φάνηκε ήδη: όταν προστέθηκαν οι προμηθευτές, τα κλειδιά που υπήρχαν —όλα για πελάτες— ΔΕΝ απέκτησαν πρόσβαση σε αυτούς. Χρειάστηκε να τσεκαριστεί. Το ίδιο θα ισχύει για κάθε πόρο που θα προστεθεί αργότερα: μια ενσωμάτωση δεν βλέπει ποτέ περισσότερα από όσα της παραχώρησες.

Τα πεδία είναι τα ίδια με την καρτέλα του πελάτη: nombre και tipo (particular ή empresa) είναι υποχρεωτικά· nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) και notas είναι προαιρετικά. Ο φορολογικός αριθμός αποθηκεύεται με κεφαλαία και το email με πεζά. Στην απάντηση όλα τα κλειδιά είναι πάντα παρόντα, με null όταν δεν υπάρχει τιμή, για να μη σπάει η αντιστοίχιση πεδίων στο εργαλείο σου. Προσοχή στο όνομα: το nombre είναι το μικρό όνομα (ή η επωνυμία, αν πρόκειται για επιχείρηση) και το επώνυμο μπαίνει χωριστά, στο apellidos, στον πληθυντικό.

Αν το σώμα περιέχει κλειδί που δεν υπάρχει (για παράδειγμα firstName αντί για nombre ή apellido στον ενικό αντί για apellidos), το αίτημα δεν απορρίπτεται, αλλά η τιμή αυτή δεν αποθηκεύεται. Για να μην περάσει απαρατήρητο, η απάντηση στη δημιουργία και την επεξεργασία πελάτη περιλαμβάνει το avisos.camposIgnorados με τη λίστα αυτών των κλειδιών· τα πεδία της διεύθυνσης εμφανίζονται με τη διαδρομή τους, π.χ. direccion.ciudad. Αν το δείτε, ελέγξτε την αντιστοίχιση πεδίων της ενσωμάτωσής σας. Τα πεδία που επιστρέφει το ίδιο το API (id, codigo, createdAt…) δεν προκαλούν ποτέ προειδοποίηση, οπότε μπορείτε να διαβάσετε έναν πελάτη, να τον αλλάξετε και να τον στείλετε πίσω ολόκληρο.

Μόνο το nombre είναι υποχρεωτικό. Προαιρετικά: codigo, cif, email, telefono, telefonoSecundario, web, direccion (σε μία μόνο γραμμή, δεν είναι αντικείμενο όπως στους πελάτες), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica ή otro), formaPago, plazoPago (σε ημέρες· το 0 σημαίνει τοις μετρητοίς), cuentaCliente και notas. Κάθε επαφή έχει nombre —υποχρεωτικό—, cargo, telefono, email και notas· οι επαφές δεν έχουν δικό τους αναγνωριστικό.

Η λίστα που στέλνεις ΑΝΤΙΚΑΘΙΣΤΑ αυτή που υπήρχε. Αν στείλεις κενή λίστα, σβήνονται όλες οι επαφές· αν δεν στείλεις το κλειδί (ή στείλεις null), μένουν όπως ήταν. Αυτό ακριβώς σου επιτρέπει να διαβάσεις έναν προμηθευτή, να του αλλάξεις ένα πεδίο και να τον στείλεις πίσω ολόκληρο χωρίς παράξενες παρενέργειες.

Σε αντίθεση με τον κωδικό πελάτη, ο κωδικός του προμηθευτή (PROV-004) δεν είναι μοναδικός: μπορεί να επαναληφθεί ακόμη και μέσα στο δικό σου συνεργείο. Γι' αυτό το GET /proveedores/{id} δέχεται μόνο το id. Αν το ERP σου κρατά μόνο τον κωδικό, χρησιμοποίησε το φίλτρο της λίστας: το GET /proveedores?codigo=PROV-004 επιστρέφει όλους όσους ταιριάζουν και αποφασίζεις εσύ.

Κάθε δελτίο περιέχει numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, τις ημερομηνίες του κύκλου (παραλαβή, έναρξη και λήξη διάγνωσης και επισκευής, ειδοποίηση πελάτη, παράδοση και ultimoCambioEstado, δηλαδή πότε το δελτίο πέρασε στην τρέχουσα κατάστασή του), μια σύνοψη του πελάτη (id, codigo, codigoVisible, nombre, apellidos, razonSocial), τη συσκευή (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), την προσφορά (numero, total, estado, fechaEnvio και fechaRespuesta, ή null αν δεν υπάρχει), τον τεχνικό στον οποίο έχει ανατεθεί (μόνο το όνομά του) και το plazoEntregaEstimado, δηλαδή τον χρόνο παράδοσης που αναφέρθηκε στον πελάτη στην απόδειξη παραλαβής. Οι εσωτερικές σημειώσεις, οι υπογραφές, οι φωτογραφίες, τα έγγραφα και οι κωδικοί της συσκευής δεν επιστρέφονται ποτέ.

Αν το CRM ή το τηλεφωνικό σου κέντρο ανοίγει την καρτέλα του πελάτη όταν μπαίνει μια κλήση, χρησιμοποίησε GET /clientes?telefono=<αριθμός>. Η αναζήτηση γίνεται στο κύριο και στο δεύτερο τηλέφωνο, όπως κι αν είναι γραμμένος ο αριθμός: τα κενά, οι παύλες και το διεθνές πρόθεμα (+30 ή 0030) αγνοούνται. Έτσι το «691 234 5678» βρίσκει έναν πελάτη αποθηκευμένο ως «+30 691-234-5678». Χρειάζονται τουλάχιστον 6 ψηφία.

Το GET /clientes/{id}/resumen επιστρέφει με μία μόνο κλήση ό,τι δείχνει συνήθως ένα CRM στην καρτέλα του πελάτη: totalReparaciones, reparacionesAbiertas (η συσκευή είναι ακόμη στο συνεργείο), porEstado, totalPresupuestado και totalPresupuestosAprobados (στο νόμισμα του συνεργείου, που έρχεται στο moneda), primeraReparacion, ultimaReparacion και ultimaActividad (η τελευταία αλλαγή σε οποιοδήποτε από τα δελτία του). Όπως και τα δελτία, απαιτεί τον πόρο Επισκευές.

Οι λίστες δέχονται page (από το 1) και limit (25 από προεπιλογή, 100 το μέγιστο· αν ζητήσεις περισσότερα περικόπτεται στα 100). Το πεδίο busqueda ψάχνει σε όνομα, επώνυμο, επωνυμία, φορολογικό αριθμό, email, κωδικό και τηλέφωνο.

120 αιτήματα ανά λεπτό και κλειδί (υπεραρκετά για έναν περιοδικό συγχρονισμό· φρενάρει έναν τυχαίο βρόχο). 10 ενεργά κλειδιά ανά οργανισμό. Οι λίστες επιστρέφουν το πολύ 100 εγγραφές ανά σελίδα. Αν ο οργανισμός είναι στο δωρεάν πλάνο με εξαντλημένο το μηνιαίο όριο, η καταχώριση πελατών σταματά όπως και στην εφαρμογή.

Έτσι μπορείς να ανακαλέσεις ένα χωρίς να σπάσεις τα υπόλοιπα, και στη λίστα βλέπεις πότε χρησιμοποιήθηκε το καθένα για τελευταία φορά.

Φύλαξέ το στον χώρο διαπιστευτηρίων του εργαλείου σου (συνδέσεις του Make, credentials του n8n, μεταβλητές περιβάλλοντος). Αν το ανεβάσεις σε αποθετήριο ή σε ιστοσελίδα, θεώρησέ το διαρρευμένο.

Η ανάκληση είναι άμεση: το παλιό κλειδί αρχίζει να λαμβάνει 401 CLAVE_REVOCADA. Ενημέρωσε το νέο στο εργαλείο σου και τελείωσες.

Η πλήρης τεχνική αναφορά (διαδρομές, παράμετροι, σχήματα και κωδικοί σφάλματος) δημοσιεύεται σε ανοιχτή μορφή στο /api/v1/openapi.json, χωρίς να χρειάζεται κλειδί. Από προεπιλογή είναι στα ισπανικά· πρόσθεσε ?lang= με τη γλώσσα σου για να την πάρεις μεταφρασμένη (για παράδειγμα ?lang=el ή /api/v1/openapi.json?lang=en). Μπορείς να την εισάγεις στο Postman, στο Insomnia, στο Make ή στο n8n για να έχεις όλες τις κλήσεις έτοιμες.