Verify Migrationsleitfaden

Die folgende Anleitung hilft Ihnen bei der Migration von Verify Erbe zu Verify. Dazu müssen Sie Ihre Endpunkt-URLs aktualisieren, um die neue Version aufzurufen, und Ihre Anwendungseinstellungen ändern. Sie müssen kein Vorregistrierungsformular ausfüllen, um Verify nutzen zu können.

Zusammenfassung

Die Vonage Verify API ist ein Service, der es Entwicklern ermöglicht, eine Zwei-Faktor-Authentifizierung (2FA) zu implementieren, um sich vor Betrug zu schützen und die Authentizität der Benutzer zu gewährleisten. Vonage bietet zwei Versionen dieser API an: Legacy und das aktuelle Verify. Obwohl beide Versionen die gleiche Hauptfunktion erfüllen, gibt es erhebliche Unterschiede in ihren Merkmalen, Funktionalitäten und ihrer Verwendung.

Wesentliche Unterschiede

  • Flexibilität und Anpassungsfähigkeit: Verify bietet jetzt eine flexiblere Erstellung von Arbeitsabläufen und erweiterte Anpassungsoptionen, wie z. B. ein funktionsreicheres System zur Verwaltung benutzerdefinierter Vorlagen im Vergleich zu Legacy.
  • Kanal-Unterstützung: Verify bietet jetzt zusätzliche Unterstützung für die Verifizierung über verschiedene neue Kanäle wie Silent Auth, WhatsApp und E-Mail, während Legacy auf SMS und Sprache beschränkt ist.
  • Sicherheitsmerkmale: Verify bietet jetzt verbesserte Sicherheitsfunktionen und entspricht den neuesten Standards.
  • Fehlerbehandlung: Verify bietet jetzt detailliertere Fehlermeldungen und eine verbesserte Handhabung, wie z.B. erweiterte Ratenbegrenzungs- und automatische Wiederholungsmechanismen.
  • API-Design und Benutzerfreundlichkeit: Verify hat jetzt ein benutzerfreundlicheres Design und einfachere Integrationsmöglichkeiten mit modernen Applications, wie z.B. synchrone und asynchrone Optionen.

Vergleich der Merkmale

Merkmal/Funktion Verify (Legacy) Verify
Grundlegende Verifizierung SMS, Sprache Stille Autorisierung, SMS, Sprache, E-Mail, WhatsApp
ID-Behandlung anfordern Grundlegendes Antrags-ID-System Verbesserte Verfolgung der Anfrage-ID mit mehr Metadaten
Benutzerdefinierte Workflow-Konfiguration Begrenzt Umfassend, einschließlich mehrerer Kanalkonfigurationen
Verwaltung des PIN-Ablaufs Konfigurierbar, aber begrenzt (60 bis 3600 Sekunden) Genauere Kontrolle über PIN-Ablauf und Ereigniszeitpunkte
Einhaltung der Sicherheitsvorschriften Grundlegend, mit älteren Normen übereinstimmend Fortschrittlich, konform mit den neuesten Sicherheitsstandards
Fehlerbehandlung Grundlegende Fehlermeldungen Detaillierte Fehlermeldungen mit umfangreichen Fehlercodes
Ratenbegrenzung Grundlegende Tarifbegrenzung Verbesserte Mechanismen zur Ratenbegrenzung
Mechanismus zur Wiederholung Grundlegende Neuversuche bei Fehlschlägen Erweiterte Wiederholungslogik mit anpassbaren Wiederholungsworkflows
Analytik und Berichterstattung Begrenzte Berichtsmöglichkeiten Verbesserte Analysen und detaillierte Berichte
Unterstützung der Lokalisierung Einfache Lokalisierung (begrenzte Sprachen) Verbesserte Lokalisierung mit mehr Sprachen und benutzerdefinierten Meldungen
API-Dokumentation und Unterstützung Umfassende, aber ältere Dokumentation Moderne, detaillierte und benutzerfreundlichere Dokumentation

API-Aufrufe

In Verify wurde ein asynchroner Modus eingeführt, der es Ihnen ermöglicht, Nachrichten zu empfangen und Statuten per Webhook aufzurufen, wobei Sie sowohl Ereignisse (im Falle von whatsapp_interactive) und zusammenfassende Rückrufe. Sie können es auch synchron verwenden mit redirect_url und check_url.

Sie müssen Ihre Webhooks für Verify-Rückrufe im Abschnitt Application des Kunden-Dashboard:

Webhooks can be configured on the customer dashboard

Weitere Dokumentation zu Webhooks finden Sie unter hier.

Endpunkte

Alle Verify-API-Aufrufe müssen aktualisiert werden, um den neuen Endpunkt zu verwenden:

