Identifox API Tutorial

1. Ziel des Tutorials

In diesem Tutorial lernen Sie, wie Sie den Identifox-Api in Ihrer eigenen Anwendung verwenden. Sie können Dokumente hochladen, Unterzeichner und Beobachter einladen und den Unterzeichnungsprozess begleiten.

→ Wie erhalte ich einen API-Key?

2. Minimale Schritte:

  1. API-Key erhalten
  2. Access-Token generieren
  3. Neues Projekt erstellen
  4. Dokument erstellen oder erhalten
  5. Dokumente hochladen
  6. Unterzeichner definieren
  7. Unterzeichnungsprozess starten

2.1. API-Key erhalten

Besorgen Sie sich zunächst einen API-Key für Ihre Anwendung

→ Wie erhalte ich einen API-Key?

2.2. Access-Token generieren

Ihre Anwendung muss für jede Sitzung einen Access-Token generieren lassen.

→ berlinsms Client Credentials Flow.md

Diesen Access-Token benötigt Ihre Anwendung für jede der folgenden Schritte.

Senden Sie dazu den Access-Token jeweils als Bearer im Authorization-Header Authorization: Bearer <Access-Token>

2.3. Neues Projekt erstellen

Übermitteln Sie im Body der Route POST/v1/projects einen Json mit dem Namen eines neues Projektes

{
  "project_tag": "<Name des neuen Projektes>"
}

Im Response erhalten Sie die Id des neuen Projektes

{
  "project_id": <projectId>,
}

Speichern Sie die projectId für die weitere Verwendung.

.js
const fetch = require('node-fetch');

const accessToken = '<Access-Token>';

const url = 'https://example.com/v1/projects';
const headers = { 
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
};
const projectData = {
    'project_tag': 'Neues Projekt'
};
const response = await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(projectData)
});

const responseData = await response.json();
const projectId = responseData.project_id;
.py
import requests

access_token = '<Access-Token>'

url = 'https://example.com/v1/projects'
headers = {
    'accept': 'application/json',
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}
project_data = {
    'project_tag': 'Neues Projekt'
}

response = requests.post(url, headers=headers, json=project_data)
response_data = response.json()
project_id = response_data['project_id']
C#
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

string accessToken = "<Access-Token>";

url = 'https://example.com/v1/projects';

using HttpClient client = new HttpClient();

client.DefaultRequestHeaders.Add("accept", "application/json");
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
client.DefaultRequestHeaders.Add("Content-Type", "application/json");

var projectData = new
{
    project_tag = "Neues Projekt"
};        

string jsonData = JsonConvert.SerializeObject(projectData);
var content = new StringContent(jsonData, Encoding.UTF8, "application/json");

HttpResponseMessage response = await client.PostAsync(url, content);
string responseData = await response.Content.ReadAsStringAsync();
var responseJson = JsonConvert.DeserializeObject<dynamic>(responseData);
string projectId = responseJson.project_id;

Alle nachfolgenden Routen benötigen diese projectId im Pfad der Route

2.4. Dokumente erstellen oder erhalten

Sie müssen das zu unterzeichnende Dokument bereithalten. Woher Sie das Dokument bekommen, hängt von der Art der Anwendung ab. Sie können das Dokument zum Beispiel automatisch generieren lassen oder ihre Anwender bitten, es hochzuladen.

Für den nächsten Schritt gehen wir davon aus, dass sich das Dokument als PDF bereits in dem Filesystem ihrer Anwendung befindet.

2.5. Dokumente hochladen

Laden Sie das Dokument und übermitteln Sie es im Body der Route POST/v1/projects/{projectId}/documents.

Ersetzen Sie dazu die projectId im Pfad.

Der query-parameter "document_is_main" wird benötigt. Setzen Sie diesen auf "true"

.js
const filePath = <Pfad zum Dokument>; 
const fileBuffer = fs.readFileSync(filePath);

const url = 'https://example.com/v1/projects/${projectId}/documents?document_is_main=true';
const headers = { 
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/pdf'
};
await fetch(url, {
    method: 'POST',
    headers: headers,
    body: fileBuffer
});
.py
file_path = '<Pfad zum Dokument>'
with open(file_path, 'rb') as file:
    file_buffer = file.read()

