Tutorial zur Identifox API

1 Ziel des Tutorials

In diesem Tutorial lernen Sie, wie Sie die Identifox API in Ihrer eigenen Software verwenden. Sie können damit innerhalb Ihrer eigenen Anwendungsumgebung Dokumente uploaden, Unterzeichner und Beobachter einladen und den Unterzeichnungsprozess begleiten.

2 Von der API bis zum Unterzeichnungsprozess in wenigen Schritten

API-Key erhalten
Access-Token generieren
Neues Projekt erstellen
Dokument erstellen oder erhalten
Dokumente hochladen
Unterzeichner definieren
Unterzeichnungsprozess starten

2.1 API-Key erhalten

Besorgen Sie sich zunächst einen API-Key für Ihre Anwendung. Einen Link zum entsprechenden Tutorial finden Sie hier:

→ Wie erhalte ich einen API-Key?

2.2 Access-Token generieren

Ihre Anwendung muss für jede Sitzung einen Access-Token generieren lassen. Eine entsprechende Dokumentation finden Sie hier:

→ berlinsms Client Credentials Flow.md

Auf diesen Access-Token greift Ihre Anwendung in jedem der folgende Schritte zurück.

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 Projekts.

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

Im Response erhalten Sie die Id des neuen Projekts.

{
  "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']

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 erfordern diese projectId im Pfad der Route.

2.4 Dokumente erstellen oder erhalten

Halten Sie das zu unterzeichnende Dokument bereit. Woher Sie das Schriftstück 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 bereits als PDF im 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.

Setzen Sie den erforderlichen Query-Parameter "document_is_main" 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)

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

Definieren Sie jeden Unterzeicher mit den folgenden Daten:

Name des Unterzeichners
E-Mail Adresse, um den Unterzeichner einzuladen
Telefonnummer, mit der der Unterzeichner das Dokument signieren soll
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))

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 E-Mail 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)

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);