Skip to main content

HIS inbound

HIS inbound is how scheduled appointments enter OSIGU automatically. Your Hospital Information System (HIS) pushes each appointment as it's created; this is the first inbound endpoint of the ecosystem (push HIS → OSIGU).

POST   /v1/checkin/appointments/his-inbound
PUT    /v1/checkin/appointments/his-inbound/{external_appointment_id}
DELETE /v1/checkin/appointments/his-inbound/{external_appointment_id}
Dedicated credentials

All three HIS integration operations (create, update, delete) are gated by a single permission, granted separately from the manual reception-desk operations. Ask OSIGU for dedicated credentials for your HIS integration rather than reusing the reception desk's — it keeps the two access paths independent and auditable.

Identity and idempotency​

An appointment is identified by the pair (provider, external_appointment_id) — the provider comes from your token, and external_appointment_id is your HIS's own identifier for the appointment. This makes the endpoint idempotent and safe to retry: sending the same appointment twice never creates a duplicate.

The pair is unique only among live appointments

Deduplication looks only at appointments that are still enabled. Once an appointment has been deleted (DELETE /his-inbound/{external_appointment_id}, a soft-delete), a later POST with the same external_appointment_id no longer finds it and creates a brand-new appointment instead of resurrecting the old one. So (provider, external_appointment_id) is not a permanent key — plan for delete-then-resend producing a new record, with a new id.

What happens on a re-send is a charge merge, not an overwrite:

The rules on a re-send are strict and worth memorising:

  • The appointment header is never modified — beneficiary, payer, doctor, appointment date, notes, agreement, service. Whatever was captured on first creation stays.
  • Only charges whose provider_product_code is not already present are merged in, under a row lock (concurrent re-sends are safe).

Response codes​

CodeMeaning
201 CreatedA new pre-appointment was created, or an existing one received at least one new charge.
200 OKNo-op: the appointment already existed and none of the request's charges were new (all already present, or charges empty/absent).
422 Unprocessable EntityRequest validation failed — returns field paths and messages.
404 Not FoundThe provider or payer could not be resolved in the RCM platform.
502 Bad GatewayThe RCM API is unavailable or timed out.
Treat 200 and 201 the same

Both 200 and 201 return the current pre-appointment in the body. For an idempotent push you usually don't need to branch on the code — just persist the returned appointment. The distinction is there if you want to log "created something new" vs "already up to date".

Request shape​

The payload carries the appointment header and the charges. Payer is resolved from payer_tax_identification_number; the beneficiary, doctor, specialty, agreement and service are captured as sent.

{
  "external_appointment_id": "HIS20260706001234",
  "appointment_date": "2026-07-15T14:30:00-05:00",
  "payer_tax_identification_number": "800123456",
  "beneficiary_card_number": "0123456789",
  "beneficiary_name": "Juan Carlos Perez Gomez",
  "beneficiary_document_type": "CC",
  "beneficiary_document_number": "1234567890",
  "doctor_name": "Dr. Maria Sanchez",
  "doctor_code": "DOC12345",
  "specialty_name": "Cardiology",
  "agreement_code": "AGR2024001",
  "service_code": "S1",
  "charges": [
    { "provider_product_code": "PROC001", "provider_product_name": "Electrocardiogram (ECG)", "quantity": 1 }
  ]
}

See the API Reference for the complete field list, constraints, and a live playground. For a step-by-step integration walk-through, see Integrate HIS inbound.

Managing an existing appointment​

Beyond creating and merging, the HIS can update and delete an appointment it created. Both operations address the appointment by its external_appointment_id in the path, are restricted to appointments with source HIS_INBOUND, and require the same HIS integration permission as POST.

Update — PUT /his-inbound/{external_appointment_id}​

Unlike a POST re-send (which never touches the header and only adds charges), PUT updates the header and reconciles the charges:

  • Header — beneficiary, payer, doctor, specialty, agreement, service, notes and appointment date are updated to the request's values.
  • Charges are reconciled against the request's charges list:
    • not yet present → added;
    • present in both → updated in place (quantity / provider_product_name);
    • no longer present → soft-deleted, along with their documents.

Only appointments in a non-terminal status (PENDING / CONFIRMED) can be updated.

CodeMeaning
200 OKHeader updated and charges reconciled; returns the current pre-appointment.
400 Bad RequestThe appointment exists but was not created by the HIS integration (source ≠ HIS_INBOUND).
404 Not FoundNo appointment for that external_appointment_id + provider, or provider/payer not resolvable in RCM.
409 ConflictThe appointment is in a terminal status (COMPLETED / CANCELLED) and can't be updated.
422 Unprocessable EntityRequest validation failed.
403 ForbiddenYour credentials aren't enabled for HIS integration.

Delete — DELETE /his-inbound/{external_appointment_id}​

Soft-deletes the appointment along with its charges and documents (the S3 objects are left intact). Only HIS_INBOUND appointments can be deleted.

CodeMeaning
204 No ContentSoft-deleted — or the appointment was already CANCELLED (idempotent no-op).
400 Bad RequestThe appointment was not created by the HIS integration (source ≠ HIS_INBOUND).
404 Not FoundNo appointment for that external_appointment_id + provider.
409 ConflictThe appointment is COMPLETED and can't be deleted.
403 ForbiddenYour credentials aren't enabled for HIS integration.

DELETE is idempotent — deleting an already-cancelled appointment still returns 204.

Common pitfalls​

  • Reusing external_appointment_id across appointments. It's the dedup key. Two genuinely different visits must have different identifiers, or the second will be treated as a re-send of the first.
  • Expecting a re-send to update the header. A POST re-send won't — it only adds charges. If the beneficiary or date genuinely changed, use PUT, which updates the header and reconciles charges.