Skip to main content

Integrate HIS inbound

This guide walks through wiring your Hospital Information System to push appointments into OSIGU as they're scheduled. See HIS inbound for the concept.

Prerequisites​

  • OSIGU credentials enabled for HIS integration — one permission covers all three operations (create, update and delete). Ask for credentials dedicated to the HIS, separate from the reception desk's.
  • The (provider, payer, agreement) combinations you'll use enabled for your integration.

Step 1 — Get an access token​

Pre-Attendance uses the same OAuth2 client-credentials flow as the rest of the platform:

curl -X POST https://sandbox.osigu.com/v1/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d "grant_type=client_credentials"

Cache the token for ~50 minutes. See Obtaining tokens.

Step 2 — Push the appointment​

Send each appointment as it's created in your HIS:

curl -X POST https://sandbox.osigu.com/pre-attendance-api/v1/checkin/appointments/his-inbound \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "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",
    "specialty_name": "Cardiology",
    "agreement_code": "AGR2024001",
    "charges": [
      { "provider_product_code": "PROC001", "provider_product_name": "Electrocardiogram (ECG)", "quantity": 1 }
    ]
  }'

external_appointment_id is your HIS identifier for the appointment and is the deduplication key. Use a stable, unique value per real appointment.

Step 3 — Handle the response​

CodeWhat it meansWhat to do
201 CreatedNew pre-appointment created, or new charge(s) merged into an existing one.Persist the returned appointment (note its id).
200 OKNothing new (already existed, no new charges).Safe to ignore — you're already in sync.
422Validation failed.Fix the payload; the body lists field paths.
404Provider or payer not resolvable.Check payer_tax_identification_number and your enabled combinations.
502RCM API unavailable.Retry with backoff (see below).

Both success codes return the current pre-appointment in the body, so for a simple sync you can persist the body without branching.

Step 4 — Retries are safe​

Because identity is (provider, external_appointment_id), re-sending is idempotent:

  • Re-send after a network error → no duplicate; you get the current state.
  • Re-send with an additional charge → only the new charge (by provider_product_code) is merged; the header is untouched.
  • Re-send unchanged → 200 OK no-op.

So on 502 or a timeout, just retry the same request with exponential backoff.

Step 5 — Update or delete an appointment​

When an appointment genuinely changes in your HIS (a re-send won't update the header), or is cancelled, use the management operations. Both address the appointment by external_appointment_id in the path and use the same HIS integration credentials as POST. See Managing an existing appointment for the full semantics.

Update (updates the header and reconciles charges — added / updated / removed):

curl -X PUT https://sandbox.osigu.com/pre-attendance-api/v1/checkin/appointments/his-inbound/HIS20260706001234 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "appointment_date": "2026-07-16T09:00: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", "charges": [ { "provider_product_code": "PROC001", "provider_product_name": "Electrocardiogram (ECG)", "quantity": 2 } ] }'

Returns 200 with the updated appointment. Charges missing from the list are soft-deleted. Only HIS_INBOUND appointments in PENDING/CONFIRMED can be updated (400 if it wasn't created by the HIS, 409 if it's COMPLETED/CANCELLED).

Delete (soft-delete, idempotent):

curl -X DELETE https://sandbox.osigu.com/pre-attendance-api/v1/checkin/appointments/his-inbound/HIS20260706001234 \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Returns 204 (also 204 if it was already cancelled). A COMPLETED appointment can't be deleted (409).

What NOT to do​

  • Don't reuse an external_appointment_id for a different visit — it will be treated as a re-send.
  • Don't expect a re-send to update the beneficiary/date/notes — a POST re-send never touches the header. Use PUT (Step 5) for that.

Next steps​