65.9K
CodeProject 正在变化。 阅读更多。
Home

开始使用 Evident

emptyStarIconemptyStarIconemptyStarIconemptyStarIconemptyStarIcon

0/5 (0投票)

2018年9月12日

CPOL
viewsIcon

4631

Evident 集成选项概述。

找到合适的验证解决方案意味着能够灵活地应对任何挑战,高效地获取开展业务所需的答案。Evident 强大的平台让企业能够自信、轻松地进行集成,并为扩展和添加功能留有充裕的空间,仅需极少的精力。

系统始终以同样简单的方式工作

  1. 您可以使用一个或多个属性创建验证请求,例如某人是否拥有有效的船只保险或许可通过背景调查。
  2. 您希望验证的个人数据的最终用户将数据提交给平台。
  3. 系统运行验证以满足您的请求。
  4. 系统报告最新的验证结果,从而支持您的业务运营。

这些步骤的具体操作取决于您选择的集成方法。

集成选项

在 Evident,我们深知简洁、安全和可扩展性既是必需的,又难以寻觅。通过四种集成选项,开发人员和部署团队可以选择最符合其资源和需求的路径。从允许企业在几分钟内完成验证且集成有限的 Evident Portal,到支持端到端定制的 VerifyAPI,我们的身份保障平台提供了一个灵活、直观且安全的解决方案,以满足您的验证需求。

客户门户和 Evident Submit 用户界面

如果您想立即开始,只需极少的精力,就可以使用您账户下的 Evident 自有集成。如果此模式是您的首选,请联系支持以开始。

VerifyAPI 和 Evident Submit 用户界面

在此集成模式下,您的后端与 Evident 平台集成,而我们负责在我们可品牌化的界面中收集客户数据。

使用 VerifyAPI 创建请求

VerifyAPI 是一个 RESTful JSON API,允许您创建验证请求并检索有关现有请求的信息。

您需要用户名和 API 密钥才能使用 HTTP Basic Auth 通过 VerifyAPI 进行身份验证。如果您在注册时未收到凭据,请发送电子邮件至support@evidentid.com。您应该有一个用于生产环境的 API 密钥,以及另一个用于沙箱环境的 API 密钥。我们将向您展示如何将 API 密钥与相应的 VerifyAPI 实例一起使用。

  • 生产环境的 VerifyAPI 位于https://verify.api.evidentid.com/api/v1
  • 沙箱环境的 VerifyAPI 位于https://verify.api.demo.evidentid.com/api/v1

在展示此处示例调用时,我们将您的选定 API 称为 $VERIFY,并将您的账户名称称为 $ACCOUNT

您的 API 密钥是机密信息!您应该仅从您的服务器调用 VerifyAPI 端点,并且仅限于您的服务器。请注意密钥的使用方式,以确保最高级别的保护。

对于此集成,我们创建一个请求来验证属于电子邮件jon.doe@somedomain.com的最终用户的信息。验证请求由属性组成,属性是用于构建您期望验证内容的报告的小型、可验证数据项。最终用户需要进行身份验证并将个人数据提交给系统进行验证。创建请求后,最终用户从上次提交之日起有 28 天的时间来完成,否则整个请求将超时。

 

字段 描述
email 您希望验证的个人数据的所有者的电子邮件。根据集成模式,用户可能会收到一封电子邮件,指示他们响应验证请求。
userId 这是您自己的自定义标识符,如果您不希望使用我们的标识符,可以使用它来查找此最终用户。这允许与您自己的数据库记录实现更好的互操作性。
description 一个描述验证请求意图的字符串。这用于您自己的记录或适用的情况下与最终用户的通信。
userAuthenticationType 此字段控制最终用户如何向系统进行身份验证。对于此集成模式,将其设置为 blindtrust
attributesRequested 一个对象数组,其中包含 attributeType 键,用于指定您要验证的数据项。
$ curl "$VERIFY/verify/requests" \
    -X POST \
    --header "Content-Type: application/json" \
    -u "$ACCOUNT" \
    -d @- << EOF
{
    "email": "jon.doe@somedomain.com",
    "userId": "jon.doe.12345",
    "description": "Please provide your ServSafe certificate number",
    "userAuthenticationType": "blindtrust",
    "attributesRequested": [
        {"attributeType": "certifications.servsafe.servsafe_food_handler.valid"}
    ]
}
EOF

