API – Interface
for developers

eTermin's REST API let's developers quickly build applications which
enable access to the data in your eTermin account via HTTP and JSON.

This allows you to integrate online and desktop applications (3rd party
systems) seamlessly into your eTermin account. Almost every object in
eTermin (whether it is a contact, appointment, etc.) can be manipulated
using the API.

REST Basics

When you make a request to the eTermin's REST API you need to address each ressource by a unique URI. The operations which can be done with the resources can be defined using the HTTP verbs. Our API uses all four REST commands - GET, POST, PUT, DELETE.

GET

read resources

POST

create resources

PUT

edit resources

DELETE

delete resources

You can find the documentation of the resources here.


Authentication

The standard API URL to be used is "https://www.etermin.net/api/{resource}" In every request you must carry with it an API key (you find this key in the account settings), a signature and a randomly generated salt string.

The header of each request should contain following elements:

  • publickey
  • salt
  • signature

To generate the signature:
  • Generate a random string to get a new salt
  • Generate the signature by hashing the salt using SHA256 with the secret key as the key
  • base64 encode the signature

Please see the example below how to create the signature that you need to use in each request. 


	$publicKey = "your-api-key";
	$privateKey = "your-secret-key-never-share-it";
	// Generates a random string of ten digits
	$salt = mt_rand();
	// Computes the signature by hashing the salt with the secret key as the key
	$signature = hash_hmac('sha256', $salt, $privateKey, true);
	// base64 encode
	$encodedSignature = base64_encode($signature);
	echo "Your signature: " . $encodedSignature;
	$opts = [
		'http' => [
		  'method'  => "GET",
		  'header'  => "publickey: " . $publicKey . "\r\n" .
			  "salt: " . $salt . "\r\n" .
			  "signature: " . $encodedSignature . "\r\n"
		]
	];
	$result = file_get_contents('https://www.etermin.net/api/workingtimes?calendarid=1234', false, stream_context_create($opts));
	var_dump($result);



      var publicKey = "your-api-key";
      var privateKey = "your-secret-key-never-share-it";
      // Generate a new globally unique identifier for the salt
      var salt = System.Guid.NewGuid().ToString();
      // Initialize the keyed hash object using the secret key as the key
      HMACSHA256 hashObject = new HMACSHA256(Encoding.UTF8.GetBytes(privateKey));
      // Computes the signature by hashing the salt with the secret key as the key
      var signature = hashObject.ComputeHash(Encoding.UTF8.GetBytes(salt));
      // Base 64 Encode
      string encodedSignature = Convert.ToBase64String(signature);
      System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12;
      using (WebClient client = new WebClient())
      {
        client.Headers.Add("publickey", publicKey);
        client.Headers.Add("salt", salt);
        client.Headers.Add("signature", encodedSignature);
        byte[] response = client.UploadValues("https://www.etermin.net/api/contact", "POST", new NameValueCollection()
        {
          { "email", "email@example.com" },
          { "firstname", "Thomas" },
          { "lastname", "Mueller" }
        });
        string result = System.Text.Encoding.UTF8.GetString(response);
      }



	Dim publicKey = "your-api-key"
	Dim privateKey = "your-secret-key-never-share-it"
	' Generate a new globally unique identifier for the salt
	Dim salt = System.Guid.NewGuid().ToString()
	' Initialize the keyed hash object using the secret key as the key
	Dim hashObject As New HMACSHA256(Encoding.UTF8.GetBytes(privateKey))
	' Computes the signature by hashing the salt with the secret key as the key
	Dim signature = hashObject.ComputeHash(Encoding.UTF8.GetBytes(salt))
	' Base 64 Encode
	Dim encodedSignature = Convert.ToBase64String(signature)
	Console.WriteLine("Your signature: " & encodedSignature)
	Console.ReadKey()



import random
import hmac
import base64
import hashlib
 
publicKey = "your-api-key"
privatekey = "your-secret-key-never-share-it"
# Generates a random string of ten digits
salt = str(random.getrandbits(32))
# Encode the privatekey and salt
privatekeyentcoded = privatekey.encode(encoding='utf-8', errors='strict')
saltentcoded = salt.encode(encoding='utf-8', errors='strict')
# Computes the signature by hashing the salt with the secret key as the key
signature = hmac.new(privatekeyentcoded, msg=saltentcoded, digestmod=hashlib.sha256).digest()
# Encode the signature
encodedSignature = base64.b64encode(signature)
encodedSignatureString = encodedSignature.decode(encoding='utf-8', errors='strict')
print("Your signature: "+encodedSignatureString)

Push notifications - Webhooks