Funktion Verify (Legacy) Verify
Verifizierungsanfrage senden POST https://api.nexmo.com/v2/verify/ POST https://api.nexmo.com/v2/verify
Antrag auf Überprüfung POST https://api.nexmo.com/verify/check/:format POST https://api.nexmo.com/v2/verify/:request_id
Suche verifizieren https://api.nexmo.com/verify/search/:format Demnächst verfügbar

Verwenden Sie an Ihre Webhooks gesendete Statusmeldungen, um vergangene oder aktuelle Anfragen in der Zwischenzeit zu überwachen.
Anfrage stornieren POST https://api.nexmo.com/verify/control/:format mit cmd = cancel DELETE https://api.nexmo.com/v2/verify/:request_id
Nächstes Ereignis im Workflow auslösen POST https://api.nexmo.com/verify/control/:format mit cmd = trigger_next_event POST https://api.nexmo.com/v2/verify/:request_id/next-workflow
Benutzerdefinierte Vorlagen POST https://api.nexmo.com/verify/templates GET https://api.nexmo.com/v2/verify/templates

POST https://api.nexmo.com/v2/verify/templates

GET https://api.nexmo.com/v2/verify/templates/:template_id

PATCH https://api.nexmo.com/v2/verify/templates/:template_id

DELETE https://api.nexmo.com/v2/verify/templates/:template_id
PSD2 POST https://api.nexmo.com/verify/psd2/:format Demnächst verfügbar
Netzwerk entsperren POST https://api.nexmo.com/verify/network-unblock POST https://api.nexmo.com/v2/verify/network-unblock

Arbeitsabläufe

Verify bietet Ihnen die Flexibilität, Ihren eigenen Arbeitsablauf zu definieren, im Gegensatz zu den festen Arbeitsabläufen von Legacy. Sie können eine beliebige Kombination von unterstützenden Kanälen Ihrer Wahl im Workflow angeben, maximal jedoch drei Kanäle.

Weitere Dokumentation zu Workflows finden Sie unter hier.

Kanäle

Neue Kanäle sind jetzt in Verify verfügbar:

  • SMS
  • Sprache (früher TTS in Legacy)
  • WhatsApp
  • E-Mail
  • Stille Authentifizierung

Ausführlichere Informationen zu diesen Kanälen finden Sie in der API-Spezifikation.

Spezielle Dokumentation zur stillen Authentifizierung finden Sie unter hier.

Zusammenfassung Rückrufe

Rückrufe werden an Ihren Webhook mit dem Status des Ereignisses zurückgegeben, entsprechend request_id & Kanal. Die folgenden Sequenzdiagramme zeigen, wie dies bei Verwendung eines einzelnen Kanals oder mehrerer Kanäle in Ihrem Arbeitsablauf funktioniert.

Einzelner Kanal

Summary Callback: Single channel in the workflow

Mehrere Kanäle

Summary Callback: Multiple channels in the workflow

Antwort-Codes

Neben der Änderung der Endpunkte müssen auch Ihre Applications aktualisiert werden, um die Antwortcodes zu verstehen, die bei der Verwendung von Verify empfangen werden:

HTTP-Code Definition
Erstellen einer Anfrage: POST /v2/verify
202 Der Antrag wurde angenommen. Lieferung in Bearbeitung.
409 Zu dieser Nummer ist eine Anfrage in Bearbeitung.
422 Fehler bei der Bearbeitung der Anfrage.
Validierung einer Anfrage: POST /v2/verify/{request_id}
200 Erfolgreich! Der korrekte Code wurde übermittelt.
400 Es wurde ein falscher Code angegeben.
404 Die Anfrage konnte nicht gefunden werden.
409 Die aktuelle Aktion unterstützt keine Pin-Prüfung.
410 Viele Male wurde ein falscher Code angegeben.
422 Anfrage kann nicht validiert werden.

Antrag auf Stornierung

Verify (Legacy) Verify
Kontrolle verifizieren kann verwendet werden, um eine laufende Überprüfungsanfrage abzubrechen. Kann nicht innerhalb der ersten 30 Sekunden der Anfrage abgebrochen werden. Senden Sie eine Stornierungsauftrag - wenn der Überprüfungsantrag aktiv ist, bricht er den Arbeitsablauf ab.

Schablonen

Verify (Legacy) Verify
Kunden können eine benutzerdefinierte Vorlage verwenden, um Verify-Nachrichten zu senden (Dokumentation) Verify verwendet dieselbe vordefinierte Vorlagen als Verify Legacy. Benutzerdefinierte Vorlagenfunktionalität in Kürze.

PSD2-Einhaltung

Verify (Legacy) Verify
Ist PSD2-konform Demnächst verfügbar

Antrag auf Überprüfung der Suche

