Introduktion
Provet verksamhetssystem kan integreras med tredjepartsapplikationer med hjälp av verktyg som kallas REST API och webhooks.
Webhooks finns tillgängliga i Provet för att skicka notiser till tredjepartssystem om tillägg eller ändringar i data i Provet. Webhooks överför inte själva den ändrade datan, utan i stället information om vad som har ändrats genom att helt enkelt meddela tredjepartssystemet att en ändring har skett. Den faktiska datan kan därefter hämtas av tredjepartssystemet med hjälp av Provet REST API.
REST API är en kommunikationsmetod för att komma åt, redigera eller lägga till data som finns i Provet med hjälp av vilken tredjepartsapplikation som helst, programmässigt. Provet REST API ger de flesta av nyckeldatatypema i Provet som kan läsas eller manipuleras av andra system.
Kombinationen av Provet webhooks och REST API skapar unika möjligheter för att bygga integrerade lösningar. Leverantörer av andra system som känner till dessa tekniker kan enkelt integrera med datan i Provet verksamhetssystem genom att använda dessa tekniker.
Innan du kan börja använda Provet API:er behöver vi aktivera åtkomst till testmiljön för dig. Kontakta vår Partner Development Manager för att komma igång.
Vi skapar en testmiljö åt dig som du kan använda under den första utvecklingen. Vi skapar även en integration template med önskad OAuth2 grant type som ger åtkomst till din testmiljö. Det gör att du kan utveckla och testa din kod med vårt API.
Se vår developersida för API-dokumentation, API-schema och annan värdefull information som hjälper dig i utvecklingen.
Webhooks
Webhooks kan konfigureras och aktiveras i Settings > Integrations > Webhooks eller via en API endpoint. Om din integration använder webhooks rekommenderar vi att du automatiserar skapandet av webhooks via ett API. Se vår utvecklarsida för den uppdaterade List of Webhook Triggers och den detaljerade Webhooks guide.
REST API
Provet tillhandahåller REST API för att möjliggöra åtkomst till data som finns lagrad i Provet. API:t använder OAuth 2.0 authentication. Datan returneras i JSON-format.
För att kunna komma åt REST API behöver du en integration template.
Provet API support two grant types: Authorization Code och Client Credentials.
Authorization Code används för autentisering av användargränssnitt och för fall där användare kommer åt API:t som sig själva. PKCE stöds och rekommenderas starkt. Public clients MUST use PKCE.
Client Credentials används för backend-anslutning där tjänster kommunicerar direkt med en annan utan några användaråtgärder.
REST API kan nås genom att använda en URL som sammanställs enligt följande: https://<provet_environment>/<provet_id>/api/0.1/
URL:en för <provet_environment> skiljer sig lite mellan miljöerna. Det kan till exempel vara
provetcloud.com för EU-miljö
us.provetcloud.com för US-miljö
I URL:en <provet_id> finns det unika ID:t för Provet-instansen för ditt företag
Hela URL:en visas alltid i API settings i Provet Settings > Integrations > Open API access.
Provet REST API är browsable, vilket bör ge utvecklare goda möjligheter att bedöma hur dataöverföring fungerar.
Lägg till en integration applikation i Provet
När mallen har skapats kan integrationen ses i integration katalogen i Provet: Settings > Integrations > Open API access > Add Application. Katalogen listar tillgängliga integrationer och innehåller en kort beskrivning av vad varje integration gör. Om integrationen har fler installationsinstruktioner visas det också i katalogen.
Integrationerna kan ha begränsad synlighet: de kan begränsas till endast vissa Provet tenants eller i vissa länder. Tredjeparten som tillhandahåller integrationen kan välja hur brett integrationen ska vara synlig på tenants. När det finns begränsningar visas applikationen i integrationskatalogen endast på de tenants / i de länder där det är tillåtet.
Alternativ vid ny registrering av kund
Varje gång en ny kund registrerar sig för att använda en integration, det vill säga väljer den från integration katalogen i Provet (Add Application), skickas unika kundautentiseringsuppgifter till integrationsleverantören. Det finns två alternativ för att meddela en registrering av en ny kund, som kan väljas när en integration template skapas:
email
hookup URL
När integrationen bara används på en Provet-instans är e-post ett bra val: då kan personen som tar emot e-postmeddelandet konfigurera autentiseringsuppgifterna för integrationen och börja använda den. Å andra sidan, när integrationen används brett rekommenderas hookup URL och automatisering av tillägg av en ny kund.
Hookup URL lyssnar efter automatiska notiser om nya kunder. När en ny kund lägger till integrationen i Provet skickar orkestreringsverktyget automatiskt ett JSON-meddelande till den angivna URL:en. Det behövs ingen manuell interaktion, eftersom integrationen automatiskt parsar den nya kunden från JSON-meddelandet och lägger till deras autentiseringsuppgifter i deras kundtabell.
JSON schema för datan som skickas vid nya registreringar av integration:
{ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "required": [ "provet_id", "client_id", "client_secret", "algorithm", "authorization_grant_type", "client_type", "redirect_uris", "token_url", "authorize_url", "openid_autodiscovery_url" ], "properties": { "provet_id": { "type": "number", "description": "Provet ID of the tenant who added this integration." }, "client_id": { "type": "string" }, "client_secret": { "type": ["null", "string"] }, "algorithm": { "type": ["null", "string"], "description": "Signing algorithm used.", "examples": [null, "HS256", "RS256"] }, "authorization_grant_type": { "type": "string", "description": "Authorization flow used.", "examples": ["authorization_code", "client_credentials"] }, "client_type": { "type": "string", "description": "Client type.", "examples": ["confidential", "public"] }, "redirect_uris": { "type": "string", "description": "Space-separated list of callback URIs.", "examples": ["https://example.com/callback"] }, "token_url": { "type": "string", "description": "OAuth2.0 token endpoint URL." }, "authorize_url": { "type": "string", "description": "OAuth2.0 authorize endpoint URL." }, "openid_autodiscovery_url": { "type": ["null", "string"], "description": "OpenID autodiscovery URL. Null if integration does not use OpenID." }, "departments": { "type": "array", "items": { "type": "integer" }, "description": "Array of department IDs that have enabled this integration.", "examples": [[1, 2, 3]] }, "added_department": { "type": "integer", "description": "ID of the department that enabled this integration.", "examples": [3] }, "removed_department": { "type": "integer", "description": "ID of the department that disabled this integration.", "examples": [3] } }}
Behörigheter
När en ny integration applikation läggs till i Provet skapas automatiskt en virtuell användare och en behörighetsgrupp för integrationen. Den virtuella användaren kallas Integration <Integration name> och du hittar den i Settings > Users med filtret Virtual. Behörighetsgruppen har samma namn som integrationen.
Provet har stöd för automatiserad behörighetshantering, vilket minskar manuellt arbete och säkerställer konsekvens. Funktionen kallas "permission template" och läggs till på integration template. Kontakta Provet support för att få din permission template på din integration template.
När permission templates ändras uppdateras den tillhörande behörighetsgruppen i Provet automatiskt så att den matchar den senaste mallen. Tillagda behörigheter inkluderas och borttagna behörigheter exkluderas för att säkerställa synkronisering.
Om en permission template inte används har den som standard samma behörigheter som behörighetsgruppen Users.
Om en integration kräver andra behörigheter (vissa endpoints är nekade eller om du vill begränsa behörigheterna) måste behörigheterna redigeras. Kontrollera i Provet API schema vilka behörigheter varje endpoint behöver. Se även View and Manage User Permissions.
Integration kopplad till enhet
I Provet-miljöer med flera clinic locations kan en integration aktiveras eller inaktiveras separat för varje clinic location. Inställningen är endast informativ och skapar inga ytterligare kunddata. Listan över clinic locations där integrationen är aktiverad ingår i data payloaden för webhooks.
Varje gång integrationen aktiveras eller inaktiveras för en clinic location skickas en ny webhook som innehåller följande information:
Alla för närvarande aktiverade departments
Den department som lades till
Den department som togs bort
Den här funktionen behövs normalt inte. Om du behöver information om vilka clinic locations som använder eller inte använder din integration på samma Provet tenant, kontakta Provet support och fråga om du kan få den här funktionen aktiverad för din integration.
I Provet visar integrationer som är specifika för clinic locations en knapp Enable eller Disable längst ned i raden. Det gör att användare kan aktivera eller inaktivera integrationen för clinic location som de för närvarande tittar på. När en integration läggs till måste den aktiveras separat för varje clinic location. De clinic locations där integrationen är aktiverad visas bredvid knappen Disable. Om en integration inte stödjer aktivering specifik för clinic locations aktiveras den automatiskt på organisationsnivå.
Publicera en integration
När du har utvecklat och testat din integration och vill släppa den för publik användning kontaktar du Provet support för att få din Integration Template synlig för alla Provet-instansen. Om din integration inte är kundspecifik och är avsedd att användas i många Provet-instansen av många användare finns det vissa krav som måste uppfyllas innan den går live. Kraven är till för att göra onboarding av integrationen enklare och ge den information som Provet support behöver.
Skapa en kort video om din integration: hur den används och vad den gör.
Skapa en onboarding-instruktion som innehåller alla manuella steg som Provet-användaren behöver göra för att ta din integration i bruk. Stegen kan även inkludera de åtgärder som behövs i ditt system.
Se det här exemplet på onboarding-guide. Exempelintegration använder en webhook, men din integration kan behöva annan konfiguration som t.ex. ett Anpassat fält.
Tillhandahåll både videon och onboarding-guiden och meddela oss på vilka marknader / i vilka länder din integration ska vara synlig.
För att automatisera onboarding och minimera mänskliga fel rekommenderar vi att du använder följande funktioner för publika integrationer som används över många Provet tenants:
Permission template
Hookup URL i stället för email notification
Skapande av webhooks och Anpassade knappar via API endpoints (om tillämpligt)
Om du inte har dessa funktioner i bruk, kontakta Provet support för att konfigurera permission template och hookup URL åt dig. Om du har en specifik anledning att använda en notification email, meddela oss gärna.
För partners med platsbaserad fakturering krävs funktionen som är specifik för clinic location. Den måste konfigureras, testas och ingå i onboarding-instruktionerna innan integrationen kan gå live.