Enter host password for user '$ACCOUNT': # Paste API key here to keep it out of history.

这是来自 VerifyAPI 的响应,指示已创建请求。我们将保留新请求的 id 以供将来参考。userIdentityToken 是一个多用途令牌,最终用户可以使用它来针对 Evident Web 应用进行身份验证。通常您不需要自己使用此令牌。我们会代表您向最终用户发送电子邮件。

您也可以保留 idOwnerId 以供您希望查看适用于该用户的验证请求时参考。

此时,您的系统将使用 webhook 或其他 VerifyAPI 调用(下文讨论)等待结果。

{
   "id": "3fc5ed0e-bb51-4c34-b294-0648969b7544",
   "idOwnerId": "ae954a66-8c00-4bc2-90f7-93c21542dab5",
   "userIdentityToken": "[lots of characters!]"
}

Webhook 通知

创建请求后,我们将向所有者发送电子邮件和提醒,以提交其个人数据。此时,您可以使用我们的 webhook 事件来监控验证请求何时完成。有关设置说明,请参阅您账户的Webhook

$ curl "$VERIFY/verify/requests/3fc5ed0e-bb51-4c34-b294-0648969b7544" \
    -X GET \
    -u "<account>"

Enter host password for user '<account>': # Paste API key here to keep it out of history.

使用 VerifyAPI 检查结果

让我们回到服务器。我们将使用之前 VerifyAPI 提供的请求 id 来检查报告。

$ curl "$VERIFY/verify/requests/3fc5ed0e-bb51-4c34-b294-0648969b7544" \
    -X GET \
    -u "<account>"

Enter host password for user '<account>': # Paste API key here to keep it out of history.

响应可能表明结果尚未准备好,在这种情况下,您只需在一两分钟后重复请求。最终,响应将类似于此。

{
    // ...
    "attributes": [
        {
            "status": "shared",
            "type": "certifications.servsafe.servsafe_food_handler.valid",
            "values": [
                true,
            ]
        }
    ]
}

在这里,您可以看到最初请求的属性以及结果。根据此,该属性因数据提交而被标记为“已共享”。

位于 values 数组中的第一个值显示此集合的最近一次提交已通过事实核查并被认定为合法。稍后的验证可能会显示开头的 false,以捕获证书是否曾经有效但后来无效。这意味着您可以随时了解验证的最新信息。因此,如果您向同一个人发出相同的请求并获得不同的结果,您可以做出相应的响应。

如果您在入职过程中选择了 webhook 和电子邮件通知,那么您也将自动收到这些结果的通知。

{
   "id": "3fc5ed0e-bb51-4c34-b294-0648969b7544",
   "idOwnerId": "ae954a66-8c00-4bc2-90f7-93c21542dab5",
   "userIdentityToken": "[lots of characters!]"
}

错误处理

VerifyAPI 可能会以 4xx 状态码响应。在这种情况下,响应将具有一个 JSON 主体,其中包含一个 reason 键,该键包含一个可读字符串,解释错误(例如 { "reason": "Invalid parameters specified." })。

5xx 状态码(尽管不太常见)通常表示暂时性中断。

在调用 VerifyAPI 时,请检查响应正文中的 4xx 错误代码,相应地调整您的请求并重试。如果尽管先前集成成功或文档存在明显不一致,错误仍然存在,请联系支持。

VerifyAPI 和 AssureSDK

此集成模式适用于您需要后端集成客户端 Web 浏览器集成的情况。使用此方法,您无需在服务器上处理个人信息,但仍可允许最终用户使用您自己的品牌界面输入信息。此集成模式使用 VerifyAPI(一个用于管理验证请求的 RESTful JSON API)和 AssureSDK(一个在 Web 浏览器中使用的 JavaScript 库,可确保敏感数据永远不会到达您的后端)。

您需要设置 webhook 来捕获验证结果已准备好通过 VerifyAPI 检索的通知,或者您可以自行检查状态。

要查看此集成模式的实际效果,请查看示例 VerifyAPI+AssureSDK 集成的源代码。

{
   "id": "3fc5ed0e-bb51-4c34-b294-0648969b7544",
   "idOwnerId": "ae954a66-8c00-4bc2-90f7-93c21542dab5",
   "userIdentityToken": "[lots of characters!]"
}

使用 VerifyAPI 创建请求

