Online Renewal Invoice API

This document contains five invoice APIs for the frontend in the online renewal process: invoice title query, invoice application submission, single order and batch invoice progress query, and electronic invoice download.

General Conventions

• API prefix: /v3/console/package-renewal-order
• APIs require the existing console login session. User identity and order ownership are obtained by the server from the login session. Do not and must not pass unionId in the request.
• The POST of the request is Content-Type application/json.
• Successful response format: { "code": 200, "status": "success", "data": ... }.
• For failed responses, the status is error, with error details in error.code and error.desc. The frontend should use status === "success" to determine business success.

Order List Invoice Eligibility Fields

The following fields are added to each order item in GET /v3/console/package-renewal-order/list:

The frontend only handles the invoice entry for orders where canApplyInvoice=true: display "Apply for Invoice" for NOT_APPLIED, display "Download Invoice" for ISSUED, and show the application progress for other statuses. The batch query API can be used for partial status refresh.

Server State Synchronization

After a customer submits an application, the application status is initially PROCESSING. The payment service polls PCS/CRM according to the cycle configured in ONLINE_INVOICE_POLL_INTERVAL_SECONDS, and writes ISSUED, FAILED, invoice number, PDF URL, and failure reason back to the application table; polling stops once a final state is reached. Polling uses database leases to prevent multiple instances from updating the same application. The frontend does not need to rely on page refreshes to advance the status.

1. Query Historical Invoice Titles

Query existing invoice titles in CRM by company name to auto-fill the taxpayer identification number. Returns an empty array if no record is found; this does not indicate a request failure.

Request

GET /v3/console/package-renewal-order/invoice-title

Request example:

GET /v3/console/package-renewal-order/invoice-title?companyName=广州保利云科技有限公司

Response Data

data is an array:

Response example:

{
  "code": 200,
  "status": "success",
  "data": [
    {
      "companyName": "广州保利云科技有限公司",
      "taxpayerId": "91440101MA5XXXXXXX"
    }
  ]
}

It is recommended that the frontend call this after the user finishes entering the company name; if multiple records are returned, allow the user to select the corresponding taxpayer identification number.

2. Submit Invoice Application

Submit an electronic invoice application for the current logged-in user's online renewal order. The server validates order ownership and eligibility conditions, and handles duplicate submissions for the same order idempotently.

Request

POST /v3/console/package-renewal-order/invoice-application

Request body fields:

Request example:

{
  "orderId": "renewal_order_123456",
  "invoiceType": "VAT_NORMAL",
  "companyName": "广州保利云科技有限公司",
  "taxpayerId": "91440101MA5XXXXXXX"
}

Response Data

data is the invoice application information:

Response example:

{
  "code": 200,
  "status": "success",
  "data": {
    "orderId": "renewal_order_123456",
    "requestNo": "invoice_request_123456",
    "invoiceType": "VAT_NORMAL",
    "companyName": "广州保利云科技有限公司",
    "taxpayerId": "91440101MA5XXXXXXX",
    "amountCent": 99800
  }
}

The example only shows core fields; the actual response will include invoice status and invoice information as per the table above. Disable repeated clicks before submission; even if duplicate submissions occur due to network retries, the server handles idempotency per order. Successful submission only means the application has been accepted.

3. Query Invoice Progress

Query the invoice application status for a specified renewal order of the current logged-in user. This API synchronizes the latest status from CRM and is suitable for calling after application submission or when refreshing the order detail page.

Request

GET /v3/console/package-renewal-order/invoice-application

Request example:

GET /v3/console/package-renewal-order/invoice-application?orderId=renewal_order_123456

Response Data

The complete fields of data are consistent with the response data in Section 2 "Submit Invoice Application". Focus on the following fields:

Response example:

{
  "code": 200,
  "status": "success",
  "data": {
    "orderId": "renewal_order_123456",
    "requestNo": "invoice_request_123456",
    "statusName": "开票中",
    "invoiceApplicationStatus": "PROCESSING"
  }
}

When the order has not been applied for, the API returns:

{
  "code": 200,
  "status": "success",
  "data": {
    "orderId": "renewal_order_123456",
    "invoiceApplicationStatus": "NOT_APPLIED"
  }
}

4. Batch Query Invoice Progress

Used for batch determination of action items in the order list. This API only accepts paid renewal orders eligible for online invoicing belonging to the current logged-in user; if any order does not meet the conditions, the entire request returns a business failure.

Request

POST /v3/console/package-renewal-order/invoice-application/batch

Request body fields:

Request example:

{
  "orderIds": [
    "renewal_order_123456",
    "renewal_order_654321"
  ]
}

Response Data

data is an object keyed by order ID. Each value contains invoiceApplicationStatus, whose value is consistent with the order list field; orders that have not been applied only return orderId and invoiceApplicationStatus=NOT_APPLIED.

{
  "code": 200,
  "status": "success",
  "data": {
    "renewal_order_123456": {
      "orderId": "renewal_order_123456",
      "statusName": "已开票",
      "invoiceApplicationStatus": "ISSUED",
      "invoiceNo": "1234567890",
      "pdfUrl": "https://example.com/invoices/invoice_request_123456.pdf"
    },
    "renewal_order_654321": {
      "orderId": "renewal_order_654321",
      "invoiceApplicationStatus": "NOT_APPLIED"
    }
  }
}

Order list display rules: Display "Apply for Invoice" when invoiceApplicationStatus=NOT_APPLIED; display "Download Invoice" when ISSUED; show application progress for other statuses. Do not use the status numeric value for frontend branching.

5. Get Electronic Invoice PDF Download URL

Get the electronic invoice PDF URL for an invoiced renewal order of the current logged-in user. If the order has not been invoiced, the server returns a business failure response.

Request

GET /v3/console/package-renewal-order/invoice-download

Request example:

GET /v3/console/package-renewal-order/invoice-download?orderId=renewal_order_123456

Response Data

The complete fields of data are consistent with the response data in Section 2 "Submit Invoice Application", where pdfUrl is the core field of this API. After obtaining pdfUrl, the frontend can open it in a new window or handle it according to the existing download strategy.

Response example:

{
  "code": 200,
  "status": "success",
  "data": {
    "orderId": "renewal_order_123456",
    "requestNo": "invoice_request_123456",
    "invoiceNo": "1234567890",
    "pdfUrl": "https://example.com/invoices/invoice_request_123456.pdf"
  }
}

Recommended Call Sequence

1. After the user fills in the company name, call "Query Historical Invoice Titles" to auto-fill or select the taxpayer identification number.
2. After the user confirms the invoice information, call "Submit Invoice Application".
3. Call "Batch Query Invoice Progress" in the order list; call "Query Invoice Progress" on the order detail page or application result page, and display the status based on statusName and failureReason.
4. After invoicing, call "Get Electronic Invoice PDF Download URL" and use the returned pdfUrl to download or preview the invoice.