DPP 注册系统 API 集成指南（第5—10页）：认证、注册流程、任务跟踪与错误处理

--- page 5 --- DPP Registry API Integration Guide Chapter 1. Introduction | 5 Chapter 1. Introduction 1.1 About this Guide Purpose and audience This guide is intended for Economic Operators and the developers or architects integrating their systems with Registry and Activity Dashboard APIs. It assumes familiarity with HTTP, JSON and Bearer authentication. It explains the registration process, the API calls involved and the client behaviour required to complete and monitor a registration request. DPP Registration and activity tracking at a glance Registry accepts DPP registration submissions containing one or more DPP items. Each submission contains a common product classification and between 1 and 100 submissionItems. Activity Dashboard provides centralised visibility into the asynchronous task created for each accepted submission, including its lifecycle status, business outcome and per-item processing evidence. 1.2 Core concepts Submission acceptance When Registry accepts a submission, it returns 202 Accepted and opens an asynchronous task used to process and track the registration: 1. The response includes a taskId, which is the identifier used for subsequent Activity Dashboard operations. 2. When estimatedPeriodCompletionTime is provided, use that ISO 8601 duration as guidance for when to query Activity Dashboard for the first time. The estimate is not a completion guarantee. 3. The acceptance response does not represent the current task lifecycle status. Retrieve GET /api/v1/tasks/{taskId} to determine whether the task is PENDING, PROCESSING, COMPLETED or ERROR. Task lifecycle and business outcome Activity Dashboard separates the lifecycle of the asynchronous task from the business outcome produced by that task. • PENDING: means that the task has been created and is waiting to be processed. • PROCESSING: means that asynchronous processing is in progress. • COMPLETED: means that task processing finished and a business outcome is available. • ERROR: means that the task itself could not be complete successfully. For a COMPLETED task, inspect outcome.outcomeResult to determine the business outcome: • SUCCEEDED: positive business outcome. • FAILED: negative business outcome, for example when one or more submitted DPP items are non- --- page 6 --- DPP Registry API Integration Guide Chapter 1. Introduction | 6 compliant. Registration submissions are atomic: if any submitted item is non-compliant, none of the items in that submission are registered. A business outcome of FAILED does not mean that the asynchronous task failed technically. A task may therefore have status=COMPLETED and outcomeResult=FAILED. The unique product identifier The uniqueProductIdentifier (UPI) shall be in a URL format. Registry uses the UPI exactly as submitted as the initial URL of the DPP resource. Digital product passport validation Upon submission for registration, the registry shall read the digital product passport content and validate it in accordance with Commission implementing regulation (EU) 2026/1778. The DPP resource must therefore be reachable at validation time. An unreachable resource results in UPI_NOT_RESOLVABLE. Registry does not persist the fetched DPP payload content. Organisation scoping and the verification prerequisite Registry operations are scoped to the Organisation associated with the authenticated principal, clients do not pass an organisation ID in registration requests. An Economic Operator must complete Organisation verification during onboarding before using Registry integration capabilities. Requests from an Organisation that is not eligible for registration are rejected. --- page 7 --- DPP Registry API Integration Guide Chapter 2. Getting started | 7 Chapter 2. Getting started 2.1 Prerequisites and setup Authentication Protected endpoints require a Bearer JWT in Authorization: Bearer <token>. For machine-to-machine integrations using Service Accounts, see the DPP Registry Service Account Technical Integration Guide for the authentication and access-token acquisition procedure. The Organisation and authenticated principal are derived from the token. Environments and base URLs Use the Registry and Activity Dashboard base URLs published for the target environment. Do not derive deployment endpoints from placeholder or local-development host values in the API specifications. Submission headers Header Required Purpose X-Correlation-Id No Correlates the request with downstream processing and support diagnostics. If omitted, the backend generates and propagates one. Idempotency-Key Yes Provides replay-safe deduplication (maximum 128 characters). Reusing the same key returns the original accepted task. Fetch reference data first Before submitting a registration, call GET /api/v1/dpp/product-groups and use the productGroup and, where applicable, productSubGroup corresponding to the product being registered. The returned values are Registry product-classification reference data and are not arbitrary selections. First end-to-end registration flow • Step 1: Confirm that the Organisation has completed verification and that the caller is authorised to register DPPs. For a Service Account, use a Service Account configured with the Register DPPs role. • Step 2: Retrieve the Registry product-classification reference data with GET /api/v1/dpp/product- groups and use the productGroup and, where applicable, productSubGroup corresponding to the DPP being registered. • Step 3: Ensure that each DPP is reachable through its uniqueProductIdentifier, then send POST /api/v1/dpp/submission. For a first single-DPP registration, provide exactly one element in submissionItems. Store the returned taskId. If estimatedPeriodCompletionTime is returned, use it as guidance for when to query the task for the first time. • Step 4: After the estimated period, call GET /api/v1/tasks/{taskId} in Activity Dashboard. If the task is PENDING or PROCESSING, continue querying until it reaches a terminal state. If it is --- page 8 --- DPP Registry API Integration Guide Chapter 2. Getting started | 8 COMPLETED, inspect outcome and specificTaskData. If it is ERROR, treat the task as a technical processing failure. Use GET /api/v1/tasks/{taskId}/items when per-item processing evidence is required. Figure 1 - End-to-end registration flow --- page 9 --- DPP Registry API Integration Guide Chapter 3. Registering DPPs | 9 Chapter 3. Registering DPPs 3.1 Registration submission The submission contract Send POST /api/v1/dpp/submission with Content-Type: application/json: { "productGroup": "BATTERIES", "productSubGroup": "EV", "submissionItems": [ { "uniqueProductIdentifier": "https://example.com/dpp/battery/0001", "granularity": "item", "batchIdentifier": "xxx-000", "modelIdentifier": "yyy-111" } ] } uniqueProductIdentifier is required for every submitted item. The example above also includes fields applicable to this productGroup. Other product groups may define additional or different product-specific fields. Always use the fields defined by the Registry contract for the selected product group and product sub- group. A registration submission always uses the same JSON contract. Use one submissionItems element to register a single DPP and multiple elements to register several DPPs sharing the same request-level product classification. Idempotent submission Send Idempotency-Key with every registration submission. The key identifies one logical action within the REST resource to which the request is submitted. When retrying the same logical submission, reuse the same Idempotency-Key. Registry associates the retry with the original action and returns the outcome associated with that action rather than creating a duplicate submission. A new or modified logical submission to the same resource requires a new Idempotency-Key. Reusing a key already associated with another logical action on the same resource is treated as an idempotency conflict and does not create a new action. Idempotency keys are scoped to the REST resource. The same key value may therefore be used independently for requests to different resources without creating an idempotency conflict. Clients should treat an Idempotency-Key as bound to a single logical action within a given REST resource and should not reuse the same key for a different action on that resource. Reading the 202 A 202 Accepted response confirms that Registry accepted the request for asynchronous processing, it does not mean that registration is complete. --- page 10 --- DPP Registry API Integration Guide Chapter 3. Registering DPPs | 10 Field Meaning taskId Primary identifier used to track the asynchronous operation through Activity Dashboard. taskType Type of asynchronous task created by the submission. For DPP registration: DPP_REGISTRATION. submittedAt Time at which the task-bearing request was accepted. correlationId End-to-end correlation identifier for tracing and support. estimatedPeriodCompletionTime Optional estimated time until completion, expressed as an ISO 8601 duration, for example PT10S. Use it as guidance before the first task query. updatedAt Timestamp of the latest task update returned with the acknowledgement. 3.2 Single and multiple-item submissions The same POST /api/v1/dpp/submission operation and request schema are used for both single and multiple-item registrations. To register a single DPP, provide one element in submissionItems. To register multiple DPPs, provide between 2 and 100 elements. productGroup and, when applicable, productSubGroup apply to the complete submission. DPPs that belong to different product classifications must therefore be submitted in separate requests. Each submissionItems element requires its own uniqueProductIdentifier and may contain additional fields defined by the registration schema applicable to the selected product group. A registration submission is atomic. Registry validates all submitted items before completing the registration. If every submitted item is compliant, the submission can complete successfully and the DPPs are registered. Registration atomicity If one or more submitted items are non-compliant, the complete submission has a negative business outcome and none of the submitted DPPs are registered, including items that individually passed validation. The task result reports the number of submitted, compliant and non-compliant items. Use the per-item processing evidence to identify which items caused the submission to fail. 3.3 Tracking processing After a registration submission is accepted, use the returned taskId to track it through Activity Dashboard. When estimatedPeriodCompletionTime is provided in the 202 Accepted response, wait approximately the indicated period before making the first GET /api/v1/tasks/{taskId} request. If the task is still PENDING or PROCESSING, the client should apply a Fibonacci polling backoff for subsequent requests. Recommended polling intervals are 1, 1, 2, 3, 5, 8, 13, 21, 34 and 55 seconds, after which the client shall cap its own polling interval at 60 seconds until the task reaches a terminal state. If an HTTP response includes Retry-After, wait at least the period indicated by that header before sending the next request. Retry-After takes precedence over the client-generated polling interval and may therefore exceed the normal 60-second polling cap. When the task reaches COMPLETED, inspect outcome for the overall business result and specificTaskData.processingInfo for the aggregate compliance result of the submitted items. Use GET /api/v1/tasks/{taskId}/items when per-item processing evidence is required. If the task reaches ERROR, treat it as a technical processing failure.