# For Schools Operator API

For Schools Operator API is the protected follow-up surface for school-side partnership leads.

## Public schema

- /api/for-schools/operator-openapi: OpenAPI 3.1 schema for school-side assistant follow-up

## Protected endpoints

These endpoints require Authorization Bearer credentials:

- GET /api/for-schools/operator-leads
- POST /api/for-schools/operator-actions
- GET /api/for-schools/operator-prospects
- POST /api/for-schools/operator-outreach-actions
- POST /api/for-schools/operator-prospect-leads
- POST /api/commercial/operator-send-buyer-reply
- POST /api/commercial/operator-send-follow-up
- POST /api/commercial/operator-reply-intake-record
- POST /api/commercial/operator-payment-evidence-record
- POST /api/commercial/operator-payment-evidence-import

## Assistant workflow

The assistant should:

1. Fetch school operator leads.
2. Process hot payment-ready or checkout-intent school leads before warm leads. Use salesPriority, salesPriorityReason, and closingPath to explain the next move.
3. Use nextOperatorAction to decide whether to send the school reply pack, request one official URL, prepare a scope confirmation, send a payment request, watch external payment evidence, deliver the repair kit, or run one post_delivery_growth follow-up.
4. Build the shared commercial queue itemId as for_schools:{leadId}.
5. Use dryRun before a real school-side send with POST /api/commercial/operator-send-buyer-reply.
6. Use follow-up only after the first school reply or URL request. POST /api/commercial/operator-send-follow-up sends only the queue item's followUpDraft, does not accept arbitrary recipient email, and does not automatically record recommendedActionPayload.
7. Use operator-payment-evidence-record only after external payment provider evidence exists. POST /api/commercial/operator-payment-evidence-record uses itemId for_schools:{leadId}, provider evidence, amountJPY, and evidenceNote, then records payment_confirmed. Do not use buyer email claims as payment evidence.
8. Use operator-payment-evidence-import for payment provider webhook or import automation. POST /api/commercial/operator-payment-evidence-import accepts generic or Stripe-like payloads with itemId for_schools:{leadId}; auth uses x-commercial-payment-evidence-secret.
9. After repair_delivered, use post_delivery_growth once: send one proof request, one second official URL repair offer, and one referral ask; then record post_delivery_follow_up_sent.
10. Use operator-reply-intake-record when a school replies by email and you want the server to analyze and record one safe action. POST /api/commercial/operator-reply-intake-record uses itemId for_schools:{leadId}. Does not accept arbitrary record endpoints or recordBody. Will not record payment_confirmed from buyer email alone.
11. Use operatorReplyPacket, schoolReplyPack, and salesChecklist as the reply basis; the shared send endpoint does not accept arbitrary recipient email.
12. Record the operator action after a reply, official URL request, scope confirmation, payment request, external payment evidence, repair delivery, post-delivery growth follow-up, or close-lost decision.
13. Never promise placement, ranking, or admission outcomes.
14. Ask for one official URL before drafting claims.
15. Do not invent official facts, fees, deadlines, Open Campus dates, or admission requirements.
16. For outbound prospecting, fetch GET /api/for-schools/operator-prospects and use outreachSalesPack
    (for_schools.outreach_sales_pack.v1) as the first-contact packet.
17. Use outreachSalesPack.firstEmailSubject and outreachSalesPack.firstEmailBody for the first email, and
    outreachSalesPack.internalForwardText when the school contact needs a 校内転送用 memo.
18. Record outreach_sent only after the first email is actually sent. Record school_replied only after an identifiable
    school reply, then call /api/for-schools/operator-prospect-leads before requesting payment.

## Operator action sequence

The intended sales workflow is:

send_school_reply -> request_official_url -> prepare_scope_confirmation -> scope_confirmed -> send_payment_request -> watch_payment -> deliver_school_repair

Use school_reply_sent, official_url_requested, scope_confirmed, payment_request_sent, payment_confirmed, repair_delivered, or closed_lost as the recorded operator action state.

## Payment and fallback behavior

- If FOR_SCHOOLS_PAYMENT_URL, FOR_SCHOOLS_PAYMENT_URL_AI_DIAGNOSIS, FOR_SCHOOLS_PAYMENT_URL_OPEN_CAMPUS, or
  FOR_SCHOOLS_PAYMENT_URL_OFFICIAL_INFO is configured, paymentRequestPack can send the buyer to a direct payment URL.
- If payment URLs are missing, use the manual_invoice fallback. The public success UI exposes
  paymentRequestPack.confirmationText and fallbackMailto so the buyer can confirm purchase by email.
- If the primary CRM table is missing or unavailable, accepted leads are still recoverable from
  for_schools_partnership_lead_backup in analytics_events.

## Commercial purpose

This API exists so OpenClaw, Hermes, or another sales assistant can handle first response and qualification work for
school-side one-time packages without reading internal database tables.