API og integrationer (CRM, Make, n8n)

Kan liste og slå den ressource op. Ethvert forsøg på at oprette, ændre eller arkivere får en 403-fejl med koden PERMISO_DENEGADO og den rettighed, der mangler.

Kan ud over at slå op også oprette, opdatere og arkivere i den ressource. Det er den rettighed, en tovejssynkronisering har brug for.

Rettighederne gives pr. ressource, og det har allerede vist sig: da leverandørerne kom til, fik de nøgler, der fandtes i forvejen — alle sammen til kunder — IKKE adgang til dem. De skulle markeres. Det samme gælder enhver ressource, der kommer til senere: en integration ser aldrig mere, end du har givet den.

Felterne er de samme som på kundekortet: nombre og tipo (particular eller empresa) er obligatoriske; nif_cif, apellidos, razonSocial, email, telefono, telefonoSecundario, direccion (calle, numero, piso, codigoPostal, localidad, provincia, pais) og notas er valgfrie. Skatte-id'et gemmes med store bogstaver og e-mailen med små. I svaret er alle nøgler altid med, med null når der ikke er nogen værdi, så feltmapningen i dit værktøj ikke går i stykker. Pas på navnet: nombre er fornavnet (eller firmanavnet for en virksomhed), og efternavnet skal stå for sig i apellidos, i flertal.

Hvis body indeholder en nøgle, der ikke findes (for eksempel firstName i stedet for nombre eller apellido i ental i stedet for apellidos), afvises anmodningen ikke, men værdien gemmes ikke. Så det ikke går ubemærket hen, indeholder svaret ved oprettelse og redigering af kunder avisos.camposIgnorados med en liste over de nøgler; adressefelter står med deres sti, fx direccion.ciudad. Ser du den, så tjek feltmapningen i din integration. Felter, som API'et selv returnerer (id, codigo, createdAt…), giver aldrig en advarsel, så du kan hente en kunde, ændre den og sende den hel tilbage.

Kun nombre er obligatorisk. Valgfrie: codigo, cif, email, telefono, telefonoSecundario, web, direccion (på én enkelt linje, ikke et objekt som hos kunderne), ciudad, provincia, codigoPostal, pais, contactos, tipoProveedor (general, producto, servicio, logistica eller otro), formaPago, plazoPago (i dage; 0 er kontant), cuentaCliente og notas. Hver kontakt har nombre — obligatorisk — samt cargo, telefono, email og notas; kontakterne har ikke deres egen identifikator.

Den liste, du sender, ERSTATTER den, der var. Sender du en tom liste, slettes alle kontakter; sender du ikke nøglen (eller sender null), bliver de, som de var. Det er dét, der gør, at du kan læse en leverandør, ændre ét felt og sende hele objektet tilbage uden mærkelige følger.

Til forskel fra kundens er leverandørkoden (PROV-004) ikke entydig: den kan gå igen selv inden for dit eget værksted. Derfor tager GET /proveedores/{id} kun imod id'et. Gemmer dit ERP kun koden, så brug filteret i listen: GET /proveedores?codigo=PROV-004 returnerer alle, der passer, og så afgør du hvilken.

Hver sag indeholder numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, forløbets datoer (indlevering, start og slut på fejlfinding og reparation, besked til kunden, udlevering og ultimoCambioEstado, hvornår sagen fik sin nuværende status), et kundeoverblik (id, codigo, codigoVisible, nombre, apellidos, razonSocial), enheden (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), tilbuddet (numero, total, estado, fechaEnvio og fechaRespuesta, eller null hvis der ikke er et), den tildelte tekniker (kun navnet) og plazoEntregaEstimado, den leveringstid kunden fik oplyst på indleveringskvitteringen. Interne noter, underskrifter, fotos, dokumenter og enhedens adgangskoder returneres aldrig.

Hvis dit CRM eller dit omstillingsanlæg åbner kundekortet, når et opkald kommer ind, så brug GET /clientes?telefono=<nummer>. Der søges i både det primære og det sekundære telefonnummer, uanset hvordan nummeret er skrevet: mellemrum, bindestreger og landekoden (+45 eller 0045) ignoreres. Så finder »20 12 34 56« en kunde, der er gemt som »+45 20-12-34-56«. Der skal mindst 6 cifre til.

GET /clientes/{id}/resumen returnerer i ét kald det, et CRM typisk viser på kundekortet: totalReparaciones, reparacionesAbiertas (enheden er stadig på værkstedet), porEstado, totalPresupuestado og totalPresupuestosAprobados (i værkstedets valuta, som kommer i moneda), primeraReparacion, ultimaReparacion og ultimaActividad (den seneste ændring i en af kundens sager). Ligesom sagerne kræver det ressourcen Reparationer.

Lister accepterer page (fra 1) og limit (25 som standard, højst 100; beder du om mere, skæres det til 100). Feltet busqueda søger i navn, efternavn, firmanavn, skatte-id, e-mail, kode og telefon.

120 forespørgsler i minuttet pr. nøgle (rigeligt til en periodisk synkronisering; det bremser en løbsk løkke). 10 aktive nøgler pr. organisation. Lister returnerer højst 100 poster pr. side. Er organisationen på det gratis abonnement med månedskvoten brugt op, stopper oprettelsen af kunder ligesom i appen.

Så kan du tilbagekalde én uden at ødelægge de andre, og i listen kan du se, hvornår hver især sidst blev brugt.

Gem den i dit værktøjs lager til legitimationsoplysninger (forbindelser i Make, credentials i n8n, miljøvariabler). Lægger du den i et repository eller på en hjemmeside, skal du betragte den som lækket.

Tilbagekaldelsen sker med det samme: den gamle nøgle begynder at få 401 CLAVE_REVOCADA. Opdatér den nye i dit værktøj, og du er færdig.

Den komplette tekniske reference (stier, parametre, skemaer og fejlkoder) er udgivet i et åbent format på /api/v1/openapi.json, uden at der kræves nøgle. Som standard er den på spansk; tilføj ?lang= med dit sprog for at få den oversat (for eksempel ?lang=da eller /api/v1/openapi.json?lang=en). Du kan importere den i Postman, Insomnia, Make eller n8n og få alle kald gjort klar.