VerifyAPI 是一个 RESTful JSON API,允许您创建验证请求并检索有关现有请求的信息。

您需要用户名和 API 密钥才能使用 HTTP Basic Auth 通过 VerifyAPI 进行身份验证。如果您在注册时未收到凭据,请发送电子邮件至support@evidentid.com。您应该有一个用于生产环境的 API 密钥,以及另一个用于沙箱环境的 API 密钥。我们将向您展示如何将 API 密钥与相应的 VerifyAPI 实例一起使用。

  • 生产环境的 VerifyAPI 位于https://verify.api.evidentid.com/api/v1
  • 沙箱环境的 VerifyAPI 位于https://verify.api.demo.evidentid.com/api/v1

在展示此处示例调用时,我们将您的选定 API 称为 $VERIFY,并将您的账户名称称为 $ACCOUNT

您的 API 密钥是机密信息!您应该仅从您的服务器调用 VerifyAPI 端点,并且仅限于您的服务器。请注意密钥的使用方式,以确保最高级别的保护。

对于此集成,我们创建一个请求来验证属于电子邮件jon.doe@somedomain.com的最终用户的信息。验证请求由属性组成,属性是用于构建您期望验证内容的报告的小型、可验证数据项。最终用户需要进行身份验证并将个人数据提交给系统进行验证。创建请求后,最终用户从上次提交之日起有 28 天的时间来完成,否则整个请求将超时。

字段 描述
email 您希望验证的个人数据的所有者的电子邮件。根据集成模式,用户可能会收到一封电子邮件,指示他们响应验证请求。
userId 这是您自己的自定义标识符,如果您不希望使用我们的标识符,可以使用它来查找此最终用户。这允许与您自己的数据库记录实现更好的互操作性。
description 一个描述验证请求意图的字符串。这用于您自己的记录或适用的情况下与最终用户的通信。
userAuthenticationType 此字段控制最终用户如何向系统进行身份验证。对于此集成模式,将其设置为 embedded
attributesRequested 一个对象数组,其中包含 attributeType 键,用于指定您要验证的数据项。
$ curl "$VERIFY/verify/requests" \
    -X POST \
    --header "Content-Type: application/json" \
    -u "$ACCOUNT" \
    -d @- << EOF
{
    "email": "jon.doe@somedomain.com",
    "userId": "jon.doe.12345",
    "description": "Please provide your ServSafe certificate number",
    "userAuthenticationType": "embedded",
    "attributesRequested": [
        {"attributeType": "certifications.servsafe.servsafe_food_handler.valid"}
    ]
}
EOF

Enter host password for user '$ACCOUNT': # Paste API key here to keep it out of history.

这是来自 VerifyAPI 的响应,指示已创建请求。我们将保留新请求的 id 以供将来参考。userIdentityToken 是一个单次使用令牌,最终用户将用它来交换 Web 应用中的会话。您也可以保留 idOwnerId 以便您希望查看适用于该用户的验证请求时参考。

我们可以使用请求 ID 随时查找请求的状态和结果,或者在需要时重新颁发 userIdentityToken

现在我们需要提供一个 HTML 页面,该页面使用 userIdentityToken 来初始化 AssureSDK,为最终用户创建会话,并提交数据进行验证。

{
   "id": "3fc5ed0e-bb51-4c34-b294-0648969b7544",
   "idOwnerId": "ae954a66-8c00-4bc2-90f7-93c21542dab5",
   "userIdentityToken": "[lots of characters!]"
}

AssureSDK 设置

现在我们有了 Evident 验证最终用户个人信息的请求,接收者将需要填写表单以将数据提交给 Evident 并使用其颁发的 userIdentityToken 来响应您的请求。在此集成中,您对用户体验的控制是完全的。您只需要设置 AssureSDK 来将数据提交给平台,从而绕过您的服务器。

要设置 AssureSDK,请在此处下载或使用此 <script> 标签从我们的 CDN 加载它。

<script type="text/javascript" src="https://cdn.evidentid.com/sdk/v1.0.4/assure-sdk.js"></script>

AssureSDK 加载后,您可以在 EvidentID.AssureSDK 全局变量中找到其签名。您需要使用 VerifyAPI 的 userIdentityToken 调用其 setUp 函数。将令牌的值放在此代码片段中 $TOKEN 的位置。该函数返回一个 Promise,其值为 undefined,但在 SDK 准备好将数据提交给 Evident 平台时解析。

