Pricing Queries

DELPHOS resolves procedure prices through a multi-level resolution chain that respects temporal pricing — every price query is resolved against the contract period active on the event date, not the current date.

Price Resolution Chain

DELPHOS resolves prices in strict priority order. The first match wins:

1. Manual Override   — procedure-specific price set on the contract period
2. CBHPM             — CBHPM table price x contract percentage
3. Type Rule         — price rule by appointment type
4. Base Price        — fallback base price

Source	Description
`manual_override`	Procedure-specific price explicitly set for this contract period
`cbhpm`	Calculated from the CBHPM reference table using the contract’s table version and percentage
`type_rule`	Price defined per appointment type on the contract period
`base_price`	Default fallback price

The pricing_source field in every response tells you which level produced the price.

Calculate Binding Price

Returns the binding price for a scheduling event. Use this when creating appointments or generating billing guides.

POST /v1/scheduling/pricing/calculate

Request body

Field	Type	Required	Default	Description
`convenio_id`	UUID	Yes	—	Convenio (insurance plan) UUID
`appointment_type_id`	UUID	Yes	—	Appointment type UUID
`procedure_codes`	array	No	`[]`	List of TUSS procedure codes to price
`event_date`	date	No	today	Date of the medical event for temporal resolution
`provider_id`	UUID	No	`null`	Provider UUID (reserved for future provider-specific pricing)

Response

Field	Type	Description
`total_price_cents`	integer	Total price in centavos
`pricing_source`	string	Dominant resolution source
`procedure_breakdown`	array	Per-procedure price details
`copay_cents`	integer	Patient copay amount in centavos
`insurance_cents`	integer	Insurance payment in centavos
`event_date`	date	Event date used for resolution
`contract_period_id`	UUID	Contract period used

Each item in procedure_breakdown:

Field	Type	Description
`procedure_code`	string	TUSS procedure code
`price_cents`	integer	Resolved price in centavos
`pricing_source`	string	Which resolution level produced this price
`cbhpm_details`	object	CBHPM calculation details (when source is `cbhpm`)
`copay_percent`	decimal	Copay percentage for this procedure
`copay_max_cents`	integer	Maximum copay cap in centavos

Status codes

Code	Meaning
`200`	Price calculated successfully
`422`	No price resolvable for the procedure or pricing error
`500`	Internal server error

curl
Python

curl -X POST "https://your-instance.delphos.app/v1/scheduling/pricing/calculate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "convenio_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "appointment_type_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "procedure_codes": ["10101012", "10101039"],
    "event_date": "2026-03-15"
  }'

import httpx

response = httpx.post(
    "https://your-instance.delphos.app/v1/scheduling/pricing/calculate",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "convenio_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "appointment_type_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "procedure_codes": ["10101012", "10101039"],
        "event_date": "2026-03-15",
    },
)

result = response.json()
print(f"Total: R$ {result['total_price_cents'] / 100:.2f}")
print(f"Copay: R$ {result['copay_cents'] / 100:.2f}")
print(f"Insurance pays: R$ {result['insurance_cents'] / 100:.2f}")
print(f"Source: {result['pricing_source']}")
print(f"Contract period: {result['contract_period_id']}")

for proc in result["procedure_breakdown"]:
    print(f"  {proc['procedure_code']}: R$ {proc['price_cents'] / 100:.2f} ({proc['pricing_source']})")

Example response

{
  "total_price_cents": 25000,
  "pricing_source": "manual_override",
  "procedure_breakdown": [
    {
      "procedure_code": "10101012",
      "price_cents": 15000,
      "pricing_source": "manual_override",
      "cbhpm_details": null,
      "copay_percent": 30,
      "copay_max_cents": 5000
    },
    {
      "procedure_code": "10101039",
      "price_cents": 10000,
      "pricing_source": "cbhpm",
      "cbhpm_details": {
        "table_version": "2024",
        "base_value_cents": 14285,
        "percentage": 70
      },
      "copay_percent": 30,
      "copay_max_cents": null
    }
  ],
  "copay_cents": 7500,
  "insurance_cents": 17500,
  "event_date": "2026-03-15",
  "contract_period_id": "c3d4e5f6-a7b8-9012-cdef-234567890abc"
}

