MedBridge Sales Ops
Overview
The MedBridge Sales Ops API surfaces shared CRM, quote, logistics, and milestone engagement data for humanitarian and medical supply workflows. Use it to build quote decision packages, indicative pricing responses, account reconciliations, and engagement follow-ups.
API Setup
The API base URL is provided as <TASK_ENV_BASE_URL> by the task runner. All endpoints are read-only GET. Use curl for all API calls and python3 -c "import json" or python3 -m json.tool for JSON formatting.
Collection endpoints:
| Endpoint |
Description |
GET /api |
List all collections |
GET /api/search?q=<text> |
Full-text search across all collections |
GET /api/customers |
All customer records |
GET /api/customers/<id> |
Single customer |
GET /api/products |
All product catalog entries |
GET /api/products/<code> |
Single product by code |
GET /api/quotes |
All quotes |
GET /api/quotes/<id> |
Single quote |
GET /api/rfqs |
All RFQs |
GET /api/rfqs/<id> |
Single RFQ |
GET /api/freight-quotes |
All freight quotes |
GET /api/freight-quotes/<id> |
Single freight quote |
GET /api/policies |
All business policies |
GET /api/opportunities |
All opportunities |
GET /api/opportunities/<id> |
Single opportunity |
GET /api/invoices |
All invoices |
GET /api/invoices/<id> |
Single invoice |
GET /api/payments |
All payments |
GET /api/payments/<id> |
Single payment |
GET /api/revenue-journals |
All revenue journals |
GET /api/revenue-journals/<id> |
Single revenue journal |
GET /api/events |
All events |
GET /api/events/<id> |
Single event |
GET /api/vouchers |
All vouchers |
GET /api/vouchers/<code> |
Single voucher by code |
Always fetch related collections in parallel. For a quote revision, fetch the quote, customer, product, freight-quotes, and policies simultaneously. For an opportunity reconciliation, fetch the opportunity, its customer, invoices, payments, revenue-journals, events, and vouchers together.
Core Workflows
1. Quote Revision with Freight
Use when the user asks for a revised quote decision package with EXW pricing and freight comparisons.
Steps:
- Fetch the quote, customer, product, freight quotes, and policies in parallel.
- Identify the correct product price tier: match
confirmed_quantity to the tier where min_qty <= quantity <= max_qty (null max_qty means unlimited). Use the tier's unit_price_usd, lead_time_days, and shelf_life_months.
- Compute
exw_total_usd = confirmed_quantity * unit_price_usd.
- Filter freight quotes by
quote_id matching the quote. Sort modes as AIR, SEA, ROAD. For each, compute grand_total_usd = exw_total_usd + freight_cost_usd.
- Assess freight validity: a freight quote is STALE when
valid_until is before the quote_date. Route risk levels map to risk flags: low→NONE, medium→MEDIUM_BORDER_RISK, high→HIGH_BORDER_RISK.
- Determine the recommended mode: prefer SEA when it has low risk and is valid. Set
freight_reconfirmation_required: true per policy POL-FREIGHT-RECONFIRM.
- Derive payment terms from the customer's
payment_profile or the applicable policy (see business_rules.md).
- Check
all_freight_options_valid_on_quote_date — false if any freight option has valid_until before the quote date.
- Add a
freight_warning when any freight option is stale or has high border risk.
Example output shape: See business_rules.md for field mapping and value derivation rules.
2. Indicative RFQ / Module Quote
Use when the user asks for an indicative EXW-only quote from an RFQ, especially for module-level products.
Steps:
- Fetch the RFQ, customer, and products in parallel. Also fetch policies.
- For each module in the RFQ's
requested_modules, fetch the product by code for pricing, article_number, lead_time_days, and shelf_life_months.
- Quote at the module level only — do not split into components or sub-SKUs unless the prompt explicitly requests it. This follows policy POL-MODULE-GRANULARITY.
- Since the RFQ has no confirmed destination, exclude freight entirely. Set
quote_basis: "EXW_ONLY" and freight_excluded: true.
- For new NGO customers (
segment: "new_ngo"), use PREPAY_100 payment terms. For other customer types, match their payment_profile.
- Set
offer_validity_days: 30 per POL-QUOTE-VALIDITY.
- Each line item:
line_total = quantity * unit_price. Sum all line totals for grand_total.
- Products where
price_tiers has only one entry use that tier directly; no quantity matching is needed since the RFQ specifies the quantity.
3. Account Reconciliation
Use when the user asks to reconcile a won opportunity against invoices, payments, and revenue recognition, plus event/voucher linkage.
Steps:
- Fetch the opportunity, its customer, invoices, payments, revenue-journals, events, and vouchers in parallel. Use the search endpoint or direct ID lookups.
- Map opportunity phases to invoices by
phase_id or invoice ID reference. For each phase:
- Determine
invoice_state: paid / unpaid
- Determine
payment_state: from payment records linked by invoice_id
- Look up revenue recognition: a revenue journal entry linked by
invoice_id means RECOGNIZED
- For paid milestones with no revenue journal, status is
MISSING_REVENUE_JOURNAL
- For unpaid milestones, status is
NOT_REQUIRED_UNPAID
- Verify
opportunity_matches_milestones: won_amount equals sum of all phase amount_usd values.
- Compute
outstanding_balance: sum of unpaid amounts across phases.
- Link the event by
customer_id or opportunity_id. Retrieve the voucher by voucher_code.
- Generate follow-up tasks:
- Collection task for each unpaid milestone with a due date, linked to the opportunity and contact.
- Event invitation task when the event is scheduled/confirmed, linked to the contact.
See business_rules.md for complete status enum values and task routing rules.
4. Engagement Reconciliation with Accounting Actions
Use when the user asks for finance-ready reconciliation with accounting journal entries and collection routing.
Steps:
- Follow the same data gathering as workflow 3 (account reconciliation).
- For each milestone, compute detailed states:
invoice_state: from invoice status field (paid/unpaid)
payment_state: from payments linked to the invoice
recognition_status: cross-reference revenue journals by invoice_id
- Determine the primary accounting action:
- If any paid milestone lacks a revenue journal →
RECORD_REVENUE_MS2 (target the specific milestone ID)
- If all paid milestones have journals →
VERIFY_REVENUE_ONLY
- If no paid milestones →
NO_ACCOUNTING_ACTION
- Build the accounting action detail with the correct
debit_account (DEFERRED_REVENUE), credit_account (IMPLEMENTATION_SERVICES_REVENUE), and owner_queue (ACCOUNTING).
- Build the collection task: if unpaid milestone is not yet past due →
MONITOR_UNPAID_NOT_DUE with owner_queue: ACCOUNT_MANAGEMENT. If past due → SEND_COLLECTION_NOTICE with owner_queue: COLLECTIONS.
- Build the event invite task:
SEND_BRIEFING_INVITE when the event is scheduled or equivalent, with owner_queue: ACCOUNT_MANAGEMENT.
Data Relationships
See api_reference.md for the complete field reference for each collection.
Key joins:
- Quote → Customer (
customer_id), Product (line_items[].product_code), Freight Quotes (id matches quote_id)
- RFQ → Customer (
customer_id), Products (requested_modules[].product_code)
- Opportunity → Customer (
customer_id), Invoices (via phases[].invoice_id), Payments (invoice_id), Revenue Journals (invoice_id), Events (opportunity_id), Vouchers (opportunity_id)
- Event → Voucher (
voucher_code)
- Customer → Payment terms via
payment_profile or segment‑to‑policy mapping
Business Rules
See business_rules.md for:
- Policy‑to‑action mappings (POL-NEW-CLIENT-PAYMENT, POL-RECURRING-NGO-PAYMENT, POL-FREIGHT-RECONFIRM, POL-MODULE-GRANULARITY, POL-REVREC, POL-QUOTE-VALIDITY, POL-EXW-SCOPE, POL-INDICATIVE-EXW)
- Price tier matching logic
- Freight validity, risk level, and staleness rules
- Payment term derivation by customer segment
- Revenue recognition journal requirements
- Follow‑up task routing by state
Output Requirements
Always return only valid JSON matching the supplied answer_template.json. Do not include markdown fences, explanatory text, or commentary outside the JSON. Use USD with two decimals for all money fields. Use ISO YYYY-MM-DD for all dates. Use the exact enum values from the template. Map API field names to the template key names precisely.
1---2name: medbridge-sales-ops-243description: "Complete MedBridge Sales Ops API integration for humanitarian and medical supply quoting, pricing, freight comparison, account reconciliation, and engagement milestone tracking. Use when the task involves: (1) Building quote revision packages with EXW pricing, freight options, and policy-driven recommendations, (2) Processing indicative RFQ/quote requests with module-level line items and EXW-only scope, (3) Reconciling won opportunities against milestone invoices, payments, and revenue recognition journals, (4) Producing engagement reconciliations with accounting actions and event invitation tasks, (5) Any MedBridge Sales Ops data retrieval across customers, products, quotes, RFQs, freight-quotes, invoices, payments, revenue-journals, events, vouchers, or opportunities via the MedBridge REST API."4metadata:5 source: https://skillmd.com/skills/prism-shadow/medbridge-sales-ops-246---78# MedBridge Sales Ops910## Overview1112The MedBridge Sales Ops API surfaces shared CRM, quote, logistics, and milestone engagement data for humanitarian and medical supply workflows. Use it to build quote decision packages, indicative pricing responses, account reconciliations, and engagement follow-ups.1314## API Setup1516The API base URL is provided as `<TASK_ENV_BASE_URL>` by the task runner. All endpoints are read-only GET. Use `curl` for all API calls and `python3 -c "import json"` or `python3 -m json.tool` for JSON formatting.1718**Collection endpoints:**1920| Endpoint | Description |21|---|---|22| `GET /api` | List all collections |23| `GET /api/search?q=<text>` | Full-text search across all collections |24| `GET /api/customers` | All customer records |25| `GET /api/customers/<id>` | Single customer |26| `GET /api/products` | All product catalog entries |27| `GET /api/products/<code>` | Single product by code |28| `GET /api/quotes` | All quotes |29| `GET /api/quotes/<id>` | Single quote |30| `GET /api/rfqs` | All RFQs |31| `GET /api/rfqs/<id>` | Single RFQ |32| `GET /api/freight-quotes` | All freight quotes |33| `GET /api/freight-quotes/<id>` | Single freight quote |34| `GET /api/policies` | All business policies |35| `GET /api/opportunities` | All opportunities |36| `GET /api/opportunities/<id>` | Single opportunity |37| `GET /api/invoices` | All invoices |38| `GET /api/invoices/<id>` | Single invoice |39| `GET /api/payments` | All payments |40| `GET /api/payments/<id>` | Single payment |41| `GET /api/revenue-journals` | All revenue journals |42| `GET /api/revenue-journals/<id>` | Single revenue journal |43| `GET /api/events` | All events |44| `GET /api/events/<id>` | Single event |45| `GET /api/vouchers` | All vouchers |46| `GET /api/vouchers/<code>` | Single voucher by code |4748Always fetch related collections in parallel. For a quote revision, fetch the quote, customer, product, freight-quotes, and policies simultaneously. For an opportunity reconciliation, fetch the opportunity, its customer, invoices, payments, revenue-journals, events, and vouchers together.4950## Core Workflows5152### 1. Quote Revision with Freight5354Use when the user asks for a revised quote decision package with EXW pricing and freight comparisons.5556**Steps:**57581. Fetch the quote, customer, product, freight quotes, and policies in parallel.592. Identify the correct product price tier: match `confirmed_quantity` to the tier where `min_qty <= quantity <= max_qty` (null `max_qty` means unlimited). Use the tier's `unit_price_usd`, `lead_time_days`, and `shelf_life_months`.603. Compute `exw_total_usd = confirmed_quantity * unit_price_usd`.614. Filter freight quotes by `quote_id` matching the quote. Sort modes as AIR, SEA, ROAD. For each, compute `grand_total_usd = exw_total_usd + freight_cost_usd`.625. Assess freight validity: a freight quote is STALE when `valid_until` is before the `quote_date`. Route risk levels map to risk flags: `low`→`NONE`, `medium`→`MEDIUM_BORDER_RISK`, `high`→`HIGH_BORDER_RISK`.636. Determine the recommended mode: prefer SEA when it has low risk and is valid. Set `freight_reconfirmation_required: true` per policy POL-FREIGHT-RECONFIRM.647. Derive payment terms from the customer's `payment_profile` or the applicable policy (see [business_rules.md](references/business_rules.md)).658. Check `all_freight_options_valid_on_quote_date` — false if any freight option has `valid_until` before the quote date.669. Add a `freight_warning` when any freight option is stale or has high border risk.6768**Example output shape:** See [business_rules.md](references/business_rules.md) for field mapping and value derivation rules.6970### 2. Indicative RFQ / Module Quote7172Use when the user asks for an indicative EXW-only quote from an RFQ, especially for module-level products.7374**Steps:**75761. Fetch the RFQ, customer, and products in parallel. Also fetch policies.772. For each module in the RFQ's `requested_modules`, fetch the product by code for pricing, `article_number`, `lead_time_days`, and `shelf_life_months`.783. Quote at the module level only — do not split into components or sub-SKUs unless the prompt explicitly requests it. This follows policy POL-MODULE-GRANULARITY.794. Since the RFQ has no confirmed destination, exclude freight entirely. Set `quote_basis: "EXW_ONLY"` and `freight_excluded: true`.805. For new NGO customers (`segment: "new_ngo"`), use `PREPAY_100` payment terms. For other customer types, match their `payment_profile`.816. Set `offer_validity_days: 30` per POL-QUOTE-VALIDITY.827. Each line item: `line_total = quantity * unit_price`. Sum all line totals for `grand_total`.838. Products where `price_tiers` has only one entry use that tier directly; no quantity matching is needed since the RFQ specifies the quantity.8485### 3. Account Reconciliation8687Use when the user asks to reconcile a won opportunity against invoices, payments, and revenue recognition, plus event/voucher linkage.8889**Steps:**90911. Fetch the opportunity, its customer, invoices, payments, revenue-journals, events, and vouchers in parallel. Use the search endpoint or direct ID lookups.922. Map opportunity phases to invoices by `phase_id` or invoice ID reference. For each phase:93 - Determine `invoice_state`: `paid` / `unpaid`94 - Determine `payment_state`: from payment records linked by `invoice_id`95 - Look up revenue recognition: a revenue journal entry linked by `invoice_id` means RECOGNIZED96 - For paid milestones with no revenue journal, status is `MISSING_REVENUE_JOURNAL`97 - For unpaid milestones, status is `NOT_REQUIRED_UNPAID`983. Verify `opportunity_matches_milestones`: `won_amount` equals sum of all phase `amount_usd` values.994. Compute `outstanding_balance`: sum of unpaid amounts across phases.1005. Link the event by `customer_id` or `opportunity_id`. Retrieve the voucher by `voucher_code`.1016. Generate follow-up tasks:102 - **Collection task** for each unpaid milestone with a due date, linked to the opportunity and contact.103 - **Event invitation task** when the event is scheduled/confirmed, linked to the contact.104105See [business_rules.md](references/business_rules.md) for complete status enum values and task routing rules.106107### 4. Engagement Reconciliation with Accounting Actions108109Use when the user asks for finance-ready reconciliation with accounting journal entries and collection routing.110111**Steps:**1121131. Follow the same data gathering as workflow 3 (account reconciliation).1142. For each milestone, compute detailed states:115 - `invoice_state`: from invoice `status` field (paid/unpaid)116 - `payment_state`: from payments linked to the invoice117 - `recognition_status`: cross-reference revenue journals by `invoice_id`1183. Determine the primary accounting action:119 - If any paid milestone lacks a revenue journal → `RECORD_REVENUE_MS2` (target the specific milestone ID)120 - If all paid milestones have journals → `VERIFY_REVENUE_ONLY`121 - If no paid milestones → `NO_ACCOUNTING_ACTION`1224. Build the accounting action detail with the correct `debit_account` (`DEFERRED_REVENUE`), `credit_account` (`IMPLEMENTATION_SERVICES_REVENUE`), and `owner_queue` (`ACCOUNTING`).1235. Build the collection task: if unpaid milestone is not yet past due → `MONITOR_UNPAID_NOT_DUE` with `owner_queue: ACCOUNT_MANAGEMENT`. If past due → `SEND_COLLECTION_NOTICE` with `owner_queue: COLLECTIONS`.1246. Build the event invite task: `SEND_BRIEFING_INVITE` when the event is `scheduled` or equivalent, with `owner_queue: ACCOUNT_MANAGEMENT`.125126## Data Relationships127128See [api_reference.md](references/api_reference.md) for the complete field reference for each collection.129130**Key joins:**131- Quote → Customer (`customer_id`), Product (`line_items[].product_code`), Freight Quotes (`id` matches `quote_id`)132- RFQ → Customer (`customer_id`), Products (`requested_modules[].product_code`)133- Opportunity → Customer (`customer_id`), Invoices (via `phases[].invoice_id`), Payments (`invoice_id`), Revenue Journals (`invoice_id`), Events (`opportunity_id`), Vouchers (`opportunity_id`)134- Event → Voucher (`voucher_code`)135- Customer → Payment terms via `payment_profile` or segment‑to‑policy mapping136137## Business Rules138139See [business_rules.md](references/business_rules.md) for:140- Policy‑to‑action mappings (POL-NEW-CLIENT-PAYMENT, POL-RECURRING-NGO-PAYMENT, POL-FREIGHT-RECONFIRM, POL-MODULE-GRANULARITY, POL-REVREC, POL-QUOTE-VALIDITY, POL-EXW-SCOPE, POL-INDICATIVE-EXW)141- Price tier matching logic142- Freight validity, risk level, and staleness rules143- Payment term derivation by customer segment144- Revenue recognition journal requirements145- Follow‑up task routing by state146147## Output Requirements148149Always return only valid JSON matching the supplied `answer_template.json`. Do not include markdown fences, explanatory text, or commentary outside the JSON. Use USD with two decimals for all money fields. Use ISO `YYYY-MM-DD` for all dates. Use the exact enum values from the template. Map API field names to the template key names precisely.