您还可以指定环境以选择与颁发令牌的实例匹配的 VerifyAPI 实例。将 EvidentID.AssureSDK.ENVIRONMENTS.DEMO 用于沙箱环境,或将 EvidentID.AssureSDK.ENVIRONMENTS.PROD 用于生产环境。

EvidentID.AssureSDK.setUp({
    environment: EvidentID.AssureSDK.ENVIRONMENTS.DEMO, // Or .PROD for production
    singleUseToken: '$TOKEN'
}).then(() => {
    // I can submit values now!
}).catch((e) => {
    alert(e.reason || e.message);
});

使用 AssureSDK 提交数据

最后一个要考虑的函数是 EvidentID.AssureSDK.submitAttributes(),它将个人信息直接发送到 Evident 平台。

为了在上下文中理解提交,让我们看一个使用 AssureSDK 的示例表单。这是一个完整的 HTML 示例,假设 userIdentityToken 已放置在代码中 $TOKEN 的位置。

为了从最终用户的角度理解,将此代码保存到 servsafe.html 并将 $TOKEN 替换为与请求关联的 userIdentityToken 值。在浏览器中打开该页面,您将看到一个表单。出于实验目的,您可以继续直接将新令牌粘贴到代码中,但集成示例只是向您的用户提供一个页面,其中包含一个新令牌。

流程如下

  1. 从 CDN 加载 AssureSDK。SDK 出现在 EvidentID.AssureSDK 全局变量中。
  2. 调用 EvidentID.AssureSDK.setUp() 来获取一个会话。
  3. 使用 EvidentID.AssureSDK.submitAttributes() 将表单数据提交给 Evident。
<!DOCTYPE html>
<html>
    <head>
        <script type="text/javascript"
                src="https://cdn.evidentid.com/sdk/v1.0.4/assure-sdk.js"></script>
        <title>Provide your ServSafe credentials</title>
    </head>
    <body>
        <script type="text/javascript">
        // Set up the SDK using the token provided by VerifyAPI.
        // The token can only be used once!
        EvidentID.AssureSDK.setUp({
            environment: EvidentID.AssureSDK.ENVIRONMENTS.DEMO,
            singleUseToken: '$TOKEN'
        }).then(() => {
            document.getElementById('fields').setAttribute('style', 'display: grid');
        }).catch((e) => {
            alert(e.reason || e.message);
        });

        function sendDataToEvident() {
            const firstname = document.getElementById('firstname').value;
            const lastname = document.getElementById('lastname').value;
            const certnumber = document.getElementById('certnumber').value;

            EvidentID.AssureSDK.submitAttributes({
                'core.firstname': firstname,
                'core.lastname': lastname,
                'certifications.servsafe.servsafe_food_handler.certnumber': certnumber,
            }).then(() => {
                alert('Success! You can proceed to check on the status of the request.');
            }).catch((e) => {
                alert(e.reason || e.message);
            });
        }
        </script>

        <fieldset id="fields" style="display: none">
            First Name: <input id="firstname"><br>
            Last Name: <input id="lastname"><br>
            ServSafe certificate number: <input id="certnumber"><br>

            <button onclick="sendDataToEvident(event)">Submit!</button>
        </fieldset>
    </body>
</html>

重新颁发令牌

如果由于某种原因用户需要另一个会话,请使用相关的请求 ID 请求一个新的单次使用令牌。在此示例中,我们使用来自先前 VerifyAPI 响应的请求 ID。该集成示例展示了一种使用新颁发的令牌来动态提供经过身份验证的 HTML 表单的方法。

$ curl "$VERIFY/verify/requests/3fc5ed0e-bb51-4c34-b294-0648969b7544/authToken" \
    -X GET \
    -u "$ACCOUNT"

Enter host password for user '$ACCOUNT': # Paste API key here to keep it out of history.

Webhook 通知

您可以使用我们的 webhook 事件来监控此集成的进度。有关设置说明,请参阅您账户的Webhook

{
    // ...
    "attributes": [
        {
            "status": "shared",
            "type": "certifications.servsafe.servsafe_food_handler.valid",
            "values": [
                true,
            ]
        }
    ]
}

使用 VerifyAPI 检查结果

让我们回到服务器。我们将使用之前 VerifyAPI 提供的请求 id 来检查报告。

