Vurdering

Teknisk oversikt

Partner API er et server-til-server REST-API over postene kundene deres allerede har i Visena — personer, selskaper, oppdrag, aktiviteter og dokumenter. Én OAuth 2.0-legitimasjon, ni ressurser under én versjonert kontrakt, og skrivinger som går gjennom de samme applikasjonstjenestene som Visenas egne skjermbilder. Denne siden er arkitekturen og sikkerhetsmodellen, for dem som skal godkjenne integrasjonen.

Én integrasjon, den virkelige Visena-motoren

Systemene deres oppretter, leser, oppdaterer og sletter postene som betyr noe — personer og selskaper, oppdrag, aktiviteter, dokumenter — inne i kundens Visena-instans. Det finnes ingen egen integrasjonsdatabase og ingen nattlig kopi: en skriving lander på den samme posten en bruker ville redigert, gjennom de samme applikasjonstjenestene, så validering og forretningsregler oppfører seg som de gjør i grensesnittet.

Den praktiske konsekvensen er at integrasjonen arver plattformens korrekthet i stedet for å implementere den på nytt. En regel grensesnittet håndhever — et påkrevd felt, et duplikat organisasjonsnummer, en referanse som må finnes — håndheves på kallet ditt også, og feilen kommer tilbake som et maskinlesbart problemdokument i stedet for en halvskrevet post.

Hva API-et gir deg

En CRUD- og synkroniseringsflate over kjernepostene i CRM og arbeid, med konvensjonene en integratør forventer. Alt under er tilgjengelig på ressursene som er dokumentert i referansen; sidene per ressurs er kontrakten.

De tre lesemodusene, side om side

Det er tre ulike oppgaver, og å velge feil er den vanligste integrasjonsfeilen vi ser. Listeendepunktene og garantiene deres er dekket i sin helhet under Lister, paginering og synk.

# a page with a real total — for a screen or a picker
GET /acme/api/v1/en/person?offset=0&limit=50

# keyset paging — for a one-off extract, walked start to finish
GET /acme/api/v1/en/person/cursor?limit=100

# a time window — for ongoing synchronisation
GET /acme/api/v1/en/person/timeline?key=modified&since=2026-08-20T02:00:00Z

En flate som fortsetter å vokse

Ni ressurser er i drift i dag, alle under én kontrakt, én legitimasjon og én autentiseringsmåte. Adressen bærer en eksplisitt versjon, så en ressurs som kommer senere er en ny adresse under samme v1 — å utvide det integrasjonen dekker er ny kode mot en kjent flate, ikke en ny integrasjon.

Arkitekturen i korte trekk

Du snakker med ett offentlig inngangspunkt. Det autentiserer kallet, knytter det til nøyaktig én instans og ruter det videre til motoren. Alt bak det inngangspunktet er internt i Visena, og aldri noe integrasjonen din adresserer.

1. Autentiser. Bytt klient-id og hemmelighet i et tilgangstoken på /{instanceName}/auth/api/v1/token, med OAuth 2.0 client credentials.
2. Kall. Send tokenet som et vanlig Authorization: Bearer-hode til hvilket som helst dataendepunkt. Det er ingenting annet som skal signeres.
3. Inngangspunktet validerer og isolerer. Tokenet sjekkes, og instansen som står i adressen må være en tokenet er innvilget for. Et kall utenfor innvilgelsen avvises i inngangspunktet, før det når noen data.
4. Motoren bruker samme logikk som produktet. Skrivinger går gjennom Visenas egne applikasjonstjenester, så regler, validering og følgeeffekter utløses som for en endring gjort på skjermen.

Anatomien til en URL

Hvert kall har samme form: instansen, API-versjonen, en locale, og så ressursen.

Locale bestemmer språket i meldingene som kommer tilbake, ikke hvilke poster du ser. Instansnavnet velger kunden, og det må være en tokenet er innvilget for — et avvik avvises i inngangspunktet, ikke besvart med noen andres data.

Det sikkerhetsteamet vil vite

Kontrollene under er egenskaper ved plattformen, ikke valg en integratør må slå på. Legitimasjon og tokener har detaljene i drift, og Skrivebeskyttet tilgang går gjennom en legitimasjon som beviselig ikke kan skrive.

