Den här artikeln är till dig som bygger en integration mot Kaddio. Med en integration kan en Kaddio-användare öppna ditt system direkt från en klient, antingen via en länk i klientmenyn eller via en vy som bäddas in på klientens översikt. Data hämtas och skapas i Kaddio via GraphQL-API:et.

Så fungerar det

Kaddio registrerar ditt företag som integratör.
Kundens administratör skapar en API-token som är kopplad till dig och klistrar in den i ditt gränssnitt.
Du registrerar integrationen via GraphQL med den token du fått. Integrationen är då väntande och inaktiv.
Kundens administratör granskar och godkänner integrationen i Kaddio. Först då blir den aktiv.
När en användare öppnar integrationen anropar Kaddio din server, och du svarar med en adress som användaren skickas till eller som visas i en ruta på klientens översikt.

Kom igång

1. Bli registrerad som integratör

Kontakta Kaddio och ange företagsnamn samt de exakta domännamn (hostnamn) som din integration ska använda, till exempel api.example.se och app.example.se. Kaddio skickar bara användare och anrop till dessa domäner. Jokertecken (*.example.se) och IP-adresser kan inte användas. Du får en integratörsnyckel av Kaddio.

2. Få en API-token från kunden

Kundens administratör går till Inställningar > API, klickar på Ny integration under Integrationer och väljer dig som integratör. Då skapas en API-token som är kopplad till dig. Kopplingen till dig kan inte ändras i efterhand, och token fungerar bara mot GraphQL-API:et.

Token visas bara en gång, och den ger åtkomst till kundens Kaddio. Bygg därför in ett fält i ditt eget gränssnitt, till exempel på en inställningssida för Kaddio-kopplingen, där kunden kan klistra in token direkt. Be inte kunden skicka token via e-post, chatt eller annan kommunikation som inte är krypterad eller skyddad, och spara den säkert hos dig så snart du fått den.

3. Anropa GraphQL

Skicka anrop till kundens Kaddio-adress med sökvägen /graphql, till exempel https://kundnamn.kaddio.com/graphql, och lägg token i headern Authorization.

4. Registrera integrationen

mutation {
  upsertIntegration(
    name: "Exempel journalsystem"
    icon: "fa-heart-pulse"
    clientLinkUrl: "https://app.example.se/kaddio/lank"
    clientOverviewUrl: "https://app.example.se/kaddio/oversikt"
    graphqlEndpoints: ["findUser", "createContact"]
  ) {
    _id
    status
    isEnabled
    secret
  }
}

clientLinkUrl ger en länk i klientmenyn som skickar användaren till ditt system. clientOverviewUrl ger en vy som bäddas in på klientens översikt. Båda är valfria, och en integration kan också bara använda API:et.
icon är valfri och anges som en enda Font Awesome-klass, till exempel fa-heart-pulse. Ikonen visas intill integrationen i klientmenyn och på klientens översikt. Utan ikon används en standardikon. Andra värden än en enda klass som börjar med fa- nekas.
Adresserna måste använda https, standardporten och ligga på en av dina registrerade domäner. Adresser med användarnamn eller lösenord godtas inte.
graphqlEndpoints är de GraphQL-endpoints du behöver i Kaddios API, till exempel findUser för att hämta uppgifter om klienten eller användaren och createContact för att skapa en kontakt. Okända namn nekas.
Det finns en integration per kund och integratör. Anropar du upsertIntegration igen uppdateras den befintliga.
secret returneras bara en gång, när integrationen skapas. Spara den säkert. Kundens administratör kan skapa en ny hemlighet om den försvinner.
Med findIntegrations ser du dina integrationer och deras status, och med removeIntegration(id: ...) tar du bort en.

Godkännande och behörigheter

Du kan aldrig själv aktivera en integration. Kundens administratör godkänner den under Inställningar > API och ser då vilka adresser och GraphQL-endpoints du har begärt.

Innan godkännandet kan din token bara anropa findIntegrations, upsertIntegration och removeIntegration.
När integrationen är godkänd och aktiv kan din token anropa de godkända endpoints du angav, och inga andra.
Ändrar du adresserna eller listan med endpoints måste kunden godkänna igen, och till dess nekas dina anrop utanför de tre hanteringsanropen. Att bara byta namn eller ikon kräver inget nytt godkännande.
Om kunden stänger av integrationen, eller Kaddio stänger av dig som integratör, slutar anropen fungera tills den är godkänd och aktiv igen.
Kundens administratör kan dessutom begränsa token ytterligare, men aldrig ge den fler rättigheter än de godkända.

Anrop från Kaddio till dig

När en användare öppnar länken eller översikten skickar Kaddio ett anrop från sin server till den adress du registrerat för platsen:

POST https://app.example.se/kaddio/lank
Content-Type: application/json
X-Kaddio-Secret: <din hemlighet>{
  "integrationId": "...",
  "orgId": "...",
  "placement": "clientLink",
  "client": { "id": "..." },
  "actor": { "id": "..." }
}

placement är clientLink eller clientOverview.
client.id är klienten som öppnades och actor.id är användaren som klickade. Båda är profil-id:n i Kaddio. Övrig information om klienten eller användaren hämtar du via GraphQL med dina godkända endpoints.
Kontrollera att X-Kaddio-Secret stämmer med din hemlighet (helst med en jämförelse som tar lika lång tid oavsett svar) och neka allt annat.

Ditt svar

Svara inom 5 sekunder med status 2xx och högst 4 kB JSON:

{ "url": "https://app.example.se/session/abc123" }

Adressen måste använda https och ligga på en av dina registrerade domäner, annars avvisas den.
Gör adressen engångs- och kortlivad. Användaren skickas dit (länk i klientmenyn) eller får den inbäddad (översikten).
Kaddio följer inte omdirigeringar på anropet.

Inbäddad vy på klientöversikten

Vyn visas i en iframe med begränsningar (sandbox med skript, formulär, same-origin och popup-fönster) och utan att skicka referrer. Din sida måste tillåta att den visas i en iframe från Kaddio genom att inte sätta X-Frame-Options till DENY eller SAMEORIGIN och genom att tillåta Kaddios adress i Content-Security-Policy: frame-ancestors. Förlita dig inte på tredjepartskakor i vyn.

Gränser och felsökning

En användare kan öppna en integration högst 30 gånger per minut.
Svarar du inte i tid, svarar med något annat än 2xx eller ogiltig JSON, eller returnerar en adress utanför dina domäner, visar Kaddio ett felmeddelande för användaren och avbryter.
Integrationen visas bara för användare som har rätt att se klienten, och bara när den är godkänd och aktiv.
Kaddio loggar varje öppning (id:n, plats och resultat, utan personuppgifter) för felsökning.

Tips: Logga aldrig hemligheten eller API-token, och lagra dem som hemligheter hos dig.

Bygga en integration mot Kaddio (för integratörer)