Charges

A charge in RCM is one billable line item attached to an event. Each charge represents something the provider did or used during the encounter: a consultation, a surgery, a diagnostic exam, a consumable material, a fee for an executor service (anaesthetist, surgical assistant, etc.).

You don't manage the event explicitly — you send charges, and RCM derives the event (and the account that wraps it) from the origin_event_id you include in each charge request. Charges are the primary thing you POST to RCM.

Shape of a charge

The full schema lives in POST /v1/charges. The mandatory fields:

Field	Description
code	Your system's identifier for the charge. Must be unique within the event.
origin_event_id	Identifier of the parent event from your HIS/PMS. This is what binds the charge to its event — and indirectly to its account.
agreement_code	The provider-payer agreement under which this charge is billed.
provider_product_code	Catalogue code identifying what was done (in Brazil, often a TUSS code).
quantity, amount, total_amount	Numeric values. total_amount is typically quantity × amount, but pass it explicitly because some agreements compute it differently.
currency	ISO 4217 (e.g. BRL, COP, USD).
creation_date_time	ISO 8601 timestamp of when the service was rendered.
description	Human-readable description of the service.
patient_id, patient_name	Patient info as recorded at service time.

Optional but commonly used:

Field	Description
parent_event_id	When this charge belongs to a secondary event (related to a base event), set this to the base event's origin_event_id. RCM groups them under one account.
service_type_code	Defaults derived from provider_product_code; pass explicitly to override (CONSULTATION, HOSPITALIZATION, etc.).
charge_executor_service_code	Required for charges that need a named executor (anaesthetist, surgeon).
healthcare_plan_coverage_code	When the agreement requires a specific plan-coverage code.
diagnostic_test_number, diagnosis_code, diagnosis_name	Clinical context — required for some agreements, optional for others.
authorization_id	Pre-authorisation number issued by the payer for procedures that need approval.

Lifecycle

The rule of thumb: you can modify or delete a charge while it's OPEN, you cannot once it's been assigned to an invoice.

What happens when you POST a charge

Behind one POST RCM performs up to three creations transparently:

1. Event — created from the charge's origin_event_id, patient info, and agreement, if no event with that origin_event_id exists yet for the authenticated provider.
2. Account — created if no account groups this event yet for (provider, payer, agreement).
3. Charge — always created and linked to the event.

Steps 1 and 2 are idempotent on origin_event_id — re-sending more charges for the same encounter just attaches them; it does not duplicate the event or account.

Operations

Endpoint	What it does
POST /v1/charges	Create a new charge — implicitly creates Event + Account if needed.
PUT /v1/charges/{chargeCode}	Modify an existing charge (only while not invoiced). The path parameter is the code you set on creation.
DELETE /v1/charges/{chargeCode}	Delete a charge (only while not invoiced).

Support files attach to events (or to charges)

A charge alone isn't enough to get paid — the payer needs supporting documentation. You upload support files linked to either:

• The event (the document supports the whole encounter — e.g. a TISS guide covering the admission)
• A specific charge (the document is charge-specific — e.g. an OPME request for one set of materials)

Pass the charge_code on the upload to attach at charge level; omit it to attach at event/account level.

Invoicing

Once you have all required support files validated for an account's charges, group them into an invoice:

curl -X POST https://sandbox.osigu.com/rcm/v1/invoices/assign-charges \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-2026-0042",
    "agreement_code": "DEFAULT",
    "charge_codes": ["CHG-001", "CHG-002", "CHG-003"]
  }'

Processing is asynchronous — the response is 202 with a Location header pointing to a status endpoint. Poll GET /v1/invoices/assign-charges/status/{id} until it completes. The endpoint reports per-charge errors so you can correct any failures.

Reassigning support files between invoices

If an invoice needs to be reissued (e.g. the payer requested a re-billing), use POST /v1/invoices/reassign-support-files to migrate the supporting documents from the old invoice to the new one without re-uploading. This is faster than recreating everything and preserves the audit trail. When it responds 202, poll GET /v1/invoices/reassign-support-files/status/{monitorId} until the migration finishes.

Handing invoices to the payer

Invoices are not the end of the cycle. To deliver them, group them into a pre-settlement — see Pre-settlements.