$ curl "$VERIFY/verify/requests/3fc5ed0e-bb51-4c34-b294-0648969b7544" \
    -X GET \
    -u "<account>"

Enter host password for user '<account>': # Paste API key here to keep it out of history.

响应可能表明结果尚未准备好,在这种情况下,您只需在一两分钟后重复请求。最终,响应将类似于此。

{
    // ...
    "attributes": [
        {
            "status": "shared",
            "type": "certifications.servsafe.servsafe_food_handler.valid",
            "values": [
                true,
            ]
        }
    ]
}

在这里,您可以看到最初请求的属性以及结果。根据此,该属性因数据提交而被标记为“已共享”。

位于 values 数组中的第一个值显示此集合的最近一次提交已通过事实核查并被认定为合法。稍后的验证可能会显示开头的 false,以捕获证书是否曾经有效但后来无效。这意味着您可以随时了解验证的最新信息。因此,如果您向同一个人发出相同的请求并获得不同的结果,您可以做出相应的响应。

如果您在入职过程中选择了 webhook 和电子邮件通知,那么您也将自动收到这些结果的通知。

// Sync
try {
  AssureSDK.createDocumentPageFromDataUrl(...)
} catch (e) {
  if (e.reason) console.log(e.reason, e.extra); // base/bad-arguments undefined
}

// Async
AssureSDK.submitAttributes(...).catch((e) => {
  if (e.reason) console.log(e.reason, e.extra); // service/rate-limited 14
});

错误处理

集成过程中,VerifyAPI 或 AssureSDK 可能会出现错误。此处我们涵盖每个错误空间。

VerifyAPI 错误

VerifyAPI 可能会以 4xx 状态码响应。在这种情况下,响应将具有一个 JSON 主体,其中包含一个 reason 键,该键包含一个可读字符串,解释错误(例如 { "reason": "Invalid parameters specified." })。

5xx 状态码(尽管不太常见)通常表示暂时性中断。

在调用 VerifyAPI 时,请检查响应正文中的 4xx 错误代码,相应地调整您的请求并重试。如果尽管先前集成成功或文档存在明显不一致,错误仍然存在,请联系支持。

AssureSDK

AssureSDK 将遵循以下规则抛出 Error 对象

  • Error 对象将具有 reason 和/或 extra 属性,除非错误是内置类型(如 TypeError)。
  • 如果出现 extra 属性,它将包含与错误相关的信息。
  • 如果遇到错误的功能返回一个 promise,错误将仅出现在 promise 的 rejection handler 中。错误不会同步抛出。

reason 代码的格式为 <facility>/<cause>,其中 <facility> 是错误的范围,<cause> 是该范围内的具体问题。

AssureSDK 错误代码

reason 描述
auth/unauthorized 授权令牌无效或已过期。
base/bad-arguments 提供的函数调用参数无效,无法使用。
idscan/bad-back 身份证背面未通过预提交验证检查。您可以要求用户重试。
idscan/bad-front 身份证正面未通过预提交验证检查。您可以要求用户重试。
idscan/missing-back 未收到身份证背面文件。
idscan/missing-front 未收到身份证正面文件。
idscan/missing-both 未收到身份证两面的文件。
service/cant-connect SDK 无法连接到 Evident 的服务。
service/rate-limited 客户端正在发出过多请求。extra 包含一个 Number,表示重试前等待的秒数。
service/internal-error Evident 的服务在处理过程中遇到未指定错误。
submit/invalid-attribute-value 提供的属性值无效,已被拒绝处理。extra 是一个 String,用于命名有问题的属性类型。
submit/unknown-attribute 提交中指定的属性类型未被识别。extra 是一个 String,用于命名有问题的属性类型。
// Sync
try {
  AssureSDK.createDocumentPageFromDataUrl(...)
} catch (e) {
  if (e.reason) console.log(e.reason, e.extra); // base/bad-arguments undefined
}

// Async
AssureSDK.submitAttributes(...).catch((e) => {
  if (e.reason) console.log(e.reason, e.extra); // service/rate-limited 14
});

VerifyAPI 和 SubmitAPI

此集成模式提供端到端的完整定制。在此集成中,您的服务器可以访问个人数据。当您的集成和设想的体验能够支持所有相关的安全和监管责任时,请使用此方法。

使用 VerifyAPI 创建请求

