Entity Document Renewal Guide

Core Interaction Flow 📊

sequenceDiagram
    autonumber
    actor User as User
    participant Partner as Partner
    participant DogPay as DogPay

    Note over Partner, DogPay: 1. Query document update requests
    Partner->>DogPay: GET /v2/openapi/openapi/entity-document-update-requests
    DogPay-->>Partner: Return request list (with update_request_id)

    Note over Partner, DogPay: 2. Upload the new document file
    Partner->>DogPay: POST /open-api/v1/file/upload
    DogPay-->>Partner: Return file_id

    Note over Partner, DogPay: 3. Submit the document file and new expiry date
    Partner->>DogPay: POST /v2/openapi/openapi/entity-document-update-requests/{id}/submit
    DogPay-->>Partner: 202, request status changes to in_review

    Note over Partner, DogPay: 4. Review result
    Partner->>DogPay: Re-query the request status
    DogPay-->>Partner: Return completed or rejected

Standard Workflow ⚙️

1. Query pending update requests: Call the query endpoint to retrieve the document update requests that need to be processed, then confirm document_type, status, and update_request_id.
2. Upload the new document file: Call the upload file endpoint to obtain the file_id. Do not pass the local raw file directly to the submission endpoint.
3. Submit the update information: Call the submission endpoint with update_request_id, files, and new_expiry_date.
4. Wait for the review result: After a successful submission, the request enters in_review; once the review is completed, the status changes to completed, or to rejected if the request is not approved.

Query Document Update Requests 🔍

List Entity Document Update Requests

GET /v2/openapi/openapi/entity-document-update-requests

Results are sorted by expiry date in ascending order, with requests that do not have an expiry date placed last, and then by creation time in descending order. If the status filter is omitted, all document update requests for the current account are returned. data is an empty array when there are no matching requests.

Response Fields

Upload the New Document File 📤

Before submission, you must call the Upload File endpoint to obtain the file ID.

When uploading, fill in fileUseType according to the upload endpoint requirements and ensure that the uploaded file corresponds to the document_type of the current request. After a successful upload, save the returned file ID and pass it into the files array of the submission endpoint.

Submit Document Update Files 🚀

Submit Entity Document Update Files

POST /v2/openapi/openapi/entity-document-update-requests/{id}/submit

Request example:

{
  "files": [
    "9f1c6d2a-3b4e-4f7a-8c1d-2e5b7a9c0d31"
  ],
  "new_expiry_date": "2027-01-01"
}

On success, the endpoint returns 202, data contains the latest request state, and status is in_review.

Status Transitions

Error Code Summary 📊

Core Constraints and Rules 🛡️

Typical Scenarios 💡