url = f'https://example.com/v1/projects/{project_id}/documents?document_is_main=true'
headers = {
    'accept': 'application/json',
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/pdf'
}

requests.post(url, headers=headers, data=file_buffer)
C#
string filePath = "<Pfad zum Dokument>";

byte[] fileBuffer = await File.ReadAllBytesAsync(filePath);
string url = $"https://example.com/v1/projects/{projectId}/documents?document_is_main=true";
using HttpClient client = new HttpClient();

client.DefaultRequestHeaders.Add("accept", "application/json");
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
client.DefaultRequestHeaders.Add("Content-Type", "application/json");

var content = new ByteArrayContent(fileBuffer);
content.Headers.ContentType = new MediaTypeHeaderValue("application/pdf");

await client.PostAsync(url, content);

2.6. Unterzeichner definieren

Für jeden Unterzeicher sind die folgenden Daten erforderlich.

  • Name mit dem der Unterzeichner angesprochen wird
  • Email-Adresse durch die der Unterzeichner eingeladen wird
  • Telefonnummer mit der der Unterzeichner das Dokument unterzeichnet
  • die Rolle "signer"
  • der Type "extern"

Übermitteln Sie diese Daten als Json im Body der Route POST/v1/projects/{projectId}/members Ersetzen Sie wieder die projectId im Pfad.

.js
const url = `https://example.com/v1/projects/${projectId}/members`;
const headers = { 
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
};
const memberData = {
    member_name: "<Name des Unterzeichners>",
    member_phonenumber: "<Email-Adresse des Unterzeichners>",
    member_mailaddress: "<Telefonnummer des Unterzeichners>",
    member_role: "signer",
    member_type: "extern"
}
await fetch(url, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify(memberData)
});
.py
url = f'https://example.com/v1/projects/{project_id}/members'
headers = {
    'accept': 'application/json',
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}
member_data = {
    member_name: "<Name des Unterzeichners>",
    member_phonenumber: "<Email-Adresse des Unterzeichners>",
    member_mailaddress: "<Telefonnummer des Unterzeichners>",
    member_role: "signer",
    member_type: "extern"
}

requests.post(url, headers=headers, data=json.dumps(member_data))
C#
string url = $"https://example.com/v1/projects/{projectId}/members";

using HttpClient client = new HttpClient();

client.DefaultRequestHeaders.Add("accept", "application/json");
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
client.DefaultRequestHeaders.Add("Content-Type", "application/json");

string jsonData = JsonConvert.SerializeObject(new
{
    member_name = "<Name des Unterzeichners>",
    member_phonenumber = "<Email-Adresse des Unterzeichners>",
    member_mailaddress = "<Telefonnummer des Unterzeichners>",
    member_role = "signer",
    member_type = "extern"
});
StringContent content = new StringContent(jsonData, Encoding.UTF8, "application/json");

await client.PostAsync(url, content);

2.7. Unterzeichnungsprozess starten

Über die Route PUT/v1/projects/{projectId}/state/start starten Sie den Unterzeichnungsprozess, Alle Unterzeichner werden per Email informiert.

const url = `https://example.com/v1/projects/${projectId}/state/start`;
const headers = { 
    'accept': 'application/json',
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
};
await fetch(url, {
    method: 'PUT',
    headers: headers
});
.py
url = f'https://example.com/v1/projects/{project_id}/state/start'
headers = {
    'accept': 'application/json',
    'Authorization': f'Bearer {access_token}',
    'Content-Type': 'application/json'
}
requests.put(url, headers=headers)
C#
string url = $"https://example.com/v1/projects/{projectId}/state/start";

using HttpClient client = new HttpClient();

client.DefaultRequestHeaders.Add("accept", "application/json");
client.DefaultRequestHeaders.Add("Authorization", $"Bearer {accessToken}");
client.DefaultRequestHeaders.Add("Content-Type", "application/json");

await client.PutAsync(url, null);