流马 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 /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 unless overridden). The customer token is returned here and must be sent later as a bearer token.

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. Repeating the call reuses the existing session.

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.

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