eTermin can send you a push notification once an appointment was created, modified or deleted on the eTermin platform. On your side you need to implement a handler that can read the variables. The supported variables you can find here. You can specify the address of the handler in the "Configuration->Integration - API->API" tab. In this tab you also will be able to send test notifications to your handler. Also, please take a look ath the examples below. 


	echo ‚APPOINTMENTUID‘ . ($_POST[„APPOINTMENTUID“]);
	echo ‚STARTDATETIMEUTC‘ . ($_POST[„STARTDATETIMEUTC“]);
	echo ‚ENDDATETIMEUTC‘ . ($_POST[„ENDDATETIMEUTC“]);
	echo ‚LASTNAME‘ . ($_POST[„LASTNAME „]);
	$command = ($_POST[„COMMAND“])
	switch ($command)
	{
		case ‚CREATED‘:
		echo ‚Your INSERT STATEMENT HERE‘;
		break;
		case MODIFIED‘:
		echo ‚Your UPDATE STATEMENT HERE‘;
		break;
		case ‚DELETED‘:
		echo ‚Your DELETE STATEMENT HERE‘;
		break;
	}


		
	public class Handler1 : IHttpHandler
	{
	  public void ProcessRequest(HttpContext context)
	  {
		try
		{
		  string appointmentUID = context.Request.Form["APPOINTMENTUID"].ToString();
		  DateTime startDateTimeUTC = DateTime.ParseExact(context.Request.Form["STARTDATETIMEUTC"], "yyyyMMdd HHmmss", CultureInfo.CurrentCulture);
		  DateTime endDateTimeUTC = DateTime.ParseExact(context.Request.Form["ENDDATETIMEUTC"], "yyyyMMdd HHmmss", CultureInfo.CurrentCulture);
		  DateTime startDateTime = DateTime.ParseExact(context.Request.Form["STARTDATETIME"], "yyyyMMdd HHmmss", CultureInfo.CurrentCulture);
		  DateTime endDateTime = DateTime.ParseExact(context.Request.Form["ENDDATETIME"], "yyyyMMdd HHmmss", CultureInfo.CurrentCulture);
		  DateTime bookingDateUTC = DateTime.ParseExact(context.Request.Form["BOOKINGDATEUTC"], "yyyyMMdd HHmmss", CultureInfo.CurrentCulture);
		  string salutation = context.Request.Form["SALUTATION"].ToString();
		  string lastName = context.Request.Form["LASTNAME"].ToString();
		  string firstName = context.Request.Form["FIRSTNAME"].ToString();
		  string email = context.Request.Form["EMAIL"].ToString();
		  string phone = context.Request.Form["PHONE"].ToString();
		  string street = context.Request.Form["STREET"].ToString();
		  string ZIP = context.Request.Form["ZIP"].ToString();
		  string town = context.Request.Form["TOWN"].ToString();
		  string birthday = context.Request.Form["BIRTHDAY"].ToString();
		  string notes = context.Request.Form["NOTES"].ToString();
		  string customerNumber = context.Request.Form["CUSTOMERNUMBER"].ToString();
		  string additional1 = context.Request.Form["ADDITIONAL1"].ToString();
		  string additional2 = context.Request.Form["ADDITIONAL2"].ToString();
		  string additional3 = context.Request.Form["ADDITIONAL3"].ToString();
		  string additional4 = context.Request.Form["ADDITIONAL4"].ToString();
		  string additional5 = context.Request.Form["ADDITIONAL5"].ToString();
		  string additional6 = context.Request.Form["ADDITIONAL6"].ToString();
		  string selectedAnswers = context.Request.Form["SELECTEDANSWERS"].ToString();
		  string bookingLanguage = context.Request.Form["BOOKINGLANGUAGE"].ToString();
		  string calendarName = context.Request.Form["CALENDARNAME"].ToString();
		  context.Response.StatusCode = 200;
		  context.Response.SuppressContent = true;
		  context.ApplicationInstance.CompleteRequest();
		  /*
			// Insert in DB
			string connectionString = "";
			System.Web.UI.WebControls.SqlDataSource dsInsert = new System.Web.UI.WebControls.SqlDataSource(connectionString, "");
			dsInsert.InsertCommand = "INSERT INTO ...";
			dsInsert.InsertParameters.Add("appointmentUID", appointmentUID);
			dsInsert.InsertParameters.Add("startDateTimeUTC", System.Data.DbType.Date, startDateTimeUTC.ToShortDateString());
			dsInsert.Insert();*/
		}
		catch (Exception e)
		{
		  System.Diagnostics.Debug.WriteLine(e.Message);
		  //context.Response.StatusCode = 400;
		  //context.Response.SuppressContent = true;
		  //context.ApplicationInstance.CompleteRequest();
		}
	  }
	}