Verify (Legacy) Verify
Verwenden Sie Suche verifizieren um den Status früherer oder aktueller Überprüfungsanfragen zu überprüfen. Verwenden Sie an Ihre Webhooks gesendete Statusmeldungen, um vergangene oder aktuelle Anfragen zu überwachen.

Betrugsmanagement

Beachten Sie, dass Netzwerksperren nur auf die SMS- und Voice-Kanäle in der Verify API angewendet werden.

Verify (Legacy) Verify
Auf Blöcke, die durch Geschwindigkeitsregeln ausgelöst werden, wird mit Fehler 7 Durch Geschwindigkeitsregeln ausgelöste Blöcke werden mit Status angezeigt blocked und Vernunft Fraudulent traffic detected for your account on network [23415]. im Rückruf der Zusammenfassung
Netzfreigaben können mit der Funktion Netzwerk Entsperren API. Verwendet dieselbe API für die Entsperrung.
Weitere Dokumentation: Altes System zur Betrugsbekämpfung Weitere Dokumentation: System zur Betrugsbekämpfung

Sequenzdiagramme verifizieren

Fluss verifizieren

Verify Flow

Verify Request mit Summary Callbacks

Verify Request with Summary Callbacks

Sequenzdiagramm für die stille Authentifizierung

Silent Authentication Sequence Diagram

Verify Payload Parameter Analyse für V1 vs. V2

Verifizierungsanfrage senden

Parameter Verify (Legacy) Verify (V2) Anmerkungen
API-Schlüssel api_key api_key
API-Geheimnis api_secret api_secret
Telefon-Nummer number to
Marke brand Eingeschlossen in workflow.channels.template
Absender-ID sender_id from Einsetzbar für channel = SMS & Email in V2
Code Länge code_length code_length
Sprache lg locale
Pin-Ablauf pin_expiry channel_timeout
Nächstes Ereignis Warten next_event_wait K.A.
Workflow-Bezeichner workflow_id Benutzerdefinierter Arbeitsablauf in workflow.channels Flexible Einstellung der Kanäle im Workflow
Benutzerdefinierter Code pin_code code
Vorlage K.A. template_id Vorlagenverwaltung Dokumentation für V2
E-Mail K.A. workflow.channels.email
WhatsApp K.A. workflow.channels.whatsapp
Stille Autorisierung K.A. workflow.channels.silent_auth
Entitäts-ID K.A. entity_id Einsetzbar für channel = SMS in V2
Inhalt ID K.A. content_id Einsetzbar für channel = SMS in V2
Application Identifier K.A. app_hash Einsetzbar für channel = SMS in V2

Antrag auf Schecküberprüfung

Parameter Verify (Legacy) Verify (V2)
API-Schlüssel api_key api_key
API-Geheimnis api_secret api_secret
ID anfordern request_id request_id
Code code code

Antrag auf Überprüfung der Suche

Parameter Verify (Legacy) Verify (V2)
API-Schlüssel api_key K.A.
API-Geheimnis api_secret K.A.
ID anfordern request_id K.A.

Verifizierungsanfrage abbrechen

Parameter Verify (Legacy) Verify (V2) Anmerkungen
API-Schlüssel api_key api_key
API-Geheimnis api_secret api_secret
ID anfordern request_id request_id
Befehl cmd=cancel K.A. V2 verwendet einen speziellen Endpunkt für die Stornierung.

Nächsten Verifizierungsprozess auslösen

Parameter Verify (Legacy) Verify (V2) Anmerkungen
API-Schlüssel api_key api_key
API-Geheimnis api_secret api_secret
ID anfordern request_id request_id
Befehl cmd=trigger_next_event K.A. V2 verwendet einen eigenen Endpunkt für die Auslösung der nächsten Aktion.

Benutzerdefinierte Vorlagen

Parameter Verify (Legacy) Verify (V2)
API-Schlüssel api_key api_key
API-Geheimnis api_secret api_secret
Kanal action_type channel
Sprache lg locale
Textvorlage template text
Textart für SMS type K.A.
URL der Mediendatei digit_n K.A.
Start der Nachricht welcome_message K.A.
Ende der Nachricht bye_message K.A.
Zendesk-Ticket contact_email K.A.
Vorlage Name K.A. name
Standardvorlagen-Indikator K.A. is_default
Vorlage Referenz K.A. template_id

PSD2-Einhaltung

Parameter Verify (Legacy) Verify (V2)
API-Schlüssel api_key K.A.
API-Geheimnis api_secret K.A.
Telefon-Nummer number K.A.
Ländercode country K.A.
Name des Empfängers payee K.A.
Zahlungsbetrag amount K.A.
Länge des Codes code_length K.A.
Sprache lg K.A.
Pin-Ablauf pin_expiry K.A.
Nächstes Ereignis Warten next_event_wait K.A.
Workflow-Bezeichner workflow_id K.A.