• Opake tokener. Et tilgangstoken er en referanseverdi, ikke en beholder: det er ingenting i det å dekode, og det utløper av seg selv — backenden din fornyer det. Et lekket token er et avgrenset tidsvindu, ikke en lesbar kopi av noe.
• Hemmeligheter vises én gang. Hemmeligheten til en legitimasjon vises én enkelt gang, ved opprettelsen, og lagres bare som en enveis hash — den kan ikke leses tilbake, verken av deg eller av Visena. En tapt hemmelighet erstattes, den gjenopprettes aldri.
• Isolering per instans. En legitimasjon er innvilget én instans, og instansen i adressen må stemme med innvilgelsen — inngangspunktet slår den opp, sjekker den og avviser et avvik. Bak det har hver instans sin egen database, så en forespørsel bundet til én kunde har ingen vei til en annens rader.
• Eksplisitte scope, og ingen tillatende standardverdi. En token-forespørsel må oppgi hvilke scope den vil ha: en som ikke oppgir noen, avvises med invalid_scope — den får ikke stilltiende alt. Delingen mellom lesing og skriving håndheves deretter per forespørsel, i et filter foran endepunktet — derfor kan en legitimasjon utstedt for lesing ikke skrive i det hele tatt, ikke bare være forventet å ikke gjøre det.
• Maskerte identifikatorer. Poster adresseres med maskerte id-er, og masken er utledet per instans: den rå databasenøkkelen går aldri over ledningen i noen retning, og samme post bærer ikke samme id i to ulike instanser.
• Tilbakekalling. Tilbakekall en legitimasjon, og tokenene den har utstedt slutter å virke — regn med at det slår inn innen omtrent ett minutt, ikke øyeblikkelig, fordi valideringssvar mellomlagres kort. Å avslutte en leverandør er ett kall, ikke en venting på utløp.
• Tilskriving, aldri anonym maskinaktivitet. En skriving gjennom API-et tilskrives en virkelig person i instansen, i de samme feltene createdBy og modifiedBy som grensesnittet fyller ut — og der kallet ble gjort for noen andre, navngir actedBy aktøren i tillegg. Ingen API-endring er utilskrevet.

Slik integrerer teamet ditt

Tre steg, og det første kallet skjer vanligvis samme ettermiddag.

1. Få en legitimasjon. En administrator i kundens Visena-instans oppretter en partnerlegitimasjon for integrasjonen og overleverer klient-id og hemmelighet på en trygg måte. Se Legitimasjon og tokener.
2. Hent et token. Backenden din bytter legitimasjonen i et tilgangstoken på token-endepunktet, og fornyer det før det utløper — noen få linjer i hvilken som helst HTTP-stack. Kom i gang har det virkende fra ende til ende.
3. Bygg mot referansen. Å gjøre kall dekker hoder, verb og merge-patch, Feil og feilsøking dekker feiltilfellene, og referansen dokumenterer hvert endepunkt, felt og statuskode per ressurs.

Når dere er klare for produksjon, er Sette i produksjon sjekklisten: avgrenset legitimasjon, en innøvd rotasjon, og hva som bør overvåkes.

Et fundament du kan bygge et produkt på

Partner API gir teamet ditt en standardbasert vei til data kundene allerede stoler på Visena med, med plattformens sikkerhetsmodell, instansisolering og forretningslogikk bak hvert kall. Det finnes ingen ny datamodell å lære og ingen integritetsgap mellom det integrasjonen gjør og det produktet gjør: samme tjenester, samme regler, samme tilskriving.

Ni ressurser er i drift under én kontrakt i dag, og flaten har vokst ved at ressurser er lagt til den — ikke ved at måten du kobler deg på har endret seg. Det er egenskapen det er verdt å designe mot: legitimasjonen, tokenbyttet, adresseformen og feilformatet du integrerer én gang, er de du beholder.

Les Kom i gang Se referansen

Vurderer du, snarere enn å bygge? Skrivebeskyttet tilgang er det korteste beviset på sikkerhetsmodellen — en legitimasjon som kan lese alt den er innvilget, og skrive ingenting.