API og integrasjoner (CRM, Make, n8n)

Kan liste og slå opp den ressursen. Ethvert forsøk på å opprette, endre eller arkivere får en 403-feil med koden PERMISO_DENEGADO og tillatelsen som mangler.

Kan i tillegg til å slå opp også opprette, oppdatere og arkivere i den ressursen. Det er tillatelsen en toveis synkronisering trenger.

Tillatelser gis per ressurs, og det har allerede vist seg: da leverandørene kom til, fikk nøklene som allerede fantes — alle for kunder — IKKE tilgang til dem. De måtte hukes av. Det samme gjelder enhver ressurs som legges til senere: en integrasjon ser aldri mer enn det du har gitt den.

Feltene 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-en lagres med store bokstaver og e-posten med små. I svaret er alle nøklene alltid med, med null når det ikke finnes noen verdi, slik at feltmappingen i verktøyet ditt ikke brekker. Pass på navnet: nombre er fornavnet (eller firmanavnet for en bedrift), og etternavnet skal for seg i apellidos, i flertall.

Hvis body inneholder en nøkkel som ikke finnes (for eksempel firstName i stedet for nombre, eller apellido i entall i stedet for apellidos), avvises ikke forespørselen, men verdien lagres ikke. For at det ikke skal gå ubemerket hen, inneholder svaret ved oppretting og redigering av kunder avisos.camposIgnorados med en liste over disse nøklene; adressefelt står med sin sti, for eksempel direccion.ciudad. Ser du den, sjekk feltkoblingen i integrasjonen din. Felt som API-et selv returnerer (id, codigo, createdAt …), gir aldri varsel, så du kan hente en kunde, endre den og sende den tilbake i sin helhet.

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

Listen du sender, ERSTATTER den som lå der. Sender du en tom liste, slettes alle kontaktene; sender du ikke nøkkelen (eller sender null), blir de stående som de var. Det er nettopp dette som gjør at du kan lese en leverandør, endre ett felt og sende hele objektet tilbake uten rare følger.

Til forskjell fra kundens er leverandørkoden (PROV-004) ikke unik: den kan gå igjen selv innenfor ditt eget verksted. Derfor tar GET /proveedores/{id} bare imot id-en. Lagrer ERP-et ditt bare koden, bruker du filteret i listen: GET /proveedores?codigo=PROV-004 returnerer alle som treffer, og så avgjør du hvilken det er.

Hver ordre inneholder numeroFicha, estado, prioridad, ubicacion, averiaDeclarada, diagnostico, datoene i forløpet (innlevering, start og slutt på feilsøking og reparasjon, varsel til kunden, utlevering og ultimoCambioEstado, når ordren fikk sin nåværende status), et kundesammendrag (id, codigo, codigoVisible, nombre, apellidos, razonSocial), enheten (id, codigo, tipo, marca, modelo, numeroSerie, imei, color), pristilbudet (numero, total, estado, fechaEnvio og fechaRespuesta, eller null hvis det ikke finnes), den tildelte teknikeren (bare navnet) og plazoEntregaEstimado, leveringstiden kunden fikk oppgitt på innleveringskvitteringen. Interne notater, signaturer, bilder, dokumenter og enhetens passord returneres aldri.

Hvis CRM-et eller sentralbordet ditt åpner kundekortet når en samtale kommer inn, bruker du GET /clientes?telefono=<nummer>. Det søkes i både hovednummeret og det sekundære nummeret, uansett hvordan nummeret er skrevet: mellomrom, bindestreker og landskoden (+47 eller 0047) ignoreres. Da finner «912 34 567» en kunde som er lagret som «+47 912-34-567». Det trengs minst 6 sifre.

GET /clientes/{id}/resumen returnerer i ett kall det et CRM vanligvis viser på kundekortet: totalReparaciones, reparacionesAbiertas (enheten er fortsatt på verkstedet), porEstado, totalPresupuestado og totalPresupuestosAprobados (i verkstedets valuta, som kommer i moneda), primeraReparacion, ultimaReparacion og ultimaActividad (den siste endringen i en av kundens ordrer). Akkurat som ordrene krever det ressursen Reparasjoner.

Lister godtar page (fra 1) og limit (25 som standard, maks 100; ber du om mer, kuttes det til 100). Feltet busqueda søker i navn, etternavn, firmanavn, skatte-ID, e-post, kode og telefon.

120 forespørsler per minutt per nøkkel (mer enn nok for en periodisk synkronisering; det bremser en løkke som har løpt løpsk). 10 aktive nøkler per organisasjon. Lister returnerer maks 100 poster per side. Er organisasjonen på gratisplanen med månedskvoten brukt opp, stoppes oppretting av kunder akkurat som i appen.

Da kan du tilbakekalle én uten å ødelegge de andre, og i listen ser du når hver av dem sist ble brukt.

Lagre den i verktøyets lager for påloggingsopplysninger (tilkoblinger i Make, credentials i n8n, miljøvariabler). Legger du den i et repository eller på et nettsted, må du regne den som lekket.

Tilbakekallingen gjelder umiddelbart: den gamle nøkkelen begynner å få 401 CLAVE_REVOCADA. Oppdater den nye i verktøyet ditt, så er du ferdig.

Den komplette tekniske referansen (stier, parametere, skjemaer og feilkoder) er publisert i et åpent format på /api/v1/openapi.json, uten at det trengs nøkkel. Som standard er den på spansk; legg til ?lang= med språket ditt for å få den oversatt (for eksempel ?lang=nb eller /api/v1/openapi.json?lang=en). Du kan importere den i Postman, Insomnia, Make eller n8n for å ha alle kallene klare.