MedBridge Sales Ops
Overview
This skill covers three core workflows against the shared MedBridge Sales Ops API.
The API base URL is provided by the runner as <TASK_ENV_BASE_URL>.
Every response must be valid JSON matching the supplied answer template; include no
markdown or narrative outside the JSON.
Consult api_endpoints.md for the full endpoint catalog and entity relationships. Consult policies.md for business rules on payment terms, freight validity, revenue recognition, and module granularity.
Workflow 1: Quote + Freight Decision Package
Triggered when given a quote ID and a confirmed quantity/date. The output includes EXW pricing, three freight modes (air/sea/road) with totals, risk flags, and policy recommendations.
Step 1 -- Gather records
Fetch in parallel:
GET /api/quotes/<quote_id>GET /api/customers/<customer_id>(from quote)GET /api/products/<product_code>(from quote'sprimary_product_code)GET /api/freight-quotes(filter byquote_idto the target quote)GET /api/policies
Step 2 -- Select the catalog tier
From the product's price_tiers[], find the tier where confirmed_quantity
falls in [min_qty, max_qty]. max_qty: null means unbounded upper limit.
Use that tier's unit_price_usd, lead_time_days. Take shelf_life_months
from the product root.
exw_total_usd = confirmed_quantity * unit_price_usd
Step 3 -- Filter freight quotes
Keep only records where:
quote_idmatches the target quotestatusisactive(discardstaleandmismatch)modeis one of air, sea, road for the target quote
Ignore distractor freight records tied to other quotes or with wrong shipment dimensions.
Step 4 -- Validate and flag freight
For each mode:
validity_status:VALIDifvalid_until >= quote_date, elseSTALEsource_is_stale: true ifvalid_until < quote_daterisk_flag: maproute_risklow->NONE, medium->MEDIUM_BORDER_RISK, high->HIGHgrand_total_usd = exw_total_usd + freight_cost_usd
A stale road quote with high border risk should not be recommended.
Step 5 -- Apply policy rules
recommended_mode: prefer SEA when valid and low-risk; AIR for urgent deadlines; avoid stale/high-risk roadfreight_reconfirmation_required: true whenever freight is presentedall_freight_options_valid_on_quote_date: false if any mode is stalepayment_terms: from customer'spayment_profileor policy matchcustomer_policy: derive from segment (e.g.,RECURRING_NGO,RECURRING_COMMERCIAL,NEW_CLIENT,MILESTONE_BILLING)
Validation checklist
- Confirm the total is
confirmed_quantity * unit_price_usd - Check every
grand_total_usd = exw_total + freight_cost - Verify
payment_termsmatches the customer's payment profile - Verify freight validity dates are compared against
quote_date
Workflow 2: RFQ-to-Quote (Indicative / EXW-Only)
Triggered when given an RFQ ID, typically for a new/prospect customer with no confirmed destination. Produce EXW-only line items at module granularity.
Step 1 -- Gather records
Fetch in parallel:
GET /api/rfqs/<rfq_id>GET /api/customers/<customer_id>(from RFQ)GET /api/policies- For each
product_codeinrequested_modules[], fetchGET /api/products/<code>
Step 2 -- Build line items
For each requested_module:
- Use
product_codeandquantitydirectly from the RFQ - Get
article_numberfrom product - Get
unit_pricefrom the product's price tier matchingquantity line_total = quantity * unit_pricelead_time_daysandshelf_life_monthsfrom the matching tier / product
Keep modules whole. The RFQ's component_composition_distractors[] and
the product's components[] are for medical review only; do not split into
component SKUs.
Step 3 -- Set quote controls
grand_total: sum of allline_totalvaluesfreight_excluded: true (no destination -> EXW only)payment_terms:PREPAY_100for new/prospect customers; otherwise from customer'spayment_profileoffer_validity_days: 30who_documentation_required: true for IEHK-style modules; false otherwise
Workflow 3: Engagement Reconciliation
Triggered when given an opportunity ID and customer ID. Produces a full reconciliation with milestone states, revenue recognition gaps, collection tasks, and event/voucher follow-ups.
Step 1 -- Gather records
Fetch in parallel:
GET /api/opportunities/<opp_id>GET /api/customers/<customer_id>GET /api/invoices(filter byopportunity_id)GET /api/payments(filter byopportunity_id)GET /api/revenue-journals(filter byopportunity_id)GET /api/events(filter byopportunity_id)GET /api/vouchers(find the one matching the event'svoucher_code)
Step 2 -- Reconcile milestones
For each phase in opportunity.phases[]:
- Find the matching invoice by
invoice_id(from phase) orphase_id - Determine
payment_state: PAID ifpaid_amount_usd == amount_usd, PARTIAL if0 < paid_amount < amount, else UNPAID - Determine
recognition_status:- If paid and journal exists ->
RECOGNIZED - If paid and journal missing ->
MISSING_REVENUE_JOURNAL - If unpaid ->
NOT_REQUIRED_UNPAID
- If paid and journal exists ->
due_datefrom invoice, or null if paid
Step 3 -- Revenue recognition summary
recognition_status:COMPLETE_FOR_PAID_MILESTONESif every paid milestone has a journal;MISSING_FOR_PAID_MILESTONESif any paid milestone lacks onerecognized_milestones[]: list of milestone IDs with journalsmissing_required_milestones[]: list of paid milestone IDs without journalsrecognized_amount: sum of recognized journal amounts
Step 4 -- Follow-up tasks
Generate tasks for:
Collections -- for each unpaid/overdue milestone:
- If
due_dateis in the future:MONITOR_UNPAID_NOT_DUE, ownerACCOUNT_MANAGEMENT - If
due_dateis in the past:SEND_COLLECTION_NOTICE, ownerCOLLECTIONS
Revenue recognition -- for each paid milestone missing a journal:
- Action:
RECORD_REVENUE_MSx, ownerACCOUNTING - Debit:
DEFERRED_REVENUE, Credit:IMPLEMENTATION_SERVICES_REVENUE
Event invitations -- for each event linked to the opportunity that is
scheduled or confirmed with a future date:
- Action:
SEND_EVENT_INVITATIONorSEND_BRIEFING_INVITE - Include
event_id,voucher_code, contact info - Owner:
ACCOUNT_MANAGEMENT
Step 5 -- Cross-check totals
phase_total_amount= sum of all phaseamount_usdvaluestotal_paid_amount= sum of allpaid_amountvalues from invoicesoutstanding_balance=won_amount - total_paid_amountopportunity_matches_phase_total: true ifwon_amount == phase_total_amount
Common Pitfalls
- Distractor freight records: The freight-quotes collection includes records
for unrelated quotes, with stale/mismatch statuses, wrong dimensions, or
different
quote_idvalues. Always filter byquote_idandstatus: active. - Component-composition distractors: RFQs and products list component breakdowns that are for medical review only. Quote at the module/product level unless the prompt explicitly asks for component-level pricing.
- Old tier traps: Prior quotes used different quantities. Always use the
current
confirmed_quantityagainst the product'sprice_tiers[]; never reuseprior_unit_price_usdfrom the quote line item. - Stale freight validity: Check
valid_untilagainstquote_date-- a freight quote expired before the quote date is unusable even if itsstatusfield still saysactive. - Missing revenue journals: A paid milestone without a corresponding revenue journal entry is an accounting gap. Flag it, don't assume it exists.
- New-client payment terms: Prospect customers always use
PREPAY_100, regardless of what a similar-looking active customer uses.