API en integraties (CRM, Make, n8n)

Kan die bron opsommen en opvragen. Elke poging om aan te maken, te wijzigen of te archiveren krijgt een 403-fout met de code PERMISO_DENEGADO en het recht dat ontbreekt.

Kan in die bron naast opvragen ook aanmaken, bijwerken en archiveren. Dit recht heeft een tweerichtingssynchronisatie nodig.

De rechten gelden per bron, en dat is al gebleken: toen de leveranciers erbij kwamen, kregen de bestaande sleutels — allemaal voor klanten — er GEEN toegang toe. Dat moest je aanvinken. Hetzelfde geldt voor elke bron die er later bij komt: een integratie ziet nooit meer dan wat je hebt toegestaan.

De velden zijn dezelfde als in de klantkaart: nombre en tipo (particular of empresa) zijn verplicht; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) en notas zijn optioneel. Het fiscaal nummer wordt in hoofdletters opgeslagen en het e-mailadres in kleine letters. In het antwoord zijn alle sleutels altijd aanwezig, met null als er geen waarde is, zodat de veldtoewijzing in je tool niet breekt. Let op de naam: nombre is de voornaam (of de handelsnaam bij een bedrijf) en de achternaam gaat apart in apellidos, meervoud.

Bevat de body een sleutel die niet bestaat (bijvoorbeeld firstName in plaats van nombre, of apellido in het enkelvoud in plaats van apellidos), dan wordt het verzoek niet geweigerd, maar die waarde wordt niet opgeslagen. Zodat dat niet onopgemerkt blijft, bevat het antwoord bij het aanmaken en bewerken van een klant avisos.camposIgnorados met de lijst van die sleutels; adresvelden staan erin met hun pad, zoals direccion.ciudad. Zie je die, controleer dan de veldtoewijzing van je integratie. Velden die de API zelf teruggeeft (id, codigo, createdAt…) geven nooit een melding, dus je kunt een klant ophalen, wijzigen en in zijn geheel terugsturen.

Alleen nombre is verplicht. Optioneel zijn codigo, cif, email, telefono, telefonoSecundario, web, direccion (op één regel, hier geen object zoals bij klanten), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica of otro), formaPago, plazoPago (in dagen; 0 betekent contant), cuentaCliente en notas. Elk contact heeft nombre —verplicht—, cargo, telefono, email en notas; contacten hebben geen eigen id.

De lijst die je stuurt VERVANGT de bestaande. Stuur je een lege lijst, dan worden alle contacten verwijderd; stuur je de sleutel niet mee (of stuur je null), dan blijven ze zoals ze waren. Daardoor kun je een leverancier ophalen, één veld wijzigen en het hele object terugsturen zonder rare bijeffecten.

Anders dan bij klanten is de leverancierscode (PROV-004) niet uniek: hij kan zelfs binnen je eigen werkplaats dubbel voorkomen. Daarom accepteert GET /proveedores/{id} uitsluitend het id. Bewaart je ERP alleen de code, gebruik dan het filter van de lijst: GET /proveedores?codigo=PROV-004 geeft alles terug wat overeenkomt en jij kiest.

Elke bon bevat numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, de datums van het traject (inname, start en einde van diagnose en reparatie, melding aan de klant, afgifte en ultimoCambioEstado, wanneer de bon zijn huidige status kreeg), een klantoverzicht (id, codigo, codigoVisible, nombre, apellidos, razonSocial), het apparaat (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), de offerte (numero, total, estado, fechaEnvio en fechaRespuesta, of null als er geen is), de toegewezen technicus (alleen de naam) en plazoEntregaEstimado, de levertermijn die de klant op het ontvangstbewijs heeft gekregen. Interne notities, handtekeningen, foto’s, documenten en apparaatwachtwoorden worden nooit teruggegeven.

Opent je CRM of telefooncentrale de klantkaart zodra er een gesprek binnenkomt, gebruik dan GET /clientes?telefono=<nummer>. Er wordt gezocht in het eerste en het tweede telefoonnummer, ongeacht hoe het nummer is geschreven: spaties, streepjes, het landnummer (+31 of 0031) en de 0 aan het begin maken niet uit. Zo vindt “06 12345678” een klant die is opgeslagen als “+31 6-1234-5678”. Er zijn minstens 6 cijfers nodig.

GET /clientes/{id}/resumen geeft in één aanroep terug wat een CRM meestal op de klantkaart laat zien: totalReparaciones, reparacionesAbiertas (het apparaat is nog in de werkplaats), porEstado, totalPresupuestado en totalPresupuestosAprobados (in de valuta van de werkplaats, die in moneda meekomt), primeraReparacion, ultimaReparacion en ultimaActividad (de laatste wijziging in een van zijn bonnen). Net als de bonnen heeft dit de bron Reparaties nodig.

Lijsten accepteren page (vanaf 1) en limit (standaard 25, maximaal 100; vraag je meer, dan wordt het afgekapt op 100). Het veld busqueda zoekt in naam, achternaam, bedrijfsnaam, fiscaal nummer, e-mailadres, code en telefoon.

120 verzoeken per minuut per sleutel (ruim genoeg voor een periodieke synchronisatie; het remt een per ongeluk ontstane lus af). 10 actieve sleutels per organisatie. Lijsten geven maximaal 100 records per pagina terug. Zit de organisatie op het gratis abonnement met het maandquotum op, dan stopt het aanmaken van klanten net als in de applicatie.

Zo kun je er één intrekken zonder de andere te breken, en zie je in de lijst wanneer elke sleutel voor het laatst is gebruikt.

Bewaar hem in de credential-opslag van je tool (verbindingen in Make, credentials in n8n, omgevingsvariabelen). Zet je hem in een repository of op een website, beschouw hem dan als gelekt.

Intrekken werkt direct: de oude sleutel krijgt vanaf dan 401 CLAVE_REVOCADA. Werk de nieuwe bij in je tool en je bent klaar.

De complete technische referentie (paden, parameters, schema's en foutcodes) is gepubliceerd in een open formaat op /api/v1/openapi.json, zonder dat je een sleutel nodig hebt. Standaard is hij in het Spaans; voeg ?lang= met je taal toe om hem vertaald te krijgen (bijvoorbeeld ?lang=nl, of /api/v1/openapi.json?lang=en). Je kunt hem importeren in Postman, Insomnia, Make of n8n om alle aanroepen klaar te hebben staan.