> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 德国 Personalausweis Profile 2 身份验证 API

> 通过 Didit 将 Personalausweis Profile 2 身份验证集成到您的应用中。查看国家覆盖范围、认证步骤、结果和定价。

Starten Sie die Personalausweis-Profile-2-Verifizierung von Ihrem Backend aus mit Ihrem Anwendungs-API-Schlüssel.
Sie benötigen weder einen Workflow noch eine `workflow_id`.
Die Antwort auf den Start beschreibt die nächste Authentifizierungsaktion; sie ist kein bestätigtes Identitätsergebnis.

## Abdeckung und Aktivierung

| Eigenschaft | Wert |
| - | - |
| Wallet | Personalausweis Profile 2 |
| Wallet-ID | `personalausweis` |
| Länder | ![](https://didit-public-assets.s3.eu-west-1.amazonaws.com/flags/de.svg)Deutschland |
| Aktivierung des Wallets in Produktion | ⏳ Demnächst verfügbar |
| Veröffentlichter Wallet-Preis | \$0.49 pro abgeschlossene Verifizierung |

Die Aktivierung eines Wallets ist unabhängig von der API-Bereitstellung und der Berechtigung Ihrer Anwendung.
Ein dokumentierter Endpunkt aktiviert kein Wallet, das als Demnächst verfügbar gekennzeichnet ist.
Die aktuellen veröffentlichten Preise finden Sie unter [Preise für digitale ID-Wallets](https://docs.didit.me/zh/getting-started/pricing.md#数字身份钱包定价).

## Was die Person tut

Folgen Sie der nächsten Aktion, die die Startanfrage zurückgibt.
Die Authentifizierungsoberfläche des Wallets bestimmt, ob die Person einen Browser, ein anderes Gerät oder eine App verwendet.

## Ergebnis abrufen

Folgen Sie dem [Leitfaden zur Digital-ID-Wallet-API](https://docs.didit.me/zh/standalone-apis/digital-id-wallets.md), um die Verifizierung zu verfolgen und ihr Ergebnis abzurufen.
Betrachten Sie nur ein abgeschlossenes, verifiziertes Ergebnis als Nachweis, dass das Wallet die Person authentifiziert hat.
Die zurückgegebenen Identitätsattribute variieren je nach Wallet; gehen Sie nicht davon aus, dass eine Adresse, ein Porträt oder alle angefragten Attribute vorhanden sind.

## Verwandte Seiten

* [Digital-ID-Wallet-APIs](https://docs.didit.me/zh/standalone-apis/digital-id-wallets.md)
* [Wallet-Abdeckung und Attribute](https://docs.didit.me/zh/core-technology/id-verification/digital-id-wallets.md)
* [Preise](https://docs.didit.me/zh/getting-started/pricing.md#数字身份钱包定价)


## OpenAPI

````yaml zh/openapi-25.json POST /v3/id-verification/wallets/personalausweis/
openapi: 3.0.0
info:
  version: 3.0.0
  title: Didit Verification API
  description: 身份证件验证 API。使用 x-api-key 请求头进行身份验证。
servers:
  - url: https://verification.didit.me
security: []
tags: []
paths:
  /v3/id-verification/wallets/personalausweis/:
    post:
      tags:
        - Digital ID wallets
      summary: 开始 Personalausweis 验证
      description: >-
        在不使用任何工作流的情况下发起 Personalausweis 登录（Bundesministerium des Innern
        (eID)；DEU）。仅在身份验证通过时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器访问的
        URL；用户返回至附加了 request_id 和 result 的 return_url。通过 GET
        /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook
        读取结果，切勿从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会与提供商通信。
      operationId: start_personalausweis_wallet_verification
      parameters:
        - in: header
          name: Idempotency-Key
          schema:
            type: string
          description: >-
            可选的重试安全密钥（最多 255
            个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409
            idempotency_key_reused。
      requestBody:
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest
            example:
              country: DEU
              vendor_data: your-customer-reference
              metadata:
                reference: example
              return_url: https://app.example.com/identity/complete
          application/x-www-form-urlencoded:
            schema:
              $ref: >-
                #/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/DigitalIdWalletApiWalletVerificationResponse
              example:
                request_id: 00000000-0000-4000-8000-000000000001
                wallet_verification:
                  wallet:
                    id: personalausweis
                    name: Personalausweis
                    issuing_authority: Bundesministerium des Innern (eID)
                  country: DEU
                  status: Not Finished
                  outcome: pending
                  error: null
                  interaction: redirect
                  simulated: false
                  expires_at: '2026-01-01T10:10:00Z'
                  next_action:
                    type: redirect
                    url: https://wallet.example.com/authorize
                  identity: null
                  attributes: null
                  level_of_assurance: null
                  verified_at: null
                  signature_valid: null
                  credential_type: person_identification
                vendor_data: your-customer-reference
                metadata:
                  reference: example
                created_at: '2026-01-01T10:00:00Z'
          description: ''
        '400':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest
          description: >-
            字段验证错误（{field: [messages]}），或错误
            return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number
            或 idempotency_key_invalid。
        '403':
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden
          description: >-
            缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或
            contract_rate_missing 错误。
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError'
          description: >-
            错误 idempotency_key_reused 或 idempotency_key_in_progress（附带
            Retry-After）。
        '502':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError'
          description: 错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError'
          description: 错误 wallet_not_configured：此环境无法访问该钱包。
      security:
        - ApiKeyAuth: []
        - BearerAuth: []
      x-codeSamples:
        - lang: curl
          label: cURL
          source: |-
            curl --request POST \
              --url https://verification.didit.me/v3/id-verification/wallets/personalausweis/ \
              --header 'x-api-key: YOUR_API_KEY' \
              --header 'Idempotency-Key: your-unique-attempt-key' \
              --header 'Content-Type: application/json' \
              --data '{
              "country": "DEU",
              "vendor_data": "your-customer-reference",
              "metadata": {
                "reference": "example"
              },
              "return_url": "https://app.example.com/identity/complete"
            }'
        - lang: python
          label: Python
          source: |-
            from didit import Didit

            # Reads DIDIT_API_KEY.
            client = Didit()

            result = client.id_wallets.start_personalausweis(
                vendor_data="your-customer-reference",
                metadata={"reference": "example"},
                country="DEU",
                return_url="https://app.example.com/identity/complete",
            )
            print(result)
        - lang: javascript
          label: Node.js
          source: |-
            import Didit from "@didit-protocol/sdk-node";

            // Reads DIDIT_API_KEY.
            const didit = new Didit();

            const result = await didit.idWallets.startPersonalausweis({
              vendor_data: "your-customer-reference",
              metadata: { reference: "example" },
              country: "DEU",
              return_url: "https://app.example.com/identity/complete",
            });
            console.log(result);
        - lang: go
          label: Go
          source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartPersonalausweis(ctx, didit.IDWalletsStartPersonalausweisParams{\n\tBody: didit.DigitalIDWalletAPIPersonalausweisWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata:   didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry:    didit.Some(didit.DigitalIDWalletAPIPersonalausweisWalletVerificationStartCountryEnum(\"DEU\")),\n\t\tReturnURL:  \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)"
        - lang: java
          label: Java
          source: >-
            import java.util.Map;

            import me.didit.Didit;

            import
            me.didit.types.DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum;

            import
            me.didit.types.DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest;


            // Reads DIDIT_API_KEY.

            Didit client = new Didit();


            var result =
            client.idWallets().startPersonalausweis(DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest.builder()
                    .vendorData("your-customer-reference")
                    .metadata(Map.of("reference", "example"))
                    .country(DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum.of("DEU"))
                    .returnUrl("https://app.example.com/identity/complete")
                    .build());
            System.out.println(result);
        - lang: php
          label: PHP
          source: |-
            <?php

            require 'vendor/autoload.php';

            use Didit\DiditClient;

            // Reads DIDIT_API_KEY.
            $didit = new DiditClient();

            $result = $didit->idWallets->startPersonalausweis([
                'vendor_data' => 'your-customer-reference',
                'metadata' => ['reference' => 'example'],
                'country' => 'DEU',
                'return_url' => 'https://app.example.com/identity/complete',
            ]);
            print_r($result->toArray());
        - lang: ruby
          label: Ruby
          source: |-
            require "didit"

            # Reads DIDIT_API_KEY.
            didit = Didit::Client.new

            result = didit.id_wallets.start_personalausweis(
              vendor_data: "your-customer-reference",
              metadata: { reference: "example" },
              country: "DEU",
              return_url: "https://app.example.com/identity/complete"
            )
            puts result.to_h
        - lang: csharp
          label: .NET
          source: >-
            using System;

            using System.Collections.Generic;

            using System.Text.Json;

            using Didit;


            // Reads DIDIT_API_KEY.

            using var client = new DiditClient();


            var result = await client.IdWallets.StartPersonalausweisAsync(new
            DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest

            {
                VendorData = "your-customer-reference",
                Metadata = new Dictionary<string, object> { ["reference"] = "example" },
                Country = new DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum("DEU"),
                ReturnUrl = "https://app.example.com/identity/complete",
            });

            Console.WriteLine(JsonSerializer.Serialize(result));
components:
  schemas:
    DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest:
      type: object
      description: 发起 Personalausweis 验证（DEU）。
      properties:
        vendor_data:
          type: string
          nullable: true
          description: 您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。
        metadata:
          type: object
          additionalProperties: {}
          nullable: true
          description: 与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。
        sandbox_scenario:
          type: string
          minLength: 1
          description: >-
            仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或
            'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET
            /v1/sandbox/scenarios/ 获取。
        country:
          allOf:
            - $ref: >-
                #/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum
          default: DEU
          description: |-
            Personalausweis 身份的 ISO 3166-1 alpha-3 国家/地区。默认为 DEU，即其支持的唯一国家/地区。

            * `DEU` - DEU
        return_url:
          type: string
          format: uri
          minLength: 1
          description: >-
            用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的
            allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET
            .../verifications/{request_id}/ 或 Webhook 读取最终结果。
          maxLength: 2048
        device:
          allOf:
            - $ref: '#/components/schemas/DigitalIdWalletApiDeviceEnum'
          default: same_device
          description: |-
            用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。

            * `same_device` - same_device
            * `cross_device` - cross_device
      required:
        - return_url
    DigitalIdWalletApiWalletVerificationResponse:
      type: object
      description: 单次独立钱包验证，正如每个钱包 endpoint 返回的结果一样。
      properties:
        request_id:
          type: string
          format: uuid
        wallet_verification:
          $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationResult'
        vendor_data:
          type: string
          nullable: true
        metadata:
          type: object
          additionalProperties: {}
          nullable: true
          description: 启动时发送的元数据对象，或 null。
        created_at:
          type: string
          format: date-time
      required:
        - created_at
        - metadata
        - request_id
        - vendor_data
        - wallet_verification
    DigitalIdWalletApiWalletVerificationStartBadRequest:
      oneOf:
        - $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError'
        - $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationFieldErrors'
    DigitalIdWalletApiWalletVerificationStartForbidden:
      oneOf:
        - $ref: >-
            #/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage
        - $ref: '#/components/schemas/DigitalIdWalletApiWalletVerificationError'
    DigitalIdWalletApiWalletVerificationError:
      type: object
      properties:
        error:
          type: string
          description: 稳定的机器可读代码，例如 wallet_unavailable。
        detail:
          type: string
      required:
        - detail
        - error
    DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum:
      enum:
        - DEU
      type: string
      description: '* `DEU` - DEU'
    DigitalIdWalletApiDeviceEnum:
      enum:
        - same_device
        - cross_device
      type: string
      description: |-
        * `same_device` - 同一设备
        * `cross_device` - 跨设备
    DigitalIdWalletApiWalletVerificationResult:
      type: object
      properties:
        wallet:
          allOf:
            - $ref: '#/components/schemas/DigitalIdWalletApiWallet'
          readOnly: true
        country:
          type: string
        status:
          type: string
          description: 待处理时为未完成，随后为已通过（已核验）或已拒绝。
        outcome:
          $ref: >-
            #/components/schemas/DigitalIdWalletApiWalletVerificationResultOutcomeEnum
        error:
          type: string
          nullable: true
          readOnly: true
        interaction:
          allOf:
            - $ref: '#/components/schemas/DigitalIdWalletApiInteractionEnum'
          readOnly: true
        simulated:
          type: boolean
          readOnly: true
        expires_at:
          type: string
          format: date-time
        next_action:
          allOf:
            - $ref: '#/components/schemas/DigitalIdWalletApiWalletNextAction'
          nullable: true
          readOnly: true
        identity:
          allOf:
            - $ref: '#/components/schemas/DigitalIdWalletApiWalletIdentity'
          nullable: true
          readOnly: true
        attributes:
          type: object
          additionalProperties: {}
          nullable: true
          readOnly: true
        level_of_assurance:
          type: string
          nullable: true
        verified_at:
          type: string
          format: date-time
          nullable: true
        signature_valid:
          type: boolean
          nullable: true
          description: 凭证签名验证通过后为 true；模拟凭证为 null。
        credential_type:
          type: string
          nullable: true
      required:
        - attributes
        - country
        - credential_type
        - error
        - expires_at
        - identity
        - interaction
        - level_of_assurance
        - next_action
        - outcome
        - signature_valid
        - simulated
        - status
        - verified_at
        - wallet
    DigitalIdWalletApiWalletVerificationFieldErrors:
      type: object
      description: 请求验证错误：每个被拒绝的字段及其消息。
      additionalProperties:
        type: array
        items:
          type: string
    DigitalIdWalletApiClientCredentialsForbiddenErrorMessage:
      type: object
      properties:
        detail:
          type: string
          default: Forbidden - User doesn't have permission
    DigitalIdWalletApiWallet:
      type: object
      properties:
        id:
          type: string
          description: 钱包的目录 ID，例如 bankid_se。
        name:
          type: string
        issuing_authority:
          type: string
          nullable: true
      required:
        - id
        - issuing_authority
        - name
    DigitalIdWalletApiWalletVerificationResultOutcomeEnum:
      enum:
        - pending
        - verified
        - cancelled
        - timeout
        - failed
      type: string
      description: |-
        * `pending` - 待处理
        * `verified` - 已验证
        * `cancelled` - 用户已取消
        * `timeout` - 已超时
        * `failed` - 已失败
    DigitalIdWalletApiInteractionEnum:
      enum:
        - redirect
        - in_app
        - digital_credentials
      type: string
      description: |-
        * `redirect` - 重定向
        * `in_app` - 应用内
        * `digital_credentials` - 数字凭证
    DigitalIdWalletApiWalletNextAction:
      type: object
      properties:
        type:
          allOf:
            - $ref: '#/components/schemas/DigitalIdWalletApiWalletNextActionTypeEnum'
          description: >-
            redirect：将用户浏览器重定向至 url。confirm_in_app：向用户显示
            verification_code，用户核对该验证码与其钱包应用中的代码一致后在应用内确认；随后进行轮询。request_digital_credential：在您最初发起流程的源上通过用户手势调用
            digital_credentials.request 请求钱包，然后将返回的内容发送至 POST
            .../verifications/{request_id}/response/。


            * `redirect` - redirect

            * `confirm_in_app` - confirm_in_app

            * `request_digital_credential` - request_digital_credential
        url:
          type: string
          format: uri
          description: 仅限 redirect：用户使用钱包登录的页面。
        digital_credentials:
          allOf:
            - $ref: >-
                #/components/schemas/DigitalIdWalletApiWalletDigitalCredentialsRequest
          description: 仅限 request_digital_credential：传递给钱包的请求内容。
        verification_code:
          type: string
          description: 仅限 confirm_in_app：钱包应用上同步显示的 4 位比对码。
        poll_interval_seconds:
          type: integer
          description: >-
            仅限 confirm_in_app：调用 POST .../verifications/{request_id}/poll/
            以获取即时反馈的频率。Didit 还会在后台轮询待处理的登录，因此即使您不进行轮询，Webhook 也会报告结果。
      required:
        - type
    DigitalIdWalletApiWalletIdentity:
      type: object
      properties:
        full_name:
          type: string
          nullable: true
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        date_of_birth:
          type: string
          format: date
          nullable: true
        nationality:
          type: string
          nullable: true
          description: ISO3 国籍，仅在钱包明确声明时提供（绝不进行推断）。
        issuing_state:
          type: string
          description: 签发该身份的方案所属的 ISO3 国家/地区。
      required:
        - date_of_birth
        - first_name
        - full_name
        - issuing_state
        - last_name
        - nationality
    DigitalIdWalletApiWalletNextActionTypeEnum:
      enum:
        - redirect
        - confirm_in_app
        - request_digital_credential
      type: string
      description: |-
        * `redirect` - 重定向
        * `confirm_in_app` - 应用内确认
        * `request_digital_credential` - 请求数字凭证
    DigitalIdWalletApiWalletDigitalCredentialsRequest:
      type: object
      properties:
        protocol:
          type: string
          description: openid4vp-v1-signed。
        request:
          type: object
          additionalProperties: {}
          description: >-
            原样传递：在浏览器中为 navigator.credentials.get({digital: request})，或在 Android
            上作为 GetDigitalCredentialOption 的 requestJson 传入
            JSON.stringify(request)。由 Didit 为您的应用签名。
      required:
        - protocol
        - request
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        您的应用 API 密钥，可在 Business Console 的“开发者 -> API
        密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于
        IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP
        列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF
        URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅
        https://docs.didit.me/console/api-keys。
    BearerAuth:
      type: http
      scheme: bearer
      description: 该应用的客户端凭证访问 token。

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.