Opportunity Creation and Pipeline Progression

An AE creates an opportunity from a converted lead or manually, selecting the account, defining expected close date, stage, and estimated value. As the deal progresses, the AE updates the stage through defined pipeline stages (e.g., Discovery → Demo → Proposal → Negotiation → Closed Won/Lost). Stage transitions trigger automated tasks, notifications, and required field validations. A Closed Won moves the opportunity to order creation;
a Closed Lost captures competitor and loss reason.

opportunity { id: string (opp_*), external_id: string, account_id: string, stage: enum, probability: int, estimated_value_minor: int64, currency_code: char(3), close_date: date, win_loss_reason: string, stage_history: array, created_at: timestamp, status: enum(OPEN, CLOSED_WON, CLOSED_LOST) };
linked to account, contact, sales_order;
(reference, product may differ).

POST /v1/opportunities { external_id, account_id, stage, estimated_value_minor, currency_code, close_date } -> 201 { id, probability, status };
PATCH /v1/opportunities/{id} { stage, win_loss_reason } -> 200;
GET /v1/opportunities/{id};
emits opportunity.stage_changed, opportunity.closed_won, opportunity.closed_lost events;
idempotent via external_id.

OPEN(Discovery) -> OPEN(Demo) -> OPEN(Proposal) -> OPEN(Negotiation) -> CLOSED_WON | CLOSED_LOST;
terminal CLOSED_WON, CLOSED_LOST;
guard: CLOSED_WON and CLOSED_LOST require win_loss_reason;
each stage transition enforces required field validation;
stage duration tracked per transition.