流马 Liuma Chief Talent Officer consultation

Reference

HTTP API

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.

openapi.json · llms.txt · service JSON

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