Skip to main content

Sanntid, dypelenker og notifikasjoner

Når noe skjer i Utleggsappen, må riktig person ofte få beskjed og ledes til riktig sted. Denne siden dekker tre ting integrasjoner ofte trenger: lytte på hendelser i sanntid (SSE), bygge dypelenker tilbake til appen, og forstå hvordan notifikasjoner fungerer.

Server-Sent Events (SSE) – lytte på hendelser i sanntid​

Bruk SSE når du vil reagere på hendelser i Utleggsappen uten å polle.

Endepunkt​

GET https://api.utlegg.app/sse/events
Authorization: Bearer ua_...   (PAT, SAT eller bruker-session)
Accept: text/event-stream

Response-stream er standard SSE – én linje med data: {...} per event, dobbel newline mellom events. Hvert data-objekt har et type-felt: connected (første event på strømmen), heartbeat (hvert 25. sekund, holder forbindelsen åpen) eller resource (en hendelse, se skjemaet under).

Filter med scopes​

Som standard får du alle hendelser brukeren/tokenen har tilgang til. Snevre inn med scopes-parameteren (JSON-array, URL-encodet). Hvert scope kan ha resourceType, eventType, resourceId og organizationId; ugyldige scopes gir 400 (sse_invalid_scopes). En globalt-scopet SAT må sende scopes.

SCOPES='[{"resourceType":"report","eventType":"approved"},{"resourceType":"report","eventType":"submitted"}]'
curl -N "https://api.utlegg.app/sse/events?scopes=$(jq -rn --arg s "$SCOPES" '$s|@uri')" \
  -H "Authorization: Bearer ua_..." \
  -H "Accept: text/event-stream"

Event-skjema​

type ClientUiEvent = {
  type:         'resource';
  resourceType: 'report' | 'organization' | 'department'
                | 'expense' | 'user' | 'account' | 'invoice'
                | 'operation';
  eventType:    'created' | 'updated' | 'deleted'
                | 'submitted' | 'approved' | 'rejected'
                | 'reviewed' | 'published' | 'stale'
                | 'progress' | 'finished' | 'changed';
  resourceId:   string;
  timestamp:    number;   // unix ms
  id?:          string;   // for deduplisering
};

Hendelse invoice/created: Sendes når faktura-PDF er ferdig generert etter at en rapport er godkjent. Lytt på resourceType === 'invoice' og eventType === 'created' for å reagere umiddelbart – f.eks. for å hente og videreformidle fakturaen.

Når du mottar et event, hent fullt objekt fra det relevante REST-endepunktet (GET /reports/{id} osv.) – selve event-payloaden er bevisst tynn.

Eksempel (JS / Node)​

const es = new EventSource(
  'https://api.utlegg.app/sse/events',
  { headers: { Authorization: `Bearer ${process.env.UA_TOKEN}` } }
);

es.onmessage = (msg) => {
  const event = JSON.parse(msg.data);
  if (event.type !== 'resource') return; // connected / heartbeat
  if (event.resourceType === 'report' && event.eventType === 'approved') {
    fetchAndProcessReport(event.resourceId);
  }
};

Praktiske hensyn​

  • Forbindelsen er knyttet til ditt token. Ved token-utløp må klienten reconnecte med ny token.
  • Klient bør implementere reconnect med eksponentielt backoff og bruke event.id til å droppe duplikater. Strømmen spiller ikke av hendelser på nytt: det som skjer mens du er frakoblet, sendes aldri.
  • Hendelser er filtrert per organisasjon og rolle på server-siden – du ser bare det tokenen din har tilgang til.

Dypelenker​

Bruk dypelenker når du sender brukeren fra ditt system tilbake til Utleggsappen.

Stabile ruter​

https://utlegg.app/{organization_handle}/approval/{reportId}   (rapport til godkjenning)
https://utlegg.app/{organization_handle}/report/{reportId}     (innsenders rapport)
https://utlegg.app/inbox/{itemId}

Mobilappen åpner disse URL-ene via Universal Links (iOS) og App Links (Android), i tillegg til /{organization_handle}/godkjenning/{reportId} som e-postene bruker. I nettleseren sender webdashbordet rapportlenkene videre til /{organization_handle}/rapport/{reportId}, som åpner riktig side for den som leser, og innbokslenken til innboksen.

Tips​

  • Bygg lenker rundt objekter og handlinger, ikke skjermnavn – UI-struktur kan endres.
  • Samle ruter i én helper i koden din slik at samme format brukes i e-post, push og web.

Notifikasjoner​

Brukerne får beskjed gjennom flere kanaler:

  • Push (mobilapp) – primær kanal for action-required hendelser
  • E-post – sendes som backup eller når brukeren ikke har appen
  • Innboks – vedvarende oppgaveliste i appen
  • Slack (organisasjonsnivå) – konfigureres av admin

Som integrator påvirker du ikke notifikasjonene direkte – de utløses av samme hendelser som SSE eksponerer. Vil du sende egne varsler, abonner på SSE og gjør utsendingen i ditt eget system.

Se også​