Hvordan blir jeg varslet når norske selskapsdata endrer seg?

Poll endringsarkivet på /api/v1/changes, som returnerer oppdagede endringshendelser med markørpaginering, eller abonner med en webhook slik at leveransene sendes til deg i stedet. Begge leser det samme arkivet. Polling er enklere å drifte og krever ikke et offentlig endepunkt; webhooks unngår en tomgangsløkke når endringer er sjeldne.

Hvor raskt dukker en registerendring opp i strømmen?

Endringsrader produseres av periodiske oppslag mot kildene, så forsinkelsen er begrenset av den takten og ikke av øyeblikket Brønnøysund skriver oppføringen. Regn strømmen som pålitelig etter hvert, ikke som umiddelbar, og bygg ikke en arbeidsflyt som antar at en endring er synlig sekunder etter at den skjedde.

Hva forteller én enkelt endringsrad meg?

Hvilken enhet som flyttet seg, hvilket felt, og begge verdiene. En rad bærer entity_id, field_path, before_value og after_value, en change_type som created, updated eller deleted, og et detected_at-tidspunkt. Det er nok til å drive en arbeidsflyt direkte i stedet for å sammenligne to øyeblikksbilder og slutte seg til hva som skjedde imellom.

Inneholder endringsrader personopplysninger?

Den offentlige projeksjonen holder tilbake personfelter, og responsen sier det gjennom et personal_fields_withheld-flagg i stedet for å la deg gjette ut fra et fravær. Du får vite at en rolle endret seg og hvilket felt som flyttet seg, som er det en overvåkingsflyt trenger, uten at arkivet blir et lager av personopplysninger.

Kan jeg filtrere strømmen til bare selskapene jeg bryr meg om?

Ja. Filtrer på source, entity_type, entity_id, change_type og et tidsrom med from og to. Å filtrere på entity_id er den direkte måten å følge et bestemt selskap. For en portefølje er det som regel enklere å filtrere på kilde og enhetstype og matche lokalt enn å ha ett abonnement per kunde.

Hvordan henter jeg oppdaterte norske selskapsdata via API?

Gjennom et endringsarkiv i stedet for ved å lese kundelisten din på nytt. Apier poller kildene etter en plan, noterer det som flyttet seg som endringsrader som bare legges til, og serverer dem fra /api/v1/changes med markørpaginering. Hver rad navngir enheten, feltstien og verdiene før og etter, så du handler på selve endringen i stedet for å sammenligne øyeblikksbilder. Kostnaden følger hvor mye som faktisk endret seg, ikke hvor mange selskaper du følger.

Markøren som lukker løkken er det som holder neste kall billig. Å følge tusen selskaper koster det samme som å følge ti, fordi forespørselen spør hva som endret seg og ikke om hvert enkelt selskap.

Hvordan oppdager jeg bytte av daglig leder eller styre?

Filtrer strømmen på enhet og les feltstien. En rolleendring kommer som en rad der entity_type er selskapet, der entity_id er organisasjonsnummeret, og der field_path peker på den delen av oppføringen som flyttet seg. before_value og after_value bærer de to tilstandene, slik at du kan skille en utskifting fra et tillegg uten å bygge opp oppføringen selv.

Rolleendringer er det mest verdifulle signalet i denne strømmen for de fleste, og grunnen er fullmakt snarere enn nysgjerrighet. En ny daglig leder eller et nytt styre kan endre hvem som har rett til å binde selskapet, noe som betyr at ethvert mellomlagret svar du har om signaturrett nå er tvilsomt. Riktig reaksjon på en rollerad er som regel å slå opp fullmakten for organisasjonen på nytt, ikke å lappe på din lokale kopi av rollelisten.

Den offentlige projeksjonen holder tilbake personfelter og sier det på responsen gjennom personal_fields_withheld. Det er en bevisst grense: du får vite at en rolle endret seg og hvilket felt som flyttet seg, som er det en overvåkingsflyt trenger, uten at endringsarkivet stille blir et register over navngitte personer. Når du trenger dagens innehavere, les dem fra /api/v1/company/{org}/context eller slå opp fullmakt direkte.

Hvordan poller jeg effektivt uten å hente alt på nytt?

Hold på en markør, og lagre den. Hver respons returnerer en next_cursor sammen med et has_more-flagg; send markøren tilbake ved neste kall, og du fortsetter nøyaktig der du stoppet. Radene er sortert på oppdagelsestidspunkt, nyeste først, og markøren er ugjennomsiktig, så behandle den som et token du lagrer og ikke som et tidsstempel du kan bygge opp igjen.

Lagre markøren først når batchen den kom med er håndtert. Lagrer du den før, blir enhver krasj midt i en batch til stille hoppede endringer, og det er den feilsituasjonen du minst vil ha i en overvåkingsrørledning, fordi ingenting melder fra om den. Lagrer du etterpå, risikerer du å behandle en batch på nytt ved omstart, og derfor bør håndtererne være idempotente. Å behandle en endring om igjen er billig; å gå glipp av en er det ikke.

Snevre inn strømmen med filtre i stedet for i etterkant: source, entity_type, entity_id, change_type og et intervall med from og to. Passer en pollende tomgangsløkke dårlig for tjenesten din, kan du abonnere med en webhook gjennom /api/v1/subscriptions og få leveransene sendt i stedet. Begge leser det samme arkivet, så valget er driftsmessig og ikke en forskjell i hva du kan få vite.

