Health services · Compense Docs

This page is generated from the contract (data/gateway-v1.json): each operation shows its verb, path, parameters, body, responses, whether it carries an Idempotency-Key, and the equivalent method in all five SDKs. For the end-to-end flow with complete examples, see the implementation guide.

Operations in tag `health` #

Contract description: Health services for IPS / health-enabled entities: appointment catalog, availability, booking on behalf of a patient (identified by document), cancel / reschedule / attendance, health invoices (DIAN / radication status, XML, RIPS, glosas) with payer collections, and the patient’s vaccination card. Clinical records go through the separate FHIR B2B channel.

Method	Path	Operation	Scope	Idem.
GET	`/v1/gateway/health-services/appointments/`	Appointments of a patient	`appointments:read`	—
POST	`/v1/gateway/health-services/appointments/`	Book an appointment for a patient	`appointments:write`	recommended
GET	`/v1/gateway/health-services/appointments/{appointment_id}/`	Appointment detail	`appointments:read`	—
POST	`/v1/gateway/health-services/appointments/{appointment_id}/cancel/`	Cancel an appointment (releases the slot)	`appointments:write`	recommended
POST	`/v1/gateway/health-services/appointments/{appointment_id}/reschedule/`	Reschedule to another slot	`appointments:write`	recommended
POST	`/v1/gateway/health-services/appointments/{appointment_id}/status/`	Record attendance (completed / no_show)	`appointments:write`	recommended
GET	`/v1/gateway/health-services/availability/`	Free appointment slots	`appointments:read`	—
GET	`/v1/gateway/health-services/billing/glosas/`	Glosas (read only)	`health_billing:read`	—
GET	`/v1/gateway/health-services/billing/invoices/`	Health invoices with DIAN / radication status	`health_billing:read`	—
GET	`/v1/gateway/health-services/billing/invoices/{invoice_id}/`	Invoice detail (lines, payments, glosas, radications)	`health_billing:read`	—
POST	`/v1/gateway/health-services/billing/invoices/{invoice_id}/payments/`	Register a payer (EPS) payment on an invoice	`health_billing:collect`	recommended
GET	`/v1/gateway/health-services/billing/invoices/{invoice_id}/rips/`	RIPS JSON of the invoice	`health_billing:read`	—
GET	`/v1/gateway/health-services/billing/invoices/{invoice_id}/xml/`	Electronic invoice XML (wrapped in JSON)	`health_billing:read`	—
GET	`/v1/gateway/health-services/catalog/`	Booking catalog (specialties, services, sites, doctors)	`appointments:read`	—
GET	`/v1/gateway/health-services/vaccination/card/`	Patient vaccination card / schedule	`vaccination:read`	—

Appointments of a patient #

GET/v1/gateway/health-services/appointments/

operationId listHealthAppointments
Authentication X-API-Key · scope appointments:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`document` required	query	string	Patient document (holder or family beneficiary). E.g.: `1032456789`
`status`	query	string	Comma-separated statuses.
`when`	query	string	upcoming \| past \| all.
`page`	query	integer	Page (from 1).
`page_size`	query	integer	Items per page (max 100).

Responses

Code	Description	Body
200	Paginated appointments.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.appointments.list()

client.health.appointments.list()

$client->health->appointments->list()

await client.Health.Appointments.ListAsync()