Calculate Non-Binding Estimate

Returns a non-binding estimate for informational purposes (e.g. patient cost preview before booking). Uses today’s date for contract period resolution.

POST /v1/scheduling/pricing/estimate

Request body

Field	Type	Required	Default	Description
`convenio_id`	UUID	Yes	—	Convenio UUID
`appointment_type_id`	UUID	Yes	—	Appointment type UUID
`procedure_codes`	array	No	`[]`	TUSS procedure codes

Response

Field	Type	Description
`non_binding`	boolean	Always `true`
`total_price_cents`	integer	Estimated total in centavos
`pricing_source`	string	Dominant resolution source
`procedure_breakdown`	array	Per-procedure details (same schema as calculate)
`copay_cents`	integer	Estimated patient copay
`insurance_cents`	integer	Estimated insurance payment

curl
Python

curl -X POST "https://your-instance.delphos.app/v1/scheduling/pricing/estimate" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "convenio_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "appointment_type_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "procedure_codes": ["10101012"]
  }'

import httpx

response = httpx.post(
    "https://your-instance.delphos.app/v1/scheduling/pricing/estimate",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "convenio_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "appointment_type_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "procedure_codes": ["10101012"],
    },
)

estimate = response.json()
print(f"Estimated total: R$ {estimate['total_price_cents'] / 100:.2f}")
print(f"Non-binding: {estimate['non_binding']}")

Monetary Values

All monetary values are expressed in centavos (integer cents) to avoid floating-point precision issues in healthcare billing.

API value	Meaning
`15000`	R$ 150.00
`7500`	R$ 75.00
`250`	R$ 2.50

To display in Reais: value / 100 with two decimal places.

Copay Calculation

When a convenio has copay (coparticipacao) enabled, the pricing engine calculates the patient’s share automatically:

copay_cents = min(total_price_cents * copay_percent / 100, copay_max_cents)
insurance_cents = total_price_cents - copay_cents

copay_percent comes from the contract period or provider-convenio link.
copay_max_cents caps the patient’s maximum out-of-pocket amount.
If no cap is set (copay_max_cents is null), the percentage applies without limit.

Temporal Pricing Walkthrough

Consider a convenio with two contract periods:

Period	Validity	CBHPM Version	Percentage
A	Jan 1 - Jun 30	2023	70%
B	Jul 1 - Dec 31	2024	75%

Scenario: A procedure performed on March 15 (within Period A) is billed in August (Period B is now active).

# Correct: event_date ensures Period A prices are used
response = httpx.post(
    "https://your-instance.delphos.app/v1/scheduling/pricing/calculate",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "convenio_id": convenio_id,
        "appointment_type_id": type_id,
        "procedure_codes": ["10101012"],
        "event_date": "2026-03-15",  # Uses Period A (CBHPM 2023, 70%)
    },
)
# result['contract_period_id'] will be Period A's UUID

Without event_date, the engine would use today’s date and resolve to Period B, producing incorrect prices for the March event.

Contract Period Snapshots

For billing audit trails, retrieve a full snapshot of the pricing configuration that was active on a specific date:

GET /v1/scheduling/convenios/{convenio_id}/contracts/{period_id}/snapshot

The snapshot includes all overrides, particular prices, and type rules, providing a complete record of the pricing state at that point in time. See Contract Management for details.

Error Handling

Code	Meaning
`200`	Price calculated successfully
`422`	No price resolvable — no matching contract period, no override, no CBHPM entry
`500`	Internal server error

Error response format:

{
  "detail": "No price resolvable for procedure 10101012 in contract period c3d4e5f6-..."
}

Common causes of 422 errors:

No active contract period for the given convenio on the event date
Procedure code not found in any resolution level
Convenio has no CBHPM table version configured