VerifyAPI 是一个 RESTful JSON API,允许您创建验证请求并检索有关现有请求的信息。

您需要用户名和 API 密钥才能使用 HTTP Basic Auth 通过 VerifyAPI 进行身份验证。如果您在注册时未收到凭据,请发送电子邮件至support@evidentid.com。您应该有一个用于生产环境的 API 密钥,以及另一个用于沙箱环境的 API 密钥。我们将向您展示如何将 API 密钥与相应的 VerifyAPI 实例一起使用。

  • 生产环境的 VerifyAPI 位于https://verify.api.evidentid.com/api/v1
  • 沙箱环境的 VerifyAPI 位于https://verify.api.demo.evidentid.com/api/v1

在展示此处示例调用时,我们将您的选定 API 称为 $VERIFY,并将您的账户名称称为 $ACCOUNT

您的 API 密钥是机密信息!您应该仅从您的服务器调用 VerifyAPI 端点,并且仅限于您的服务器。请注意密钥的使用方式,以确保最高级别的保护。

对于此集成,我们创建一个请求来验证属于电子邮件jon.doe@somedomain.com的最终用户的信息。验证请求由属性组成,属性是用于构建您期望验证内容的报告的小型、可验证数据项。最终用户需要进行身份验证并将个人数据提交给系统进行验证。创建请求后,最终用户从上次提交之日起有 28 天的时间来完成,否则整个请求将超时。

字段 描述
email 您希望验证的个人数据的所有者的电子邮件。根据集成模式,用户可能会收到一封电子邮件,指示他们响应验证请求。
userId 这是您自己的自定义标识符,如果您不希望使用我们的标识符,可以使用它来查找此最终用户。这允许与您自己的数据库记录实现更好的互操作性。
description 一个描述验证请求意图的字符串。这用于您自己的记录或适用的情况下与最终用户的通信。
userAuthenticationType 此字段控制最终用户如何向系统进行身份验证。对于此集成模式,将其设置为 blindtrust
attributesRequested 一个对象数组,其中包含 attributeType 键,用于指定您要验证的数据项。
$ curl "$VERIFY/verify/requests" \
    -X POST \
    --header "Content-Type: application/json" \
    -u "$ACCOUNT" \
    -d @- << EOF
{
    "email": "jon.doe@somedomain.com",
    "userId": "jon.doe.12345",
    "description": "Please provide your ServSafe certificate number",
    "userAuthenticationType": "blindtrust",
    "attributesRequested": [
        {"attributeType": "certifications.servsafe.servsafe_food_handler.valid"}
    ]
}
EOF

Enter host password for user '$ACCOUNT': # Paste API key here to keep it out of history.

这是来自 VerifyAPI 的响应,指示已创建请求。我们将保留新请求的 id 以供将来参考。userIdentityToken 是一个多用途令牌,您需要使用它来针对 SubmitAPI 进行身份验证。您也可以保留 idOwnerId 以供您希望查看适用于该用户的验证请求时参考。我们可以使用请求 ID 随时查找请求的状态和结果。

{
   "id": "3fc5ed0e-bb51-4c34-b294-0648969b7544",
   "idOwnerId": "ae954a66-8c00-4bc2-90f7-93c21542dab5",
   "userIdentityToken": "[lots of characters!]"
}

使用 SubmitAPI 提交

与 VerifyAPI 一样,SubmitAPI 也是一个 RESTful JSON 服务。您使用 SubmitAPI 将个人数据发送到 Evident 平台。SubmitAPI 为任何涉及个人数据所有者代表的体验提供支持。在此集成模式下,您的服务器端应用程序代表该所有者。

  • 生产环境的 SubmitAPI 位于https://submit.api.evidentid.com/api/v1/
  • 沙箱环境的 SubmitAPI 位于https://submit.api.demo.evidentid.com/api/v1/

我们将在代码中用 $SUBMIT 指定您选择的实例。由于 SubmitAPI 的客户端代表着个人数据的拥有者,因此该客户端需要使用 VerifyAPI 提供的 userIdentityToken 作为 bearer token(代码中的 $TOKEN)进行身份验证。

VerifyAPI 和 SubmitAPI 可能看起来相似,但在解释数据的方式上有所不同。VerifyAPI 可用于验证某人是否通过了背景调查,但这将需要 SubmitAPI 调用社会安全号码、出生日期和同意信息以获取监管原因。您需要了解在 VerifyAPI 中验证相关属性所需的输入。此处显示的调用提交了用于验证 certifications.servsafe.servsafe_food_handler.valid 属性的数据。

