Backend integrieren

Die Checkliste für den Aufruf von Human Plugin aus einem serverseitigen Dienst.

Markdown

Human Plugin ist ausschließlich für den Aufruf durch Ihr Backend gedacht. Stellen Sie es nicht Browsern oder mobilen Apps zur Verfügung: Es verfügt über keine eingehende Authentifizierung.

1. Erstellen

curl

curl -X POST "$HUMAN_PLUGIN_URL/v1/processes" \
  -H 'Content-Type: application/json' \
  -d '{
    "flow": "api+humantoken",
    "clientId": "client-a",
    "correlationId": "onboarding-001",
    "credential": { "type": "DUI_TYPE_NG_BVN", "value": "<document number>" },
    "imageBase64": "<base64 selfie>"
  }'

Node.js

const response = await fetch(`${process.env.HUMAN_PLUGIN_URL}/v1/processes`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    flow: 'api+humantoken',
    clientId: 'client-a',
    correlationId: 'onboarding-001',
    credential: { type: 'DUI_TYPE_NG_BVN', value: documentNumber },
    imageBase64,
  }),
  signal: AbortSignal.timeout(60_000),
});

const body = await response.json();
if (response.status !== 201) {
  // body is { message, details }
  throw new Error(`Human Plugin ${response.status} ${body.message}`);
}
const { id, state, data } = body;

Setzen Sie das Timeout Ihres Clients auf mindestens 60 Sekunden: Die Verarbeitung eines Create kann bis zu 30 Sekunden dauern, zuzüglich der Datenbankschritte. Die id kommt nur in der Create-Antwort, daher kann ein Client, der zu früh aufgibt, einen Prozess verlieren, der trotzdem abgeschlossen wird.

2. Speichern, was Sie später brauchen

Speichern	Warum
id	Das Handle für GET
Journey-token und link, falls vorhanden	Werden nur in der Create-Antwort zurückgegeben und nie von Human Plugin gespeichert
Ihre correlationId	Sie muss eindeutig sein. Erzeugen Sie für jeden Versuch eine neue, auch bei Wiederholungen, außer nach einem 503

3. Das Ergebnis lesen

1. Wenn state den Wert PROCESS_STATE_FINISHED hat, lesen Sie das Ergebnis aus data: humanToken (oder humanTokenMatch bei einer Revalidierung), liveness und ndocs. Abgeschlossen bedeutet nicht genehmigt.
2. Wenn state den Wert PROCESS_STATE_CREATED hat, pollen Sie GET /v1/processes/{id} mit Backoff, bis sich der Wert ändert. Nichts anderes bringt den Prozess voran.
3. Wenn state den Wert PROCESS_STATE_FAILED hat, wurde der Prozess ohne Ergebnis beendet. Starten Sie einen neuen, sofern Ihr Flow das erlaubt.

4. Die Intelligence nutzen

data.ndocs zeigt Ihnen, was die Person bei Ihnen getan hat: bei wie vielen Ihrer Clients und mit wie vielen Dokumenten sie erfasst wurde und wann. Beziehen Sie dies zusammen mit dem Human Token in Ihre Entscheidung ein und beachten Sie, dass der Wert fehlen kann. Siehe Intelligence.

5. Fehlerbehandlung

• Wiederholen Sie 500 oder 502 bei Create nicht automatisch. Siehe Fehler und Wiederholungen.
• Wiederholen Sie 503 bei Create mit derselben correlationId sowie jeden Fehler bei GET mit Backoff.
• 409 bedeutet, dass die correlationId bereits vergeben ist. Verwenden Sie niemals eine correlationId erneut.
• Lösen Sie bei wiederholten 503 einen Alarm aus: Es bedeutet, dass Human Plugin seine Datenbank nicht erreichen kann.

Betriebliche Erwartungen

• Rufen Sie Human Plugin aus demselben Netzwerk wie den Container auf. Terminieren Sie TLS davor, wenn der Pfad über nicht vertrauenswürdige Netzwerke führt.
• Eine Human-Plugin-Installation ist eine Isolationsgrenze. Verschiedene Clients, Marken oder Umgebungen, die keine Intelligence teilen dürfen, benötigen getrennte Installationen und Datenbanken, jeweils mit eigener Intelligence.