API et intégrations (CRM, Make, n8n)

Peut lister et consulter cette ressource. Toute tentative de création, de modification ou d'archivage reçoit une erreur 403 avec le code PERMISO_DENEGADO et la permission manquante.

En plus de consulter, elle peut créer, mettre à jour et archiver dans cette ressource. C'est la permission dont a besoin une synchronisation bidirectionnelle.

Les permissions sont définies par ressource, et cela s'est déjà vu : lors de l'ajout des fournisseurs, les clés existantes — toutes pour les clients — n'ont PAS obtenu l'accès. Il a fallu le cocher. Il en ira de même pour toute ressource ajoutée par la suite : une intégration ne voit jamais plus que ce que vous lui avez accordé.

Les champs sont les mêmes que dans la fiche client : nombre et tipo (particular ou empresa) sont obligatoires ; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) et notas sont facultatifs. L'identifiant fiscal est enregistré en majuscules et l'email en minuscules. Dans la réponse, toutes les clés sont toujours présentes, avec null quand il n'y a pas de valeur, pour que le mappage des champs dans votre outil ne casse jamais. Attention au nom : nombre est le prénom (ou le nom commercial pour une entreprise) et le nom de famille va à part, dans apellidos, au pluriel.

Si le corps contient une clé qui n'existe pas (par exemple firstName au lieu de nombre, ou apellido au singulier au lieu de apellidos), la requête n'est pas refusée, mais cette donnée n'est pas enregistrée. Pour que cela ne passe pas inaperçu, la réponse à la création et à la modification d'un client contient avisos.camposIgnorados avec la liste de ces clés ; celles de l'adresse portent leur chemin, comme direccion.ciudad. Si vous la voyez, vérifiez le mappage des champs de votre intégration. Les champs renvoyés par l'API elle-même (id, codigo, createdAt…) ne déclenchent jamais d'avertissement : vous pouvez lire un client, le modifier et le renvoyer en entier.

Seul nombre est obligatoire. Facultatifs : codigo, cif, email, telefono, telefonoSecundario, web, direccion (sur une seule ligne, ce n'est pas un objet comme pour les clients), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica ou otro), formaPago, plazoPago (en jours ; 0 signifie au comptant), cuentaCliente et notas. Chaque contact comporte nombre —obligatoire—, cargo, telefono, email et notas ; les contacts n'ont pas d'identifiant propre.

La liste que vous envoyez REMPLACE celle qui était là. Une liste vide supprime tous les contacts ; si vous n'envoyez pas la clé (ou si vous envoyez null), ils restent tels quels. C'est ce qui vous permet de lire un fournisseur, d'en modifier un champ et de le renvoyer en entier sans effet de bord.

Contrairement au code client, le code fournisseur (PROV-004) n'est pas unique : il peut se répéter même à l'intérieur de votre propre atelier. C'est pourquoi GET /proveedores/{id} n'accepte que l'id. Si votre ERP ne conserve que le code, utilisez le filtre de la liste : GET /proveedores?codigo=PROV-004 renvoie tout ce qui correspond, et c'est vous qui tranchez.

Chaque fiche contient numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, les dates du cycle (entrée, début et fin du diagnostic et de la réparation, avis au client, restitution et ultimoCambioEstado, le moment où elle est passée à son statut actuel), un résumé du client (id, codigo, codigoVisible, nombre, apellidos, razonSocial), l’appareil (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), le devis (numero, total, estado, fechaEnvio et fechaRespuesta, ou null s’il n’y en a pas), le technicien assigné (son nom uniquement) et plazoEntregaEstimado, le délai indiqué au client sur le bon de dépôt. Les notes internes, signatures, photos, documents et mots de passe de l’appareil ne sortent jamais.

Si votre CRM ou votre standard téléphonique ouvre la fiche du client à chaque appel entrant, utilisez GET /clientes?telefono=<numéro>. La recherche porte sur le téléphone principal et le secondaire, quelle que soit l'écriture du numéro : espaces, tirets, points, indicatif international de votre pays (+33 ou 0033) et 0 initial. Ainsi, « 06 12 34 56 78 » retrouve un client enregistré sous « +33 6.12.34.56.78 ». Il faut au moins 6 chiffres.

GET /clientes/{id}/resumen renvoie en un seul appel ce qu'un CRM affiche habituellement sur la fiche client : totalReparaciones, reparacionesAbiertas (l'appareil est encore à l'atelier), porEstado, totalPresupuestado et totalPresupuestosAprobados (dans la devise de l'atelier, indiquée dans moneda), primeraReparacion, ultimaReparacion et ultimaActividad (la dernière modification sur l'une de ses fiches). Il nécessite la ressource Réparations, comme les fiches.

Les listes acceptent page (à partir de 1) et limit (25 par défaut, 100 au maximum ; au-delà, la valeur est ramenée à 100). Le champ busqueda cherche dans le prénom, le nom, la raison sociale, l'identifiant fiscal, l'email, le code et le téléphone.

120 requêtes par minute et par clé (largement assez pour une synchronisation périodique ; cela freine une boucle accidentelle). 10 clés actives par organisation. Les listes renvoient au maximum 100 enregistrements par page. Si l'organisation est sur le forfait gratuit avec son quota mensuel épuisé, la création de clients est bloquée, comme dans l'application.

Vous pouvez ainsi en révoquer une sans casser les autres, et la liste vous montre quand chacune a été utilisée pour la dernière fois.

Conservez-la dans le coffre d'identifiants de votre outil (connexions Make, credentials n8n, variables d'environnement). Si elle se retrouve dans un dépôt ou sur un site web, considérez-la comme compromise.

La révocation est immédiate : l'ancienne clé commence à recevoir des 401 CLAVE_REVOCADA. Mettez la nouvelle à jour dans votre outil, et c'est terminé.

La référence technique complète (chemins, paramètres, schémas et codes d'erreur) est publiée dans un format ouvert à l'adresse /api/v1/openapi.json, sans clé nécessaire. Par défaut, elle est en espagnol ; ajoutez ?lang= avec votre langue pour l'obtenir traduite (par exemple /api/v1/openapi.json?lang=fr, ?lang=en ou ?lang=ro). Vous pouvez l'importer dans Postman, Insomnia, Make ou n8n pour avoir tous les appels prêts.