curl $SUBMIT/requests" \
    -X POST \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $TOKEN" \
    -d @- << EOF
{
    "inputs": [
        {
            "type": "core.firstname",
            "value": "John"
        },
        {
            "type": "core.lastname",
            "value": "Smith"
        },
        {
            "type": "certifications.servsafe.servsafe_food_handler.certnumber",
            "value": "1234567"
        }
    ]
}
EOF

Webhook 通知

您可以使用我们的 webhook 事件来监控此集成的进度。有关设置说明,请参阅您账户的Webhook

{
    "eventType": "notificationFailure",
    "email": <the email address that could not be emailed>,
    "recipientType": <the type of user that could not be emailed>,
    "status": <the reason for delivery failure>
}

使用 VerifyAPI 检查结果

让我们回到服务器。我们将使用之前 VerifyAPI 提供的请求 id 来检查报告。

$ curl "$VERIFY/verify/requests/3fc5ed0e-bb51-4c34-b294-0648969b7544" \
    -X GET \
    -u "<account>"

Enter host password for user '<account>': # Paste API key here to keep it out of history.

响应可能表明结果尚未准备好,在这种情况下,您只需在一两分钟后重复请求。最终,响应将类似于此。

{
    // ...
    "attributes": [
        {
            "status": "shared",
            "type": "certifications.servsafe.servsafe_food_handler.valid",
            "values": [
                true,
            ]
        }
    ]
}

在这里,您可以看到最初请求的属性以及结果。根据此,该属性因数据提交而被标记为“已共享”。

位于 values 数组中的第一个值显示此集合的最近一次提交已通过事实核查并被认定为合法。稍后的验证可能会显示开头的 false,以捕获证书是否曾经有效但后来无效。这意味着您可以随时了解验证的最新信息。因此,如果您向同一个人发出相同的请求并获得不同的结果,您可以做出相应的响应。

如果您在入职过程中选择了 webhook 和电子邮件通知,那么您也将自动收到这些结果的通知。

{
    "eventType": "notificationFailure",
    "email": <the email address that could not be emailed>,
    "recipientType": <the type of user that could not be emailed>,
    "status": <the reason for delivery failure>
}

错误处理

VerifyAPI 和 SubmitAPI 都可能以 4xx 状态码响应。在这种情况下,响应将具有一个 JSON 主体,其中包含一个 reason 键,该键包含一个可读字符串,解释错误(例如 { "reason": "Invalid parameters specified." })。

5xx 状态码(尽管不太常见)通常表示暂时性中断。

在发出请求时,请检查响应正文中的 4xx 错误代码,相应地调整您的请求并重试。如果尽管先前集成成功或文档存在明显不一致,错误仍然存在,请联系支持。

{
    "eventType": "rpRequestCompleted",
    "rpRequestId": <the ID of the RP request that was completed>
}

Webhook 通知

您可以使用 webhook 来监控 Evident 平台事件。您向平台提供一些 URL,Evident 平台会在关键时刻将 POST 请求发送到这些 URL,并附带 JSON payload。如果其中一个 POST 请求失败,它将尝试您指定的次数,并在每次重试之间留出您想要的时间。

要设置 webhook,您将需要以下内容

  • 要监控的事件
  • Webhook URL
  • POST 请求失败时的重试等待时间
  • 重试次数

将这些信息发送给我们的支持团队,您的帐户将相应配置。

您可以在下方找到所有支持的事件。

rpRequestCompleted

当最终用户的验证完成时,会触发 rpRequestCompleted。payload 指示事件类型和相关请求的 ID。
{
    "eventType": "rpRequestCompleted",
    "rpRequestId": <the ID of the RP request that was completed>
}

notificationFailure

当 Evident 平台未能通过电子邮件通知某人时,会发生 notificationFailure 事件。

属性 描述
recipientType 如果为 id_owner,则收件人是个人数据的最终用户。如果为 relying_party,则收件人是您账户上的管理员。
email 相关的电子邮件地址。
状态 如果为 bounced,则表示电子邮件已被硬退回。如果为 rejected,则表示电子邮件服务器拒绝向收件人的地址发送电子邮件。
© . All rights reserved.