Vitre API Integration

Interacting through API

This document describes the REST API of Vitre that allows outer system to interact with Vitre data and perform actions in it.

Authentication

Generating an API Key

API keys can be generated by any admin within the tenant company.

To create an API key, the user JWT token retrieved from the Vitre Portal must be utilized. If you need assistance in obtaining the token from the Portal, please contact our customer services for guidance.

Once you have the JWT token, you can establish a connection to our internal API using this URL:

• https://internalapi.vitre.io/swagger/index.html#/PublicApiKey/post_PublicApiKey

Upon successful completion, the response will include two parameters:

1. key-id - This serves as an identifier for the generated API key.

2. key - A confidential key that will not be displayed again. It is essential to copy and securely store this key on your end.

For subsequent requests to the REST API, both these parameters should be used as headers:

Supported Operations

Our API provides access to various endpoints, each enabling different actions and interactions with Vitre (Prescription Authorization System).

For each entity exposed by the system, there are common operations available:

1. POST: This allows for entity creation.
2. PUT/PATCH: These methods facilitate entity modification.

However, it's important to note that deletion is not supported by the API.

In the system, every entity possesses an internal ID for identification purposes. However, to interact with the Vitre API, you must assign a unique external identifier to each entity using the "externalId" property. This property is a string field that should be unique per entity within the tenant's context.

For comprehensive information about all the available endpoints, you can refer to the Swagger documentation, which documents and details the functionalities provided by each endpoint:

• https://publicapi.vitre.io/swagger/index.html

Swagger can be employed to execute commands for testing purposes.

Additionally, Swagger allows you to view the request and response Schemes for each endpoint, providing valuable insight into the data structures and formats to be utilized during testing and integration.

How to Work With Entities

We will outline two potential approaches for implementing an interface with Vitre. However, a key consideration is to ensure that when making modifications to entities, you do not override fields that are internally managed by processes defined in Vitre. This suggestion is provided as a guideline, but you are free to choose the approach that best fits your requirements.

For additional information or any queries, do not hesitate to reach out to our Customer Support team, who will be more than happy to assist you.

Snapshot Update

In this approach, you should use the POST action when creating new entities. After the entities are successfully created, you should follow this cycle of actions:

1. Initiate a GET request to retrieve all the available entities of the requested type.
2. Modify the relevant fields for each entity based on the response.
3. Perform a PUT operation on each updated entity to apply the changes.

Delta Update

In this approach, you will create new entities using the POST action. After the creation process, for each updated entity on your side, generate a PATCH request to apply specific changes that need to be performed in the current cycle. This approach offers faster and lighter requests to the API, reducing the likelihood of affecting internally managed data.

Updating custom properties

Vitre enables each tenant to have custom properties for entities, allowing them to store specific data not supported by Vitre out of the box.

When making GET requests to the API, these custom properties will be included in a property called "customPropertiesValues," which will store all the custom properties in an array. You can also modify these custom properties using the PUT and PATCH commands to update the relevant entity's data.

To update an entity, utilize the constant "propertyId" associated with the specific property per tenant.

For instance, when performing a POST or GET operation, include a "customPropertyValues" object containing key-value pairs of the custom properties that need to be modified or retrieved for that entity. This approach ensures smooth management and interaction with custom properties for each tenant within the system.

Patch Command

This command enables you to update specific properties within a particular entity.

To utilize this command, you need to pass an array of patch commands, where each command comprises multiple parameters. These parameters define the precise modifications you want to apply to the entity.

• "value" - This represents the new value you want to assign to the property.

• "path" - Refers to the location of the property within the entity. It must begin with a "/" symbol. For instance, "/displayName". In the case of custom properties, use this format - "/customPropertyValues/{customPropertyId}".

• "op" - We support the "replace" operation, which means it will replace the existing value with the new one.

• "from" - This field is not utilized in this context and can be left empty.