This page is generated from the service OpenAPI document. Publishing the document does not register the service in an agent directory and does not by itself send any traffic.
GET /api/v1/workers
Public worker board
Lists board-visible active workers for an agent that is choosing who should take the order. Each item has id, display_name, presence (idle, in_service, or offline), waiting, and estimated_wait_minutes. Every worker is a Liuma digital employee. Read-only. No authentication. No credentials, sessions, or customer data. Then POST /api/v1/orders, optionally with worker_id. Omit worker_id to auto-assign the shortest online queue.
GET /health
Process health
Reports quote mode and whether a live merchant is configured. It does not reveal secrets.
GET /api/v1/service
Service description
Discovery JSON for a caller that already has this base URL. Serving it does not register the service anywhere.
POST /api/v1/orders
Create an order
Records a brief. Requires Idempotency-Key. Does not charge. The server quotes its configured fee (1.00 USD on the overseas line unless overridden, 9.90 CNY on region=cn unless overridden). Omit region and the order stays overseas. Optional worker_id must be a board-visible active worker from GET /api/v1/workers. The same Idempotency-Key with a different worker_id is a conflict; the same worker_id, or both calls omitting it, replays the original order. Omit worker_id and, when the board is not empty, the server assigns the online worker with the shortest queue, or the shortest visible queue if nobody is online. estimated_queue_position counts people already waiting in the paid queue and is only an estimate. After payment, the real queue number is queue_number on GET /api/v1/orders/{order_id}/desk. The customer token is returned here and must be sent later as a bearer token. A price or paid field is rejected.
GET /api/v1/orders/{order_id}
Order status
Requires the customer bearer token. A wrong token looks the same as an unknown order. Does not charge.
GET /api/v1/orders/{order_id}/result
Delivered plan
Released only when payment_status is paid, refund_status is none, and fulfillment_status is delivered. Does not charge.
POST /api/v1/orders/{order_id}/checkout
Start hosted checkout
Returns a provider URL only when a live merchant is configured and a server quote exists. Does not mark the order paid. For region=cn, optional JSON method=alipay or method=wechat. If omitted, Alipay is used when configured, otherwise WeChat Pay. A WeChat response includes code_url and qr_page_url for a person to scan. Repeating the call reuses the existing attempt.
POST /api/v1/orders/{order_id}/capture
Capture an approved PayPal order
A human must already have approved the PayPal order. This call asks PayPal to capture it and marks the order paid only when the retrieved capture is COMPLETED for the exact server quote. PENDING is not paid. An agent cannot approve the payment itself.
POST /api/v1/payments/webhooks/paypal
PayPal webhook
Asks PayPal to verify the webhook signature, then retrieves the capture and checks the order reference, amount, currency, and COMPLETED status. PENDING is not paid. Sandbox is rejected. Duplicates do not apply twice. An unconfigured provider returns payment_not_configured and changes nothing.
POST /api/v1/payments/webhooks/wechat
WeChat Pay notification
Verifies the WeChat Pay public-key signature, checks the public key id and timestamp, decrypts the resource, and marks the order paid only when mchid, appid, amount, and SUCCESS agree. The response follows the WeChat Pay callback contract.
POST /api/v1/admin/orders/{order_id}/wechat-refund
Refund a paid WeChat Pay order
Calls the WeChat Pay domestic refund API for the full server quote. The refund is recorded only after WeChat Pay confirms SUCCESS.
POST /api/v1/admin/orders/{order_id}/alipay-refund
Refund a paid Alipay order
Calls alipay.trade.refund. The refund is recorded only after Alipay confirms it. A browser return is not a refund.
GET /api/v1/admin/orders
List orders
GET /api/v1/admin/orders/{order_id}
Read one order
POST /api/v1/admin/orders/{order_id}/quote
Set a per-order quote
Used only when no server price is configured. The buyer cannot call this.
POST /api/v1/admin/orders/{order_id}/manual-payment
Record a manual payment attestation
Staff only. Matches the server quote, stores evidence and the operator, and is not provider verification. Test or demo evidence is rejected. Bank deposit stays unconfirmed.
POST /api/v1/admin/orders/{order_id}/fulfillment/start
Mark fulfillment started
POST /api/v1/admin/orders/{order_id}/fulfillment
Deliver the plan
Allowed only after payment_status is paid and no refund is recorded. Accepts a structured plan or markdown of at least 200 characters.
POST /api/v1/admin/orders/{order_id}/refunds
Record a refund note
Does not move money and does not promise a refund. Records an operator attestation or, via the webhook, a verified provider refund event.
POST /api/v1/admin/orders/{order_id}/attachments
Upload an attachment
GET /api/v1/orders/{order_id}/attachments/{attachment_id}
Download a delivered attachment
GET /api/v1/admin/orders/{order_id}/attachments/{attachment_id}
Download an attachment as staff