HubSpot: bedriftsdata på organisasjonsnummer

Oversikt

HubSpot er et CRM. Orakel installeres som en OAuth-app i en HubSpot-portal. Etter installasjon kjører to flyter:

• Berikelse via webhook: når en bedrift opprettes, eller org_number endres, kaller HubSpot på Orakel. Orakel henter det berikede kortet (Enhetsregisteret, Regnskapsregisteret, roller, domener) og skriver det tilbake med PATCH.
• Samlet push: startes fra Integrasjoner-fanen på kontoen din (/account?tab=integrations) eller med POST /api/account/integrations/hubspot/sync.

OAuth-token og portal-ID lagres som en Destination av typen hubspot, kryptert (AES-256-GCM). Tilgangstoken fornyes automatisk ved 401.

Oppsett

Ingen invitasjon er nødvendig. HubSpot setter du opp selv.

1. Gå til kontoen din: orakel.cloud/account?tab=integrations. Trykk Koble til HubSpot.
2. Godkjenn. Huk av for «I understand the risks of connecting an unverified app» og trykk Connect app.
3. Gå tilbake til Integrasjoner-fanen. Orakel har opprettet egne felt på bedriftsobjektet og begynner å berike bedrifter som har org_number satt. Har du ingen API-nøkkel fra før, opprettes en med 7 dagers prøveperiode automatisk.
4. Test. Åpne et bedriftskort i HubSpot, sett Organisasjonsnummer til et niesifret organisasjonsnummer (for eksempel 923609016) og lagre. I løpet av 5 til 10 sekunder fyller Orakel inn navn, adresse, næringskode, ansatte, omsetning, daglig leder og mer.
5. Velg felt. Fra Integrasjoner-fanen huker du av hvilke felt Orakel skal skrive. Trykk Lagre endringer og deretter Synkroniser nå for å berike alle bedriftene på nytt.

OAuth-flyten

• GET /api/oauth/hubspot/install setter en state-informasjonskapsel og sender deg videre til https://app-eu1.hubspot.com/oauth/authorize.
• GET /api/oauth/hubspot/callback bytter inn koden, leser ut portalId og e-postadressen til den som installerer, oppretter eller oppdaterer en Destination med navnet hubspot-<portalId>, og oppretter de egne feltene. Finnes det ingen nøkkel for installatøren fra før, sendes en prøvenøkkel og en velkomst-e-post med innloggingslenke.
• Fornyingstoken byttes ut ved hver fornying. lib/hubspot/client.ts håndterer det ved 401.

Feltoppsett

Feltene styres per portal fra Integrasjoner-fanen. Alt skrives til bedriftsobjektet i HubSpot. Egne felt opprettes ved første installasjon.

Tomme verdier utelates før PATCH.

Konfigurasjon

Callbacken skriver denne konfigurasjonen (kryptert). Du skriver den ikke selv:

{
  "accessToken": "...",
  "refreshToken": "...",
  "expiresAt": 1713705600000,
  "portalId": 147637517,
  "userEmail": "installer@acme.example",
  "fieldSelection": ["companyName", "employeeCount", "revenue", "ceoName", "website", "streetAddress", "postalCode"]
}

• portalId er hub-ID-en i HubSpot, og brukes til å finne riktig destinasjon for portalen.
• fieldSelection er feltene du har valgt i Integrasjoner-fanen. Standard er de sju feltene over.

Hvordan push fungerer

• Match: søk i /crm/v3/objects/companies/search etter org_number = <orgNumber>, limit: 1.
• Oppdatering: PATCH /crm/v3/objects/companies/<id> med de valgte feltene.
• Oppretting: POST /crm/v3/objects/companies med de samme feltene.
• Webhook: abonnementene company.creation og company.propertyChange (på feltet org_number) utløser enrichHubspotCompany(portalId, objectId) asynkront. Endepunktet svarer 200 { ok: true, processing: [...] } med én gang.
• Signatur: v3 HMAC-SHA256 over METHOD + offentlig URI + kropp + tidsstempel. Den offentlige URI-en bygges opp fra X-Forwarded-Proto og X-Forwarded-Host, slik at signaturen stemmer bak omvendt proxy.

Vanlige feil

Advarsel om ukjent app ved installasjon. HubSpot varsler om at appen ikke er gjennomgått. Det er forventet før lansering. Trykk Connect app for å gå videre.

Feltene fylles ikke ut etter installasjon. Sjekk at org_number er satt på bedriftskortet. Berikelsen utløses når org_number opprettes eller endres. For bedrifter du allerede har, bruk Synkroniser nå fra Integrasjoner-fanen.

400 INVALID_OPTION på bransje. Det innebygde industry-feltet i HubSpot godtar bare én av 147 forhåndsdefinerte verdier. Orakel skriver norske næringskoder til et eget felt (nace_industry) og lar industry være i fred.

Utløpt token, eller behov for ny tilkobling. Tilgangstoken fornyes automatisk ved bruk. Får du vedvarende innloggingsfeil, koble til på nytt:

1. Gå til orakel.cloud/account?tab=integrations.
2. Trykk Koble fra ved siden av HubSpot-tilkoblingen.
3. Trykk Koble til HubSpot og gå gjennom OAuth-flyten på nytt.
4. Orakel oppdaterer tilkoblingen du har fra før. Ingen data går tapt, og det opprettes ingen dobbel portal.

Orakel-kortet mangler på bedriftskortene. Orakel-kortet viser berikede data rett i HubSpot. Forsvinner det, er det som regel fjernet fra oppsettet. Slik henter du det tilbake:

1. Åpne et bedriftskort i HubSpot.
2. Trykk Customize (blyantikonet øverst til høyre i panelet).
3. Under Cards finner du Orakel i listen og drar det inn i oppsettet.
4. Trykk Save.

Vil du gjøre det for alle på én gang: gå til Settings, Objects, Companies, Record Customization, velg standardvisningen og legg til Orakel-kortet der.

Anbudsfeltene dukker ikke opp. Aktive anbud og lenke til siste anbud finnes bare for Norge. De vises i feltvelgeren når landfilteret står på NO eller alle land.

Verdt å vite

• industry er en liste med 147 faste verdier. Skriver du norsk næringskodetekst dit, får du 400 INVALID_OPTION. Orakel skriver næringskoden til det egne feltet nace_industry og rører ikke industry.
• Boolske felt trenger eksplisitte valg. is_bankrupt opprettes med paret true/false, ellers svarer HubSpot INVALID_BOOLEAN_OPTION.
• Merkenavn beholdes. Berikelse via webhook overskriver ikke name på kort du allerede har.
• Advarselen om ukjent app ved installasjon er forventet. Appen er ikke gjennomgått, ikke utrygg.
• Én destinasjon per portal. Token hører til portalen. Installerer du den samme portalen på nytt, oppdateres destinasjonen du har.
• Synkronisering skjer når du vil. Trykk Synkroniser nå i Integrasjoner-fanen for å berike alle bedriftene på nytt. Ingen tidsgrense.
• Anbudsfeltene er kun for Norge. De vises i feltvelgeren når landfilteret står på NO eller alle land.

Se også

• Destinasjoner: endepunkter for destinasjoner og for å utløse push
• Brønnøysundregistrene: hovedkilde for firmadata og roller
• Regnskapsregisteret: kilde for regnskapstallene