Hva utløser en endringsoppføring?

Et planlagt oppslag mot en kilde som observerer noe annet enn det som var lagret. Radene bærer en source som navngir hvilken kilde som produserte dem, slik at du kan skille en registerbevegelse hos Brønnøysund fra en oppdatert valutakurs, og en change_type som created, updated eller deleted som beskriver formen på bevegelsen.

Konsekvensen det er verdt å designe rundt, er at strømmen kommer etter hvert og ikke umiddelbart. Forsinkelsen er begrenset av polletakten og ikke av øyeblikket registeret skriver oppføringen sin, så en arbeidsflyt som antar at en endring blir synlig sekunder etter at den skjedde, vil av og til ta feil. Når en beslutning virkelig trenger dagens tilstand, les selskapsendepunktet og sjekk _meta.data_freshness i stedet for å slutte fra fraværet av en endringsrad at alt står stille.

Rader legges bare til. En korreksjon kommer som en ny rad og ikke som en endring av en gammel, og det er nettopp det som gjør arkivet brukbart som dokumentasjon: det du så på et gitt tidspunkt lar seg rekonstruere i ettertid. Den egenskapen er også det som lar en etterlevelseskontrollør spørre når du først fikk vite noe, og få et svar som ikke avhenger av din egen logging. Det samme arkivet ligger bak overvåkingen beskrevet i veiledningen om automatisert selskapskontroll.

Gjør det første kallet

Sandkasseforespørselen under krever ingen nøkkel og viser selskapsoppslaget en endringsrad peker deg tilbake til. TypeScript-snutten tømmer strømmen og lagrer markøren i den rekkefølgen som overlever en krasj.

# Nøkkelløs sandkasse: selskapsoppslaget en endringsstrøm peker deg til.
curl -s https://www.apier.no/api/v1/sandbox/public/company/999999999/context

// Tøm strømmen, lagre så markøren. Rekkefølgen betyr noe ved omstart.
let cursor: string | null = loadCursor();

do {
  const url = new URL("https://www.apier.no/api/v1/changes");
  url.searchParams.set("source", "brreg");
  url.searchParams.set("entity_type", "company");
  url.searchParams.set("limit", "100");
  if (cursor !== null) url.searchParams.set("cursor", cursor);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.APIER_API_KEY}` },
  });
  if (!res.ok) {
    const { error_code, explanation } = await res.json();
    throw new Error(`${error_code}: ${explanation.summary}`);
  }

  const { data } = await res.json();

  for (const row of data.data) {
    // field_path sier HVA som flyttet seg; before/after sier hvordan.
    await handle(row.entity_id, row.field_path, row.before_value, row.after_value);
  }

  // Lagre ETTER at batchen er håndtert, og bare når den ikke er null: på
  // siste side er next_cursor null, og å lagre den ville sendt neste kjøring
  // tilbake til nyeste rad i stedet for å fortsette her.
  cursor = data.pagination.next_cursor;
  if (cursor !== null) await saveCursor(cursor);
} while (cursor !== null);

Ofte stilte spørsmål

Hvordan blir jeg varslet når norske selskapsdata endrer seg?: Poll endringsarkivet på /api/v1/changes, som returnerer oppdagede endringshendelser med markørpaginering, eller abonner med en webhook slik at leveransene sendes til deg i stedet. Begge leser det samme arkivet. Polling er enklere å drifte og krever ikke et offentlig endepunkt; webhooks unngår en tomgangsløkke når endringer er sjeldne.
Hvor raskt dukker en registerendring opp i strømmen?: Endringsrader produseres av periodiske oppslag mot kildene, så forsinkelsen er begrenset av den takten og ikke av øyeblikket Brønnøysund skriver oppføringen. Regn strømmen som pålitelig etter hvert, ikke som umiddelbar, og bygg ikke en arbeidsflyt som antar at en endring er synlig sekunder etter at den skjedde.
Hva forteller én enkelt endringsrad meg?: Hvilken enhet som flyttet seg, hvilket felt, og begge verdiene. En rad bærer entity_id, field_path, before_value og after_value, en change_type som created, updated eller deleted, og et detected_at-tidspunkt. Det er nok til å drive en arbeidsflyt direkte i stedet for å sammenligne to øyeblikksbilder og slutte seg til hva som skjedde imellom.
Inneholder endringsrader personopplysninger?: Den offentlige projeksjonen holder tilbake personfelter, og responsen sier det gjennom et personal_fields_withheld-flagg i stedet for å la deg gjette ut fra et fravær. Du får vite at en rolle endret seg og hvilket felt som flyttet seg, som er det en overvåkingsflyt trenger, uten at arkivet blir et lager av personopplysninger.
Kan jeg filtrere strømmen til bare selskapene jeg bryr meg om?: Ja. Filtrer på source, entity_type, entity_id, change_type og et tidsrom med from og to. Å filtrere på entity_id er den direkte måten å følge et bestemt selskap. For en portefølje er det som regel enklere å filtrere på kilde og enhetstype og matche lokalt enn å ha ett abonnement per kunde.