Collegamenti rapidi
Introduzione
Il sistema di gestione degli studi veterinari Provet può essere integrato con applicazioni di terze parti utilizzando strumenti chiamati REST API e webhook.
I webhook sono disponibili in Provet per inviare notifiche a sistemi di terze parti su aggiunte o modifiche dei dati all'interno di Provet. I webhook non trasferiscono i dati effettivamente modificati, bensì le informazioni su ciò che è cambiato, notificando semplicemente la modifica al sistema di terze parti. I dati effettivi possono poi essere recuperati dal sistema di terze parti utilizzando l'API REST di Provet.
REST API è un metodo di comunicazione per accedere, modificare o aggiungere ai dati residenti in Provet in modo programmatico da qualsiasi applicazione di terze parti. L'API REST di Provet offre la possibilità di leggere o manipolare la maggior parte dei dati chiave di Provet da parte di altri sistemi.
La combinazione di webhooks Provet & REST API crea possibilità uniche per la creazione di soluzioni integrate. Qualsiasi fornitore di altri sistemi che abbia familiarità con queste tecnologie può facilmente integrarsi con i dati che risiedono nel sistema di gestione degli studi veterinari Provet utilizzando queste tecnologie.
Prima di poter iniziare a utilizzare le API Provet, è necessario abilitare l'accesso all'ambiente di prova. Per iniziare, contattate il nostro responsabile dello sviluppo dei partner https://share.hsforms.com/1ttEt76KfTICnJ4FqFseI1w3iyes .
Creeremo un ambiente di prova a cui potrete accedere durante lo sviluppo iniziale. Creeremo anche un modello di integrazione con il tipo di concessione OAuth2 desiderato per l'accesso all'ambiente di prova. Questo vi permetterà di sviluppare e testare il vostro codice con la nostra API.
Consultate la nostra pagina per gli sviluppatori per la documentazione dell'API, lo schema dell'API e altre preziose informazioni per aiutarvi nello sviluppo.
Ganci web
I webhook possono essere configurati e abilitati in Settings > General > Integrations > Webhooks, o tramite un endpoint API. Se l'integrazione utilizza i webhook, si consiglia di automatizzare la creazione di webhook tramite un'API. Consultate il nostro sito per sviluppatori per l'elenco aggiornato dei trigger webhook e la guida dettagliata dei webhook.
API REST
Provet fornisce l'API REST per consentire l'accesso ai dati memorizzati in Provet. L'API utilizza l'autenticazione OAuth 2.0. I dati vengono restituiti nel formato JSON.
Per accedere all'API REST è necessario un modello di integrazione.
L'API Provet supporta due tipi di sovvenzioni: Authorization Code e Client Credentials.
Il codice di autorizzazione viene utilizzato per l'autenticazione delle interfacce utente e nei casi in cui gli utenti accedono all'API come se stessi. PKCE è supportato e altamente raccomandato. I client pubblici DEVONO utilizzare PKCE.
Le credenziali del client sono utilizzate per la connettività del backend, in cui i servizi comunicano direttamente con altri senza che l'utente compia alcuna azione.
Si può accedere all'API REST utilizzando un URL compilato come segue: https://<provet_environment>/<provet_id>/api/0.1/
<provet_environment> L'URL differisce un po' per ogni ambiente. Può essere, ad esempio
provetcloud.com per l'ambiente UE
us.provetcloud.com per l'ambiente statunitense
Nell'URL <provet_id> è l'ID univoco dell'istanza Provet per la vostra azienda.
L'intero URL è sempre mostrato nelle impostazioni API di Provet Impostazioni > Integrazioni > Accesso API aperto.
Provet REST API è navigabile, il che dovrebbe consentire agli sviluppatori di valutare le possibilità di trasferimento dei dati.
Aggiungere un'applicazione di integrazione in Provet
Una volta creato il modello, l'integrazione è visibile nel catalogo delle integrazioni di Provet: Impostazioni > Integrazioni > Accesso API aperto > Aggiungi applicazione. Il catalogo elenca le integrazioni disponibili e contiene una breve descrizione delle funzioni di ciascuna integrazione. Se l'integrazione ha ulteriori istruzioni per la configurazione, anche queste vengono visualizzate nel catalogo.
Le integrazioni possono avere una visibilità limitata: possono essere riservate solo a determinati tenant Provet o in determinati Paesi. La terza parte che fornisce l'integrazione può scegliere in che misura l'integrazione deve essere visibile ai tenant. In caso di restrizioni, l'applicazione viene visualizzata nel Catalogo delle integrazioni solo su quei tenant o in quei Paesi in cui è consentita.
Opzioni nella registrazione di un nuovo cliente
Ogni volta che un nuovo cliente si registra per utilizzare un'integrazione, ossia la sceglie dal catalogo delle integrazioni in Provet (Aggiungi applicazione), le credenziali uniche del cliente vengono inviate al fornitore dell'integrazione. Esistono due opzioni per notificare la registrazione di un nuovo cliente, che possono essere scelte quando si crea un modello di integrazione:
e-mail
URL di aggancio
Quando l'integrazione viene utilizzata solo su un'istanza di Provet, l'e-mail è una buona scelta: la persona che riceve l'e-mail può configurare i dettagli di autenticazione all'integrazione e iniziare a utilizzarla. D'altra parte, quando l'integrazione è ampiamente utilizzata, si consiglia di utilizzare l'URL di hookup e di automatizzare l'aggiunta di un nuovo cliente.
L'URL di aggancio è in ascolto per eventuali notifiche automatiche di nuovi clienti. Quando un nuovo cliente aggiunge l'integrazione in Provet, lo strumento di orchestrazione invia automaticamente un messaggio JSON a quell'URL. Non è necessaria alcuna interazione umana, poiché l'integrazione analizza automaticamente il nuovo cliente dal messaggio JSON e aggiunge le sue credenziali alla tabella dei clienti.
Schema JSON per i dati inviati per le registrazioni di nuove integrazioni:
{ "$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] } }}Permessi
Quando si aggiunge una nuova applicazione di integrazione a Provet, vengono automaticamente creati un utente virtuale e un gruppo di autorizzazioni per l'integrazione. L'utente virtuale si chiama Integrazione <Nome dell'integrazione> e può essere trovato in Impostazioni > Utenti usando il filtro Virtuale. Il gruppo di autorizzazioni ha lo stesso nome dell'integrazione.
Provet supporta la gestione automatizzata dei permessi, riducendo lo sforzo manuale e garantendo la coerenza. Questa funzione si chiama "modello di autorizzazione" e viene aggiunta al modello di integrazione. Contattate il supporto Provet per ottenere il modello di autorizzazione sul vostro modello di integrazione.
Quando i modelli di autorizzazione vengono modificati, il gruppo di autorizzazioni associato in Provet viene automaticamente aggiornato per corrispondere al modello più recente. I permessi aggiunti vengono inclusi e quelli rimossi vengono esclusi per garantire la sincronizzazione.
Se un modello di autorizzazione non viene utilizzato, ha gli stessi permessi di default del gruppo di autorizzazioni Users.
Se un'integrazione richiede autorizzazioni diverse (alcuni endpoint sono negati o si desidera limitare le autorizzazioni), le autorizzazioni devono essere modificate. Controllare dallo schema Provet API quali autorizzazioni sono necessarie per ogni endpoint. Vedere anche Visualizzare e gestire le autorizzazioni degli utenti.
Integrazione specifica del dipartimento
Negli ambienti Provet con più sedi di cliniche, l'integrazione può essere attivata o disattivata separatamente per ciascuna sede di clinica. Questa impostazione è solo informativa e non crea dati aggiuntivi per i clienti. L'elenco delle sedi delle cliniche in cui l'integrazione è abilitata è incluso nel payload dei dati del webhook.
Ogni volta che l'integrazione viene attivata o disattivata per una sede della clinica, viene inviato un nuovo webhook contenente le seguenti informazioni:
Tutti i reparti attualmente abilitati
Il reparto che è stato aggiunto
Il reparto che è stato rimosso
Questa funzionalità non è normalmente richiesta. Se avete bisogno di informazioni sulle sedi delle cliniche che utilizzano o non utilizzano la vostra integrazione sullo stesso tenant Provet, contattate il supporto Provet e chiedete se è possibile abilitare questa funzionalità per la vostra integrazione.
In Provet, le integrazioni specifiche per la sede della clinica visualizzano un pulsante Abilita o Disabilita alla fine della riga. Ciò consente agli utenti di abilitare o disabilitare l'integrazione per la sede della clinica che stanno visualizzando. Dopo l'aggiunta di un'integrazione, questa deve essere abilitata separatamente per ogni sede della clinica. Le sedi delle cliniche in cui l'integrazione è abilitata sono visualizzate accanto al pulsante Disabilita. Se un'integrazione non supporta l'attivazione specifica per la sede della clinica, viene attivata automaticamente a livello di organizzazione.
Rilascio di un'integrazione
Quando avete sviluppato e testato la vostra integrazione e volete renderla pubblica, contattate il supporto Provet per rendere visibile il vostro modello di integrazione a tutte le istanze Provet. Se l'integrazione non è specifica per il cliente e deve essere utilizzata in molte istanze di Provet da molti utenti, ci sono alcuni requisiti da soddisfare prima della messa in funzione. Questi requisiti hanno lo scopo di rendere più semplice l'onboarding dell'integrazione e di fornire le informazioni necessarie al supporto Provet.
Create un breve video sulla vostra integrazione: come si usa e cosa fa.
Creare un'istruzione di onboarding che contenga tutti i passaggi manuali necessari all'utente Provet per utilizzare la vostra integrazione. I passaggi possono includere anche le azioni necessarie nel vostro sistema.
Vedere questo esempio di guida all'onboarding. L'integrazione di esempio utilizza un webhook, ma la vostra integrazione potrebbe richiedere altre configurazioni, come un campo personalizzato, ecc.
Forniteci sia il video che la guida all'onboarding e fateci sapere in quali mercati/paesi dovrebbe essere visibile la vostra integrazione.
Per automatizzare l'onboarding e ridurre al minimo gli errori umani, ti consigliamo di utilizzare le seguenti caratteristiche per le integrazioni pubbliche che sono utilizzate in molti inquilini Provet:
Modello di autorizzazione
URL di aggancio invece della notifica via e-mail
Creazione di webhook e pulsanti personalizzati tramite endpoint API (se applicabile)
Se non si utilizzano queste funzioni, contattare l'assistenza Provet per configurare il modello di autorizzazione e l'URL di aggancio. Se avete un motivo specifico per utilizzare un'e-mail di notifica, fatecelo sapere.
Per i partner con fatturazione basata sulla posizione, è necessaria la funzione specifica per la posizione della clinica. Deve essere configurata, testata e inclusa nelle istruzioni di onboarding prima che l'integrazione possa essere avviata.