Introduzione
Il sistema di Gestione delle pratiche veterinarie Provet può essere integrato con applicazioni di terze parti utilizzando strumenti chiamati API REST e ganci web.
Ganci web sono disponibili in Provet per inviare notifiche ai sistemi di terze parti riguardo aggiunte o modifiche ai dati presenti in Provet. I ganci web non trasferiscono i dati effettivi modificati, ma invece trasferiscono l’informazione su cosa è cambiato semplicemente notificando al sistema di terze parti la modifica. I dati effettivi possono poi essere recuperati dal sistema di terze parti utilizzando l’API REST di Provet.
API REST è un metodo di comunicazione per accedere, modificare o aggiungere in modo programmatico i dati presenti nel programma Provet tramite qualsiasi applicazione di terze parti. L’API REST di Provet rende disponibili la maggior parte dei dati chiave di Provet per essere letti o manipolati da altri sistemi.
La combinazione dei ganci web di Provet e dell’API REST crea possibilità uniche per realizzare soluzioni integrate. Qualsiasi fornitore di altri sistemi che abbia familiarità con queste tecnologie può integrare facilmente i dati presenti nel sistema di Gestione delle pratiche veterinarie Provet utilizzando queste tecnologie.
Prima di poter iniziare a usare le API di Provet, dobbiamo abilitare l’accesso all’ambiente di test per te. Contatta il nostro Partner Development Manager per iniziare.
Creeremo per te un ambiente di test per l’accesso durante lo sviluppo iniziale. In più, ti forniremo un modello di integrazione con il tipo di grant OAuth2 desiderato per accedere al tuo ambiente di test. Questo ti consentirà di sviluppare e testare il tuo codice con la nostra API.
Consulta la nostra pagina per sviluppatori per la documentazione dell’API, lo schema dell’API e altre informazioni utili per supportare il tuo sviluppo.
Ganci web
I ganci web possono essere configurati e abilitati in Impostazioni > Integrazioni > Ganci web, oppure tramite un endpoint API. Se la tua integrazione usa ganci web, consigliamo di automatizzare la creazione dei ganci web tramite un’API. Per l’elenco aggiornato di List of Webhook Triggers e la guida dettagliata Webhooks guide, visita il nostro sito per sviluppatori.
API REST
Provet fornisce l’API REST per abilitare l’accesso ai dati archiviati in Provet. L’API utilizza autenticazione OAuth 2.0. I dati vengono restituiti nel formato JSON.
Per accedere all’API REST è necessario un modello di integrazione.
Il supporto dell’API Provet prevede due tipi di grant: Authorization Code e Client Credentials.
Authorization Code viene usato per autenticare le interfacce utente e i casi in cui gli utenti accedono all’API come se stessi. È supportato ed è fortemente consigliato PKCE. I client pubblici DEVONO usare PKCE.
Client Credentials viene usato per la connettività backend, quando i servizi comunicano direttamente con un altro senza alcuna azione da parte dell’utente.
L’API REST può essere accessibile utilizzando un URL compilato come segue: https://<provet_environment>/<provet_id>/api/0.1/
L’URL <provet_environment> è leggermente diverso per ciascun ambiente. Ad esempio può essere
provetcloud.com per l’ambiente UE
us.provetcloud.com per l’ambiente USA
Nell’URL <provet_id> è presente l’ID univoco dell’istanza Provet per la tua azienda
L’intero URL viene sempre mostrato nelle impostazioni API in Provet Impostazioni > Integrazioni > Accesso aperto all'API.
L’API REST di Provet è browsable, quindi dovrebbe consentire agli sviluppatori di valutare bene 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 in Provet: Impostazioni > Integrazioni > Accesso aperto all'API > Aggiungi applicazione. Il catalogo elenca le integrazioni disponibili e include una breve descrizione di cosa fa ciascuna integrazione. Se l’integrazione ha ulteriori istruzioni di configurazione, vengono mostrate anche nel catalogo.
Le integrazioni possono avere una visibilità limitata: possono essere limitate solo a determinati tenant Provet o in determinati paesi. Il fornitore di terze parti che fornisce l’integrazione può scegliere quanto ampiamente l’integrazione debba essere visibile sui tenant. In caso di limitazioni, l’applicazione viene mostrata nel catalogo delle integrazioni solo sui tenant / nei paesi in cui è consentita.
Opzioni in una registrazione di nuovo cliente
Ogni volta che un nuovo cliente si registra per usare un’integrazione, ovvero la sceglie dal catalogo delle integrazioni in Provet (Aggiungi applicazione), vengono inviate al fornitore dell’integrazione credenziali client univoche. Per notificare la registrazione di un nuovo cliente ci sono due opzioni, selezionabili quando si crea un modello di integrazione:
e-mail
hookup URL
Quando l’integrazione viene usata solo su una singola istanza Provet, e-mail è una buona scelta: in questo caso la persona che riceve l’e-mail può configurare i dettagli di autenticazione dell’integrazione e iniziare a usarla. D’altro canto, quando l’integrazione viene usata in modo esteso, si consiglia hookup URL e l’automazione dell’aggiunta di un nuovo cliente.
Hookup URL resta in ascolto di qualsiasi notifica automatizzata relativa a nuovi clienti. Quando un nuovo cliente aggiunge l’integrazione in Provet, lo strumento di orchestrazione invia automaticamente un messaggio JSON a quell’URL. Non è necessario alcun intervento umano: quando l’integrazione analizza automaticamente il nuovo cliente dal messaggio JSON e aggiunge le relative credenziali alla relativa tabella client.
Schema JSON dei dati inviati per nuove registrazioni di integrazione:
{ "$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 del tenant che ha aggiunto questa integrazione." }, "client_id": { "type": "string" }, "client_secret": { "type": ["null", "string"] }, "algorithm": { "type": ["null", "string"], "description": "Algoritmo di firma usato.", "examples": [null, "HS256", "RS256"] }, "authorization_grant_type": { "type": "string", "description": "Flusso di autorizzazione usato.", "examples": ["authorization_code", "client_credentials"] }, "client_type": { "type": "string", "description": "Tipo di client.", "examples": ["confidential", "public"] }, "redirect_uris": { "type": "string", "description": "Elenco di URI di callback separati da spazi.", "examples": ["https://example.com/callback"] }, "token_url": { "type": "string", "description": "URL dell’endpoint token OAuth2.0." }, "authorize_url": { "type": "string", "description": "URL dell’endpoint authorize OAuth2.0." }, "openid_autodiscovery_url": { "type": ["null", "string"], "description": "URL di autodiscovery OpenID. Null se l’integrazione non usa OpenID." }, "departments": { "type": "array", "items": { "type": "integer" }, "description": "Array di ID di struttura che hanno abilitato questa integrazione.", "examples": [[1, 2, 3]] }, "added_department": { "type": "integer", "description": "ID della struttura che ha abilitato questa integrazione.", "examples": [3] }, "removed_department": { "type": "integer", "description": "ID della struttura che ha disabilitato questa integrazione.", "examples": [3] } }}
Permessi
Quando viene aggiunta una nuova applicazione di integrazione in Provet, per l’integrazione vengono creati automaticamente un utente virtuale e un gruppo permessi. L’utente virtuale si chiama Integration <Integration name> e si trova in Impostazioni > Utenti usando il filtro Virtual. Il gruppo permessi ha lo stesso nome dell’integrazione.
Provet supporta la gestione automatizzata dei permessi, riducendo lo sforzo manuale e garantendo coerenza. Questa funzionalità si chiama 'permission template' ed è aggiunta al modello di integrazione. Contatta il supporto Provet per ottenere il tuo permission template da inserire nel modello di integrazione.
Quando i permission template vengono modificati, il gruppo permessi associato in Provet viene aggiornato automaticamente per corrispondere all’ultimo template. I permessi aggiunti vengono inclusi e quelli rimossi vengono esclusi per garantire la sincronizzazione.
Se un permission template non viene usato, ha per impostazione predefinita gli stessi permessi del gruppo permessi Utenti.
Se un’integrazione richiede permessi diversi (alcuni endpoint sono negati o vuoi limitare i permessi), i permessi devono essere modificati. Controlla nello schema API Provet quali permessi richiede ciascun endpoint. Vedi anche View and Manage User Permissions.
Integrazione specifica per Posizione della clinica
Negli ambienti Provet con più sedi della clinica, un’integrazione può essere abilitata o disabilitata separatamente per ciascuna Posizione della clinica. Questa impostazione è solo informativa e non crea alcun dato aggiuntivo per il cliente. L’elenco delle sedi della clinica in cui l’integrazione è abilitata è incluso nel payload dei dati del webhook.
Ogni volta che l’integrazione viene abilitata o disabilitata per una Posizione della clinica, viene inviato un nuovo webhook contenente le seguenti informazioni:
Tutte le strutture attualmente abilitate
La struttura che è stata aggiunta
La struttura che è stata rimossa
Questa funzionalità in genere non è necessaria. Se hai bisogno di sapere quali sedi della clinica usano o non usano la tua integrazione sullo stesso tenant Provet, contatta il supporto Provet e chiedi se puoi avere questa funzionalità abilitata per la tua integrazione.
In Provet, le integrazioni specifiche per Posizione della clinica mostrano un pulsante Abilitazione o Disattivare alla fine della riga. Questo consente agli utenti di abilitare o disabilitare l’integrazione per la Posizione della clinica che stanno visualizzando. Dopo che un’integrazione è stata aggiunta, deve essere abilitata separatamente per ciascuna Posizione della clinica. Le sedi della clinica in cui l’integrazione è abilitata vengono visualizzate accanto al pulsante Disattivare. Se un’integrazione non supporta l’attivazione specifica per Posizione della clinica, viene attivata automaticamente a livello di organizzazione.
Pubblicare un’integrazione
Dopo aver sviluppato e testato l’integrazione e desideri renderla disponibile al pubblico, contatta il supporto Provet per far sì che il tuo modello di integrazione sia visibile a tutte le istanze Provet. Se la tua integrazione non è specifica per il cliente ed è pensata per essere usata in molte istanze Provet da molti utenti, prima di passare in produzione è necessario soddisfare alcuni requisiti. Questi requisiti servono a rendere più semplice l’onboarding dell’integrazione e a fornire le informazioni necessarie per il supporto Provet.
Crea un breve video sulla tua integrazione: come usarla e cosa fa.
Crea un’istruzione di onboarding che contenga tutte le fasi manuali necessarie da parte dell’utente Provet per mettere in uso la tua integrazione. I passaggi possono includere anche le azioni necessarie nel tuo sistema.
Vedi questo esempio di guida per l’onboarding. L’esempio di integrazione usa un solo webhook, ma la tua integrazione potrebbe richiedere anche altre configurazioni, come ad esempio un campo personalizzato, ecc.
Fornisci sia il video sia la guida di onboarding e comunicaci in quali mercati / in quali paesi la tua integrazione deve essere visibile.
Per automatizzare l’onboarding e ridurre al minimo gli errori umani, consigliamo di usare le seguenti funzionalità per le integrazioni pubbliche utilizzate in molti tenant Provet:
permission template
Hookup URL invece della notifica e-mail
Creazione di ganci web e pulsanti personalizzati tramite endpoint API (se applicabile)
Se queste funzionalità non sono in uso, contatta il supporto Provet per configurare per te permission template e hookup URL. Se hai un motivo specifico per usare una notifica e-mail, comunicacelo.
Per i partner con fatturazione basata sulla posizione, è necessaria la funzionalità specifica per Posizione della clinica. Deve essere configurata, testata e inclusa nelle istruzioni di onboarding prima che l’integrazione possa essere pubblicata.