Hitta rätt svar om HubSpots API

Så använder du dokumentation, Community och ändringsloggen för att komma vidare med en integration.

Illustration av dokumentation, en förstoringslins och kort för HubSpot Community och changelog.

Vilket fält ska integrationen uppdatera? Varför får vi ett behörighetsfel? Gäller forumsvaret från 2021 fortfarande? Den som arbetar med en HubSpot-integration behöver kunna hitta och bedöma tekniska svar utan att läsa hela utvecklardokumentationen. Här är en praktisk metod för CRM-ansvariga, beställare och andra som samarbetar med en integrationspartner.

Börja med att formulera vilken fråga du behöver lösa

Att söka på att en integration inte fungerar ger lätt många svar som handlar om något annat. Försök i stället beskriva vad ni försöker göra, vilket objekt som berörs och vad resultatet blir.

Exempelvis: en order finns i affärssystemet, men den motsvarande affären i HubSpot saknar rader efter en uppdatering. Det avgränsar frågan till rätt flöde och gör det möjligt att undersöka om felet gäller hämtning av underlag, radskapande, kopplingar eller behörigheter.

Ni behöver inte själva lösa problemet. En tydlig frågeställning gör både egen läsning och dialogen med partnern effektivare.

Använd rätt del av HubSpots underlag

På developers.hubspot.com finns tekniskt underlag om API:er, appar, autentisering och utvecklarverktyg. Guiderna hjälper dig att förstå upplägget. API-referensen beskriver de konkreta anropen, deras indata och möjliga svar.

HubSpots kunskapsbank beskriver i högre grad hur funktioner används och konfigureras i gränssnittet. Där kan du exempelvis undersöka vad användaren ska kunna se eller hur ett fält fungerar i vardagen.

HubSpot Communitys avdelning för API:er och integrationer är användbar när du vill se hur andra har löst en viss situation. Developer Changelog hjälper dig att hitta ändringar och tidsplaner som kan påverka en befintlig lösning.

Exempel 1: vad heter fältet egentligen?

I HubSpot kan användaren se en svensk etikett, medan API:et använder ett internt namn. Även val i en dropdown har interna värden som kan skilja sig från texten som visas.

Om fältet heter Prioritet i gränssnittet behöver utvecklaren därför veta vilket internt property-namn som gäller på just det objektet. Att ett liknande fält finns på kontakter betyder inte att det heter samma sak på affärer.

Börja med att kontrollera objektet och fältets inställningar. Vid behov kan partnern läsa objektets property-definitioner för att kontrollera namn, typ, tillåtna värden och om fältet går att skriva till. Skicka helst både etikett och internt namn när ni beskriver en mappning.

Exempel 2: uppgifterna finns men kopplingen saknas

En affär, ett företag och en kontakt kan alla finnas i HubSpot utan att vara kopplade till varandra som ni tänkt. I API-sammanhang kallas sådana relationer associations.

Frågan blir då inte bara om integrationen har skapat posterna. Den behöver också skapa rätt koppling mellan dem. På samma sätt räcker det inte att affärsrader finns någonstans i kontot; de behöver höra till rätt sammanhang.

Det hjälper att först förstå objektmappningen och skillnaden mellan products och line items. Då blir det lättare att välja rätt avsnitt i dokumentationen.

Exempel 3: ett felmeddelande pekar mot nästa kontroll

HTTP-status och feltext kan hjälpa till att avgränsa problemet. Ett 401-svar pekar ofta mot autentiseringen. Ett 403-svar kan handla om behörigheter eller åtkomst till funktionen. Ett 429-svar betyder att anropstakten behöver hanteras. Men statuskoden ensam förklarar inte alltid hela orsaken.

Spara därför även svarets feltext, tidpunkt och eventuell begäransreferens, exempelvis correlation ID när det finns. Partnern kan då koppla ihop uppgiften med rätt körning. Undvik att klistra in tokens eller verkliga kunduppgifter i ett publikt forum.

Våra guider om autentisering och driftövervakning ger mer sammanhang kring dessa frågor.

Bedöm om svaret fortfarande gäller

Ett gammalt forumssvar kan vara korrekt för den miljö det skrevs för och ändå vara fel väg för ett nytt projekt. Kontrollera därför vilket API, vilken appmodell och vilken produktfunktion svaret avser.

Begreppen private app och public app är ett bra exempel. HubSpots nyare utvecklarplattform gör att äldre instruktioner behöver läsas tillsammans med aktuella guider. Samma sak gäller förändringar i licenser, objekt och funktioner.

Titta även på skillnaden mellan annonserat, tillgängligt och obligatoriskt. Ett datum för när något ändras behöver inte vara samma sak som datumet när en äldre lösning slutar fungera. Följ länken till det officiella beskedet och kontrollera vilka konton som omfattas.

Ställ en fråga som går att besvara

Ett användbart underlag till partnern eller Community innehåller följande:

Vad du försöker åstadkomma och vilket objekt det gäller.
Förväntat resultat och vad som faktiskt händer.
Relevant felkod, feltext och tidpunkt.
Vilken metod eller dokumentationssida som använts.
Ett anonymiserat exempel med bara de uppgifter som behövs.

Om felet är återkommande, beskriv när det uppstår. Är det bara stora order? Bara uppdateringar? Bara poster som först skapats i det andra systemet? Sådana mönster kan vara mer värdefulla än en skärmbild av ett allmänt felmeddelande.

Testa hypotesen i ett avgränsat fall

När ni hittat ett möjligt svar bör det provas kontrollerat innan ett stort antal poster ändras. Bestäm vad som ska hända och kontrollera både den direkta ändringen och eventuella följdeffekter.

En lyckad API-körning visar att anropet accepterades. Verksamheten behöver också kontrollera att rätt post uppdaterades, att kopplingarna stämmer och att resultatet fungerar i arbetet.

Det är en av fördelarna med att samarbeta med en partner som har både tekniska komponenter och erfarenhet av processerna. Ni kan använda dokumentationen för att ställa bättre frågor, medan partnern ansvarar för att omsätta svaren till ett sammanhängande flöde.

Vanliga frågor om HubSpots tekniska underlag

Var hittar jag API-dokumentationen?

Börja på developers.hubspot.com och välj rätt API eller guide. Kontrollera att du läser om rätt objekt och den version som integrationen använder.

Kan jag lita på ett accepterat Community-svar?

Använd det som vägledning, men kontrollera datum och sammanhang mot aktuell officiell dokumentation. Ett accepterat svar kan gälla en äldre modell.

Behöver jag kunna programmera för att ha nytta av dokumentationen?

Nej. Begrepp som objekt, interna fältnamn, behörigheter och kopplingar hjälper även beställare att beskriva krav och förstå partnerns lösning.

Vad ska jag skicka vid ett integrationsfel?

Skicka förväntat och faktiskt resultat, tidpunkt och relevanta feluppgifter genom en överenskommen säker kanal. Lämna hemligheter och onödiga personuppgifter utanför.