client.Health.Appointments.List(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/appointments/?document=1032456789" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Book an appointment for a patient #

POST/v1/gateway/health-services/appointments/

operationId bookHealthAppointment
Authentication X-API-Key · scope appointments:write
Idempotency-Key recommended (the SDK generates it)

Books slot_id for the patient identified by document. Unknown patient: send new_patient to quick-register them. Emits appointment.booked.

Parameters

Name	In	Type	Description
`Idempotency-Key`	header	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

Field	Type	Description
`appointment_type`	string	Values: `first_time`, `follow_up`, `control`, `emergency`.
`channel`	string	Values: `recepcion`, `telefono`.
`consultation_type`	string	Values: `presencial`, `telemedicina`.
`document` required	string	E.g.: `"1032456789"`
`new_patient`	object
`notes`	string
`reason`	string
`slot_id` required	string

Responses

Code	Description	Body
200	Processed; the engine result is in `data`.	`TransactionEnvelope` application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.appointments.book()

client.health.appointments.book()

$client->health->appointments->book()

await client.Health.Appointments.BookAsync()

client.Health.Appointments.Book(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/appointments/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "document": "1032456789",
    "slot_id": "<slot_id>"
  }'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Appointment detail #

GET/v1/gateway/health-services/appointments/{appointment_id}/

operationId getHealthAppointment
Authentication X-API-Key · scope appointments:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`appointment_id` required	path	string	Appointment id (UUID) or appointment code. E.g.: `CITA-2026-000123`

Responses

Code	Description	Body
200	Appointment.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.appointments.get()

client.health.appointments.get()

$client->health->appointments->get()

await client.Health.Appointments.GetAsync()

client.Health.Appointments.Get(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/appointments/CITA-2026-000123/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Cancel an appointment (releases the slot) #

POST/v1/gateway/health-services/appointments/{appointment_id}/cancel/

operationId cancelHealthAppointment
Authentication X-API-Key · scope appointments:write
Idempotency-Key recommended (the SDK generates it)

IPS-level cancel. on_behalf_of_patient: true applies the patient rules (2-hour notice). Emits appointment.cancelled.

Parameters

Name	In	Type	Description
`appointment_id` required	path	string	Appointment id (UUID) or appointment code. E.g.: `CITA-2026-000123`
`Idempotency-Key`	header	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

Field	Type	Description
`on_behalf_of_patient`	boolean
`reason` required	string

Responses

Code	Description	Body
200	Processed; the engine result is in `data`.	`TransactionEnvelope` application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.appointments.cancel()

client.health.appointments.cancel()

$client->health->appointments->cancel()

await client.Health.Appointments.CancelAsync()

client.Health.Appointments.Cancel(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/appointments/CITA-2026-000123/cancel/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "<reason>"
  }'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Reschedule to another slot #

POST/v1/gateway/health-services/appointments/{appointment_id}/reschedule/

operationId rescheduleHealthAppointment
Authentication X-API-Key · scope appointments:write
Idempotency-Key recommended (the SDK generates it)

Same rules as the app (2-hour notice, locked slot, never in the past). Emits appointment.rescheduled.

Parameters

Name	In	Type	Description
`appointment_id` required	path	string	Appointment id (UUID) or appointment code. E.g.: `CITA-2026-000123`
`Idempotency-Key`	header	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

Field	Type	Description
`new_slot_id` required	string

Responses

Code	Description	Body
200	Processed; the engine result is in `data`.	`TransactionEnvelope` application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.appointments.reschedule()

client.health.appointments.reschedule()

$client->health->appointments->reschedule()

await client.Health.Appointments.RescheduleAsync()

client.Health.Appointments.Reschedule(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/appointments/CITA-2026-000123/reschedule/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "new_slot_id": "<new_slot_id>"
  }'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Record attendance (completed / no_show) #

POST/v1/gateway/health-services/appointments/{appointment_id}/status/

operationId setHealthAppointmentAttendance
Authentication X-API-Key · scope appointments:write
Idempotency-Key recommended (the SDK generates it)

Only from confirmed/pending and from the appointment time on. Emits appointment.status_changed.

Parameters

Name	In	Type	Description
`appointment_id` required	path	string	Appointment id (UUID) or appointment code. E.g.: `CITA-2026-000123`
`Idempotency-Key`	header	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

Field	Type	Description
`reason`	string
`status` required	string	Values: `completed`, `no_show`.

Responses

Code	Description	Body
200	Processed; the engine result is in `data`.	`TransactionEnvelope` application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.appointments.set_attendance()

client.health.appointments.setAttendance()

$client->health->appointments->setAttendance()

await client.Health.Appointments.SetAttendanceAsync()

client.Health.Appointments.SetAttendance(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/appointments/CITA-2026-000123/status/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "completed"
  }'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Free appointment slots #

GET/v1/gateway/health-services/availability/

operationId listHealthAvailability
Authentication X-API-Key · scope appointments:read
Idempotency-Key not applicable

Use date for one day, or start_date/end_date/asap for a range (no dates: next 30 days).

Parameters

Name	In	Type	Description
`date`	query	string (date)	One day (YYYY-MM-DD).
`start_date`	query	string (date)	From (YYYY-MM-DD).
`end_date`	query	string (date)	To (YYYY-MM-DD).
`asap`	query	boolean	Earliest slots in the next 90 days.
`doctor_id`	query	string	Doctor id.
`location_id`	query	string	Site id.
`specialty_id`	query	string	Specialty id.
`service_id`	query	string	Service type id.
`page`	query	integer	Page (from 1).
`page_size`	query	integer	Items per page (max 100).

Responses

Code	Description	Body
200	Paginated slots.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.availability()

client.health.availability()

$client->health->availability()

await client.Health.AvailabilityAsync()

client.Health.Availability(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/availability/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Glosas (read only) #

GET/v1/gateway/health-services/billing/glosas/

operationId listHealthGlosas
Authentication X-API-Key · scope health_billing:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`invoice`	query	string	Invoice id.
`status`	query	string	Comma-separated statuses.
`page`	query	integer	Page (from 1).
`page_size`	query	integer	Items per page (max 100).

Responses

Code	Description	Body
200	Paginated glosas.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.billing.list_glosas()

client.health.billing.listGlosas()

$client->health->billing->listGlosas()

await client.Health.Billing.ListGlosasAsync()

client.Health.Billing.ListGlosas(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/billing/glosas/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Health invoices with DIAN / radication status #

GET/v1/gateway/health-services/billing/invoices/

operationId listHealthInvoices
Authentication X-API-Key · scope health_billing:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`status`	query	string	Comma-separated statuses (e.g. CUV_OK,RADICADA).
`payer`	query	string	Payer id.
`q`	query	string	Number, reference or CUV.
`document`	query	string	Patient document.
`date_from`	query	string (date)	Created from (YYYY-MM-DD).
`date_to`	query	string (date)	Created to (YYYY-MM-DD).
`page`	query	integer	Page (from 1).
`page_size`	query	integer	Items per page (max 100).

Responses

Code	Description	Body
200	Paginated invoices.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.billing.list_invoices()

client.health.billing.listInvoices()

$client->health->billing->listInvoices()

await client.Health.Billing.ListInvoicesAsync()

client.Health.Billing.ListInvoices(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/billing/invoices/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Invoice detail (lines, payments, glosas, radications) #

GET/v1/gateway/health-services/billing/invoices/{invoice_id}/

operationId getHealthInvoice
Authentication X-API-Key · scope health_billing:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`invoice_id` required	path	string	Health invoice id. E.g.: `3f2b8c1e-0000-4a1b-9c2d-000000000001`

Responses

Code	Description	Body
200	Invoice.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.billing.get_invoice()

client.health.billing.getInvoice()

$client->health->billing->getInvoice()

await client.Health.Billing.GetInvoiceAsync()

client.Health.Billing.GetInvoice(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/billing/invoices/3f2b8c1e-0000-4a1b-9c2d-000000000001/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Register a payer (EPS) payment on an invoice #

POST/v1/gateway/health-services/billing/invoices/{invoice_id}/payments/

operationId registerHealthInvoicePayment
Authentication X-API-Key · scope health_billing:collect
Idempotency-Key recommended (the SDK generates it)

Idempotent by Idempotency-Key (or by method + reference). Never above the non-disputed balance. Emits health_billing.payment.registered.

Parameters

Name	In	Type	Description
`invoice_id` required	path	string	Health invoice id. E.g.: `3f2b8c1e-0000-4a1b-9c2d-000000000001`
`Idempotency-Key`	header	string	Client-generated key that makes a write safely retryable. Replaying the same key returns the original result with `idempotent_replay: true`; a replay while the original is still in flight returns 409. E.g.: `horizonte-2026-06-26-credit-000123`

Request body

Content type: application/json · required

Field	Type	Description
`amount` required	string	E.g.: `"53500.00"`
`method` required	string	Values: `TRANSFERENCIA`, `CONSIGNACION`, `GIRO_DIRECTO`, `RETENCION`.
`paid_at`	string (date)
`reference` required	string

Responses

Code	Description	Body
200	Processed; the engine result is in `data`.	`TransactionEnvelope` application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.billing.register_payment()

client.health.billing.registerPayment()

$client->health->billing->registerPayment()

await client.Health.Billing.RegisterPaymentAsync()

client.Health.Billing.RegisterPayment(ctx, …)

curl -X POST "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/billing/invoices/3f2b8c1e-0000-4a1b-9c2d-000000000001/payments/" \
  -H "X-API-Key: $COMPENSE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "53500.00",
    "method": "TRANSFERENCIA",
    "reference": "<reference>"
  }'

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

RIPS JSON of the invoice #

GET/v1/gateway/health-services/billing/invoices/{invoice_id}/rips/

operationId getHealthInvoiceRips
Authentication X-API-Key · scope health_billing:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`invoice_id` required	path	string	Health invoice id. E.g.: `3f2b8c1e-0000-4a1b-9c2d-000000000001`

Responses

Code	Description	Body
200	RIPS.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.billing.get_invoice_rips()

client.health.billing.getInvoiceRips()

$client->health->billing->getInvoiceRips()

await client.Health.Billing.GetInvoiceRipsAsync()

client.Health.Billing.GetInvoiceRIPS(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/billing/invoices/3f2b8c1e-0000-4a1b-9c2d-000000000001/rips/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Electronic invoice XML (wrapped in JSON) #

GET/v1/gateway/health-services/billing/invoices/{invoice_id}/xml/

operationId getHealthInvoiceXml
Authentication X-API-Key · scope health_billing:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`invoice_id` required	path	string	Health invoice id. E.g.: `3f2b8c1e-0000-4a1b-9c2d-000000000001`

Responses

Code	Description	Body
200	XML document.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.billing.get_invoice_xml()

client.health.billing.getInvoiceXml()

$client->health->billing->getInvoiceXml()

await client.Health.Billing.GetInvoiceXmlAsync()

client.Health.Billing.GetInvoiceXML(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/billing/invoices/3f2b8c1e-0000-4a1b-9c2d-000000000001/xml/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Booking catalog (specialties, services, sites, doctors) #

GET/v1/gateway/health-services/catalog/

operationId getHealthCatalog
Authentication X-API-Key · scope appointments:read
Idempotency-Key not applicable

Responses

Code	Description	Body
200	Catalog.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.catalog()

client.health.catalog()

$client->health->catalog()

await client.Health.CatalogAsync()

client.Health.Catalog(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/catalog/" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Patient vaccination card / schedule #

GET/v1/gateway/health-services/vaccination/card/

operationId getVaccinationCard
Authentication X-API-Key · scope vaccination:read
Idempotency-Key not applicable

Parameters

Name	In	Type	Description
`document` required	query	string	Patient document. E.g.: `1032456789`

Responses

Code	Description	Body
200	Vaccination card.	object application/json

Possible errors (400, 401, 403, 404, 409, 422, 429, 500, 502, 504) — application/problem+json

400	Malformed request.	`about:blank`
401	Missing or invalid API key.	`about:blank`
403	The key is valid but lacks the required scope, or the source IP is not allow-listed.	`about:blank`
404	The requested resource does not exist.	`about:blank`
409	Idempotency conflict — same key, original still processing.	`https://errors.compense.co/gateway/idempotency-conflict`
422	Request body failed validation.	`https://errors.compense.co/gateway/validation`
429	Per-key rate limit or monthly quota exceeded; see `Retry-After`.	`https://errors.compense.co/gateway/rate-limited`
500	Unexpected gateway error; quote the `trace_id` to support.	`about:blank`
502	The processing engine returned an error.	`https://errors.compense.co/gateway/upstream-error`
504	The processing engine did not respond in time.	`https://errors.compense.co/gateway/upstream-error`

See problem+json errors for the equivalent exception in each SDK.

Example

SDK method and HTTP request

client.health.vaccination.card()

client.health.vaccination.card()

$client->health->vaccination->card()

await client.Health.Vaccination.CardAsync()

client.Health.Vaccination.Card(ctx, …)

curl "https://sandbox.dev.compense.co/gw/v1/gateway/health-services/vaccination/card/?document=1032456789" \
  -H "X-API-Key: $COMPENSE_API_KEY"

Each SDK's methods come from its contract parity suite. The cURL runs against the sandbox; <field> values are placeholders.

Operations in tag health #

Appointments of a patient #

Parameters

Responses

Example

Book an appointment for a patient #

Parameters

Request body

Responses

Example

Appointment detail #

Parameters

Responses

Example

Cancel an appointment (releases the slot) #

Parameters

Request body

Responses

Example

Reschedule to another slot #

Parameters

Request body

Responses

Example

Record attendance (completed / no_show) #

Parameters

Request body

Responses

Example

Free appointment slots #

Parameters

Responses

Example

Glosas (read only) #

Parameters

Responses

Example

Health invoices with DIAN / radication status #

Parameters

Responses

Example

Invoice detail (lines, payments, glosas, radications) #

Parameters

Responses

Example

Register a payer (EPS) payment on an invoice #

Parameters

Request body

Responses

Example

RIPS JSON of the invoice #

Parameters

Responses

Example

Electronic invoice XML (wrapped in JSON) #

Parameters

Responses

Example

Booking catalog (specialties, services, sites, doctors) #

Responses

Example

Patient vaccination card / schedule #

Parameters

Responses

Example

Operations in tag `health` #