Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/FerchoSG/healthcare-web/llms.txt

Use this file to discover all available pages before exploring further.

The billing API manages clinic invoices, payment tracking, and integration with Costa Rica’s Ministerio de Hacienda electronic billing system. Invoices can be created in draft state and updated as payments are received or as the Hacienda validation process progresses. All endpoints require a valid Authorization bearer token and x-clinic-id header.

​
GET /billing/invoices

Retrieve all invoices for the active clinic. Response — Invoice[]
​
id
string
UUID of the invoice.
​
clinic_id
string
UUID of the owning clinic.
​
patient_id
string
UUID of the billed patient.
​
appointment_id
string | null
UUID of the linked appointment, or null.
​
hacienda_consecutive
string | null
Hacienda-assigned consecutive document number, populated after submission.
​
numeric_key
string | null
Hacienda 50-digit numeric key (clave numérica), populated after acceptance.
​
total_amount
number
Total invoice amount in cents (CRC colones).
​
service_description
string | null
Free-text description of the service billed.
​
hacienda_status
string
Hacienda e-billing status. One of DRAFT, ACCEPTED, or REJECTED.
​
payment_status
string
Payment collection status. One of PAID, UNPAID, or PARTIAL.
​
payment_method
string | null
Payment method used. One of SINPE_MOVIL, TARJETA, EFECTIVO, or TRANSFERENCIA. null when payment has not been received.
​
payment_reference
string | null
Transaction reference number (e.g., SINPE confirmation code).
​
paid_amount
number | null
Amount actually paid, in cents. Used for partial payments.
​
paid_at
string | null
ISO 8601 timestamp of when payment was received.
​
notes
string | null
Internal notes about the invoice.
​
pdf_url
string | null
URL to the PDF version of the invoice.
​
xml_url
string | null
URL to the Hacienda-compliant XML document.
​
createdAt
string
ISO 8601 creation timestamp.
​
updatedAt
string
ISO 8601 last-updated timestamp.
​
patient
object
​
appointment
object | null
Linked appointment summary, or null.
curl --request GET \
  --url http://localhost:3001/billing/invoices \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>"

​
POST /billing/invoices

Create a new invoice. Newly created invoices start with hacienda_status: DRAFT until they are submitted to Hacienda. Request body
​
patient_id
string
required
UUID of the patient being billed.
​
total_amount
number
required
Total amount to bill, in cents (CRC colones). For example, 1500000 represents ₡15,000.00.
​
appointment_id
string
UUID of the appointment to associate with this invoice.
​
service_description
string
Human-readable description of the service rendered.
​
payment_status
string
default:"UNPAID"
Initial payment status. One of PAID, UNPAID, or PARTIAL.
​
payment_method
string
Payment method. One of SINPE_MOVIL, TARJETA, EFECTIVO, or TRANSFERENCIA.
​
payment_reference
string
Transaction reference number (e.g., SINPE confirmation code).
​
paid_amount
number
Amount already paid, in cents. Used for partial payments.
​
paid_at
string
ISO 8601 timestamp of when the payment was received.
​
notes
string
Internal notes for clinic staff.
Response — Invoice The newly created invoice object. See field definitions in GET /billing/invoices above. 
curl --request POST \
  --url http://localhost:3001/billing/invoices \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>" \
  --header "Content-Type: application/json" \
  --data '{
    "patient_id": "p_abc123",
    "appointment_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "total_amount": 2500000,
    "service_description": "Consulta médica general",
    "payment_status": "PAID",
    "payment_method": "SINPE_MOVIL",
    "payment_reference": "CR2026052012345",
    "paid_amount": 2500000,
    "paid_at": "2026-05-20T10:15:00Z"
  }'

​
PATCH /billing/invoices/:id

Update an existing invoice. Use this endpoint to record payments, correct amounts, or update Hacienda-related fields after processing. Path parameters
​
id
string
required
UUID of the invoice to update.
Request body
​
appointment_id
string
Link or re-link to a different appointment.
​
total_amount
number
Updated total amount in cents.
​
service_description
string
Updated service description.
​
payment_status
string
Updated payment status: PAID, UNPAID, or PARTIAL.
​
payment_method
string
Updated payment method: SINPE_MOVIL, TARJETA, EFECTIVO, or TRANSFERENCIA.
​
payment_reference
string
Updated transaction reference.
​
paid_amount
number
Updated paid amount in cents.
​
paid_at
string | null
ISO 8601 payment timestamp, or null to clear.
​
notes
string
Updated internal notes.
Response — Invoice The updated invoice object. 
curl --request PATCH \
  --url http://localhost:3001/billing/invoices/inv_abc789 \
  --header "Authorization: Bearer <token>" \
  --header "x-clinic-id: <clinic_id>" \
  --header "Content-Type: application/json" \
  --data '{
    "payment_status": "PAID",
    "payment_method": "TRANSFERENCIA",
    "paid_amount": 2500000,
    "paid_at": "2026-05-20T11:00:00Z"
  }'

​
Hacienda integration

CitaBox integrates with Costa Rica’s Ministerio de Hacienda electronic billing (comprobantes electrónicos). Invoices start as DRAFT and are submitted to Hacienda asynchronously. The hacienda_status field reflects the result of that submission.
  • DRAFT — invoice has not yet been submitted to Hacienda.
  • ACCEPTED — Hacienda accepted the document. The hacienda_consecutive and numeric_key fields are populated.
  • REJECTED — Hacienda rejected the document. Check notes for the rejection reason.
The pdf_url and xml_url fields are populated by the Hacienda submission process and should not be set manually.

Build docs developers (and LLMs) love

Get started for freeTalk to us