API Integration Documentation

Healthcare Management System - FHIR R4 Compliant

Introduction

This API provides comprehensive healthcare management functionality following the FHIR R4 standard. It enables third-party integrations for appointment scheduling, patient management, and telehealth consultation workflows.

Key Features:

  • FHIR R4 compliant resources
  • Real-time appointment scheduling
  • Patient registration and management
  • Telehealth consultation integration with OpenTok
  • Flexible pricing and coverage management

Authentication

Most endpoints require authentication using a Bearer token in the Authorization header.

Authorization Header 
Authorization: Bearer YOUR_ACCESS_TOKEN

Note: The /patients/sign-up endpoint is public and does not require authentication.

Base URL & Sandbox

Configure your base URL based on the environment:

Rate Limiting

API endpoints implement rate limiting to ensure service stability:

Endpoint Type Limit Time Window
Standard Operations (GET, POST, PATCH) 200 requests 60 seconds
Critical Operations (Start/Finish Consultation) 20 requests 60 seconds
Patient Sign-Up 50 requests 60 seconds

FHIR Format

This API follows the FHIR R4 (Fast Healthcare Interoperability Resources) standard. Resources are returned in JSON format following FHIR specifications:

  • Resources include resourceType field
  • Collections are returned as FHIR Bundle resources
  • References use format: ResourceType/id
  • Dates follow ISO 8601 format
Example FHIR Bundle Response 
{
  "resourceType": "Bundle",
  "type": "searchset",
  "total": 1,
  "entry": [
    {
      "resource": {
        "resourceType": "Appointment",
        "id": "12345"
      }
    }
  ]
}

API Endpoints

Authentication & Registration

POST /auth/login/external

Generate a custom authentication token for external patient access. This is a public endpoint that doesn't require prior authentication.

Public Endpoint: This endpoint does not require authentication. It's used to generate tokens for external patient login.

Query Parameters

Parameter Type Description
tenantIdREQUIRED string Tenant identifier

Request Body

Field Type Description
uidREQUIRED string User identifier (UID)

Response Codes

200
Token generated successfully
400
Invalid uid or tenantId
404
User not found
500
Error generating token

Example Request

cURL 
curl -X POST "https://dev.api.synapse.umasalud.com/nexus/auth/login/external?tenantId=hospital-abc" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "patient-auth-uid-123"
  }'

Example Response

JSON Response (200 OK) 
{
  "status": 200,
  "data": [{
    "data": {
      "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjFmODhiODE0MjljYzQ1M...",
      "expiresIn": 3600
    }
  }]
}

Error Responses

400 Bad Request 
{
  "status": 400,
  "message": "uid is required"
}
404 Not Found 
{
  "status": 404,
  "message": "User not found"
}
500 Server Error 
{
  "status": 500,
  "message": "Error generating custom token"
}
GET /schedules/appointments/search

Search and filter appointments by multiple criteria including practitioner, patient, location, date range, and status.

Query Parameters

Parameter Type Description
statusOPTIONAL string Appointment status (default: "booked")
startDateOPTIONAL string Start date filter (ISO 8601 format)
endDateOPTIONAL string End date filter (ISO 8601 format)
patientIdOPTIONAL string Patient ID to filter appointments
doctorIdOPTIONAL string Practitioner/Doctor ID to filter appointments
pageOPTIONAL number Page number for pagination
pageSizeOPTIONAL number Number of results per page

Appointment Status Values:

  • booked - Confirmed appointment
  • cancelled - Cancelled appointment
  • fulfilled - Completed appointment
  • pending - Pending confirmation
  • noshow - Patient did not show up
  • arrived - Patient has arrived
  • checked-in - Patient checked in

Response Codes

200
List of appointments matching criteria
404
No appointments found
500
Internal server error

Example Request

cURL 
curl -X GET "https://dev.api.synapse.umasalud.com/nexus/schedules/appointments/search?doctorId=123&startDate=2024-01-01&endDate=2024-01-31&status=booked&page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Example Response

JSON Response (200 OK) 
{
  "status": 200,
  "message": "Success",
  "totalRecords": 1,
  "data": {
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 1,
    "entry": [
      {
        "fullUrl": "https://api.synapse.com/fhir/Appointment/123",
        "resource": {
          "resourceType": "Appointment",
          "id": "123",
          "status": "booked",
          "start": "2024-01-15T10:00:00Z",
          "end": "2024-01-15T10:30:00Z",
          "minutesDuration": 30,
          "description": "Consulta general",
          "participant": [
            {
              "actor": {
                "reference": "Patient/456",
                "display": "Juan Pérez"
              },
              "status": "accepted"
            },
            {
              "actor": {
                "reference": "Practitioner/789",
                "display": "Dra. María García"
              },
              "status": "accepted"
            }
          ],
          "specialty": [{
            "coding": [{
              "system": "http://snomed.info/sct",
              "code": "394802001",
              "display": "General Medicine"
            }]
          }],
          "slot": [{
            "reference": "Slot/slot-123"
          }]
        },
        "search": {
          "mode": "match"
        }
      }
    ],
    "link": [
      {
        "relation": "self",
        "url": "https://dev.api.synapse.umasalud.com/nexus/schedules/appointments/search?page=1"
      },
      {
        "relation": "next",
        "url": "https://dev.api.synapse.umasalud.com/nexus/schedules/appointments/search?page=2"
      }
    ]
  }
}

Error Responses

404 Not Found 
{
  "status": 404,
  "message": "No appointments found",
  "totalRecords": 0,
  "data": {
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 0,
    "entry": []
  }
}
500 Server Error 
{
  "status": 500,
  "message": "Internal server error",
  "totalRecords": 0
}

Slot Selection

POST /schedules/appointments

Create a new appointment with slot reservation. Supports automatic price calculation based on patient coverage and consultation type.

Request Body

Field Type Description
identifierREQUIRED array Appointment identifiers with use, system, and value
serviceCategoryREQUIRED array Service category with coding (system, code, display)
serviceTypeREQUIRED array Service type classification
specialtyREQUIRED array Medical specialty (SNOMED CT codes)
appointmentTypeREQUIRED object Type of appointment (ROUTINE, EMERGENCY, etc.)
priorityREQUIRED number Priority level (0-9, where 0 is most urgent)
descriptionREQUIRED string Appointment description
startREQUIRED string Start date-time (ISO 8601, must be in future)
endREQUIRED string End date-time (ISO 8601, must be after start)
minutesDurationREQUIRED number Duration in minutes
slotREQUIRED array Slot references (at least one slot required)
participantREQUIRED array Participants with actor, required, status, and type
requestedPeriodREQUIRED array Requested time periods with start and end
proposedREQUIRED boolean true if proposed, false if confirmed
reasonCodeOPTIONAL array Reason for the appointment
commentOPTIONAL string Additional comments
patientInstructionOPTIONAL string Instructions for the patient
coverageTypeOPTIONAL string Coverage type for copay calculation
consultationTypeOPTIONAL string Consultation type: "virtual" or "onsite"

Validations:

  • start must be in the future and before end
  • Referenced slot must exist and be available
  • Participants (Patient, Practitioner) must exist in the system
  • Dates must be in ISO 8601 format with timezone

Response Codes

201
Appointment created successfully
400
Invalid data (e.g., dates, missing fields)
409
Slot already booked or conflict
500
Server error creating appointment

Example Request

cURL 
curl -X POST "https://dev.api.synapse.umasalud.com/nexus/schedules/appointments" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": [{
      "use": "official",
      "system": "https://synapse.com/appointments",
      "value": "APT-2024-001"
    }],
    "serviceCategory": [{
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/service-category",
        "code": "17",
        "display": "General Practice"
      }]
    }],
    "serviceType": [{
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/service-type",
        "code": "124",
        "display": "General Practice"
      }]
    }],
    "specialty": [{
      "coding": [{
        "system": "http://snomed.info/sct",
        "code": "394802001",
        "display": "General Medicine"
      }]
    }],
    "appointmentType": {
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/v2-0276",
        "code": "ROUTINE",
        "display": "Routine appointment"
      }]
    },
    "priority": 5,
    "description": "Consulta médica general",
    "start": "2024-01-15T10:00:00Z",
    "end": "2024-01-15T10:30:00Z",
    "minutesDuration": 30,
    "slot": [{
      "reference": "Slot/slot-12345"
    }],
    "participant": [
      {
        "actor": {
          "reference": "Patient/456",
          "display": "Juan Pérez"
        },
        "required": "required",
        "status": "accepted",
        "type": [{
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
            "code": "PPRF",
            "display": "primary performer"
          }]
        }]
      },
      {
        "actor": {
          "reference": "Practitioner/789",
          "display": "Dra. María García"
        },
        "required": "required",
        "status": "accepted",
        "type": [{
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
            "code": "ATND",
            "display": "attender"
          }]
        }]
      }
    ],
    "requestedPeriod": [{
      "start": "2024-01-15T10:00:00Z",
      "end": "2024-01-15T10:30:00Z"
    }],
    "proposed": false,
    "coverageType": "insurance",
    "consultationType": "virtual",
    "comment": "Primera consulta del paciente"
  }'

Example Response

JSON Response (201 Created) 
{
  "data": {
    "resource": {
      "resourceType": "Appointment",
      "id": "appointment-12345",
      "status": "booked",
      "identifier": [{
        "use": "official",
        "system": "https://synapse.com/appointments",
        "value": "APT-2024-001"
      }],
      "start": "2024-01-15T10:00:00Z",
      "end": "2024-01-15T10:30:00Z",
      "minutesDuration": 30,
      "description": "Consulta médica general",
      "priority": 5,
      "serviceCategory": [{
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/service-category",
          "code": "17",
          "display": "General Practice"
        }]
      }],
      "specialty": [{
        "coding": [{
          "system": "http://snomed.info/sct",
          "code": "394802001",
          "display": "General Medicine"
        }]
      }],
      "participant": [
        {
          "actor": {
            "reference": "Patient/456",
            "display": "Juan Pérez"
          },
          "required": "required",
          "status": "accepted"
        },
        {
          "actor": {
            "reference": "Practitioner/789",
            "display": "Dra. María García"
          },
          "required": "required",
          "status": "accepted"
        }
      ],
      "slot": [{
        "reference": "Slot/slot-12345"
      }],
      "comment": "Primera consulta del paciente",
      "meta": {
        "versionId": "1",
        "lastUpdated": "2024-01-10T14:30:00Z"
      }
    }
  }
}

Error Responses

400 Bad Request 
{
  "status": 400,
  "message": "Invalid appointment data",
  "error": {
    "field": "start",
    "message": "Start date must be in the future"
  }
}
409 Conflict 
{
  "status": 409,
  "message": "Slot is already booked",
  "error": {
    "slotId": "slot-12345",
    "currentStatus": "busy"
  }
}
500 Server Error 
{
  "status": 500,
  "message": "Error al crear la cita médica"
}
POST /patients/sign-up

Public endpoint for passwordless patient registration. The system sends an access link via email for authentication.

Public Endpoint: This endpoint does not require authentication.

Request Body

Field Type Description
tenantREQUIRED string Tenant identifier
patientData.identifierREQUIRED array Patient identifiers (DNI with system, value, type, use)
patientData.nameREQUIRED array Patient names with given and family names
patientData.telecomREQUIRED array Contact points (phone, email) with system, value, use
patientData.genderREQUIRED string Gender: male, female, other, unknown
patientData.birthDateREQUIRED string Birth date (YYYY-MM-DD format)
patientData.managingOrganizationREQUIRED object Organization reference (must exist in system)
patientData.coverageREQUIRED object Insurance coverage (affiliateNumber, organization, plan)
patientData.addressOPTIONAL array Patient addresses (use, type, text, line, city, state)
authDataOPTIONAL object Authentication data (uid, roleIds)

Registration Flow:

  1. Client sends patient data
  2. System validates data and DNI uniqueness
  3. Patient resource is created in FHIR

Response Codes

201
Patient registered successfully
400
Invalid data (missing DNI, etc.)
404
Organization not found
409
Patient already exists (duplicate DNI)
500
Server error creating patient

Example Request

cURL 
curl -X POST "https://dev.api.synapse.umasalud.com/nexus/patients/sign-up" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant": "hospital-abc",
    "patientData": {
      "identifier": [{
        "system": "http://www.argentina.gob.ar/dni",
        "value": "12345678",
        "type": {
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
            "code": "NNARG",
            "display": "National Identifier"
          }],
          "text": "DNI"
        },
        "use": "official"
      }],
      "name": [{
        "given": ["Juan", "Carlos"],
        "family": "Pérez"
      }],
      "telecom": [
        {
          "system": "phone",
          "value": "+54 11 1234-5678",
          "use": "mobile"
        },
        {
          "system": "email",
          "value": "juan.perez@email.com"
        }
      ],
      "gender": "male",
      "birthDate": "1990-05-15",
      "managingOrganization": {
        "reference": "Organization/org-123"
      },
      "coverage": {
        "affiliateNumber": "123456789",
        "organization": "osde-123",
        "plan": "plan-310"
      },
      "address": [{
        "use": "home",
        "type": "physical",
        "text": "Av. Corrientes 1234, Piso 5, CABA",
        "line": ["Av. Corrientes 1234", "Piso 5"],
        "city": "CABA",
        "state": "Buenos Aires"
      }]
    }
  }'

Example Response

JSON Response (201 Created) 
{
  "status": 201,
  "message": "Patient registered successfully",
  "totalRecords": 1,
  "data": {
    "resourceType": "Patient",
    "id": "patient-abc123",
    "active": true,
    "identifier": [{
      "system": "http://www.argentina.gob.ar/dni",
      "value": "12345678",
      "type": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/v2-0203",
          "code": "NNARG",
          "display": "National Identifier"
        }],
        "text": "DNI"
      },
      "use": "official"
    }],
    "managingOrganization": {
      "reference": "Organization/org-123"
    },
    "name": [{
      "given": ["Juan", "Carlos"],
      "family": "Pérez"
    }],
    "birthDate": "1990-05-15",
    "gender": "male",
    "telecom": [
      {
        "system": "phone",
        "value": "+54 11 1234-5678",
        "use": "mobile"
      },
      {
        "system": "email",
        "value": "juan.perez@email.com"
      }
    ],
    "address": [{
      "use": "home",
      "type": "physical",
      "text": "Av. Corrientes 1234, Piso 5, CABA",
      "line": ["Av. Corrientes 1234", "Piso 5"],
      "city": "CABA",
      "state": "Buenos Aires"
    }],
    "extension": [
      {
        "url": "http://synapse.com/fhir/StructureDefinition/coverage-organization",
        "valueString": "osde-123"
      },
      {
        "url": "http://synapse.com/fhir/StructureDefinition/coverage-affiliate",
        "valueString": "123456789"
      },
      {
        "url": "http://synapse.com/fhir/StructureDefinition/coverage-plan",
        "valueString": "plan-310"
      }
    ],
    "meta": {
      "versionId": "1",
      "lastUpdated": "2024-01-10T14:30:00Z"
    }
  }
}

Error Responses

400 Bad Request 
{
  "status": 400,
  "message": "Invalid patient data",
  "error": {
    "field": "identifier",
    "message": "DNI is required"
  }
}
404 Not Found 
{
  "status": 404,
  "message": "Organization not found",
  "error": {
    "organizationId": "org-123"
  }
}
409 Conflict 
{
  "status": 409,
  "message": "Patient already exists",
  "error": {
    "dni": "12345678",
    "existingPatientId": "patient-xyz789"
  }
}
500 Server Error 
{
  "status": 500,
  "message": "Error desconocido al crear paciente"
}

Appointment Management

PATCH /schedules/appointments/{id}/cancel

Cancel your own appointment as a patient. Only the patient associated with the appointment can cancel it using this endpoint.

Path Parameters

Parameter Type Description
idREQUIRED string Appointment ID to cancel

Request Body

Field Type Description
cancelationReasonOPTIONAL object CodeableConcept with cancellation reason

Authorization: This endpoint validates that the authenticated user is the patient associated with the appointment. You can only cancel your own appointments.

Response Codes

200
Appointment cancelled successfully
400
Patient not found or not authorized
404
Appointment not found

Example Request

cURL 
curl -X PATCH "https://dev.api.synapse.umasalud.com/nexus/schedules/appointments/appt-123/cancel" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cancelationReason": {
      "coding": [{
        "system": "http://terminology.hl7.org/CodeSystem/appointment-cancellation-reason",
        "code": "pat",
        "display": "Patient"
      }],
      "text": "No puedo asistir"
    }
  }'

Example Response

JSON Response (200 OK) 
{
  "status": 200,
  "data": {
    "data": {
      "resourceType": "Appointment",
      "id": "appt-123",
      "status": "cancelled",
      "cancelationReason": {
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/appointment-cancellation-reason",
          "code": "pat",
          "display": "Patient"
        }],
        "text": "No puedo asistir"
      },
      "start": "2024-01-15T10:00:00Z",
      "end": "2024-01-15T10:30:00Z",
      "participant": [{
        "actor": {
          "reference": "Patient/patient-456"
        },
        "status": "accepted"
      }]
    }
  }
}

Error Responses

400 Bad Request 
{
  "status": 400,
  "message": "You can only cancel appointments that belong to you"
}
404 Not Found 
{
  "status": 404,
  "message": "Appointment not found"
}

Consultation

GET /schedules/practitioners/{id}/slots

Get appointment slots for a specific practitioner. Returns an empty array if no slots are available. Can be filtered by date range and location.

Path Parameters

Parameter Type Description
idREQUIRED string Practitioner ID (must exist in system)

Query Parameters

Parameter Type Description
startOPTIONAL string Start date/time filter (ISO 8601 with timezone)
endOPTIONAL string End date/time filter (ISO 8601 with timezone)
locationIdOPTIONAL string Filter by location/office ID

Slot Status Values:

  • free - Available for booking
  • busy - Occupied (has appointment)
  • busy-unavailable - Not available (break, lunch, etc.)
  • busy-tentative - Temporarily reserved
  • entered-in-error - Created by mistake

Validation: The practitionerId must exist in the system. Dates must be in ISO 8601 format with timezone. If start and end are provided, start must be before end.

Response Codes

200
Slots retrieved successfully
400
Invalid query parameters
404
Practitioner not found or no slots
500
Server error retrieving slots

Example Request

cURL 
curl -X GET "https://dev.api.synapse.umasalud.com/nexus/schedules/practitioners/prac-123/slots?start=2024-01-15T00:00:00Z&end=2024-01-15T23:59:59Z&locationId=loc-456" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Example Response

JSON Response (200 OK) 
{
  "status": 200,
  "message": "Slots retrieved successfully",
  "totalRecords": 8,
  "data": {
    "data": {
      "resourceType": "Bundle",
      "type": "searchset",
      "total": 8,
      "entry": [
        {
          "fullUrl": "https://api.synapse.com/fhir/Slot/slot-123",
          "resource": {
            "resourceType": "Slot",
            "id": "slot-123",
            "status": "free",
            "start": "2024-01-15T10:00:00Z",
            "end": "2024-01-15T10:30:00Z",
            "schedule": {
              "reference": "Schedule/schedule-abc"
            },
            "specialty": [{
              "coding": [{
                "system": "http://snomed.info/sct",
                "code": "394802001",
                "display": "General Medicine"
              }],
              "text": "Medicina General"
            }],
            "serviceType": [{
              "coding": [{
                "system": "http://terminology.hl7.org/CodeSystem/service-type",
                "code": "124",
                "display": "General Practice"
              }]
            }],
            "appointmentType": {
              "coding": [{
                "system": "http://terminology.hl7.org/CodeSystem/v2-0276",
                "code": "ROUTINE",
                "display": "Routine appointment"
              }]
            },
            "comment": "Consulta general de 30 minutos"
          },
          "search": {
            "mode": "match"
          }
        },
        {
          "fullUrl": "https://api.synapse.com/fhir/Slot/slot-124",
          "resource": {
            "resourceType": "Slot",
            "id": "slot-124",
            "status": "free",
            "start": "2024-01-15T10:30:00Z",
            "end": "2024-01-15T11:00:00Z",
            "schedule": {
              "reference": "Schedule/schedule-abc"
            },
            "specialty": [{
              "coding": [{
                "system": "http://snomed.info/sct",
                "code": "394802001",
                "display": "General Medicine"
              }],
              "text": "Medicina General"
            }]
          },
          "search": {
            "mode": "match"
          }
        }
      ]
    }
  }
}

Error Responses

400 Bad Request 
{
  "status": 400,
  "message": "Invalid query parameters",
  "error": {
    "field": "start",
    "message": "Start date must be in ISO 8601 format"
  }
}
404 Not Found 
{
  "status": 404,
  "message": "No slots found for this practitioner",
  "totalRecords": 0,
  "data": {
    "data": {
      "resourceType": "Bundle",
      "type": "searchset",
      "total": 0,
      "entry": []
    }
  }
}
500 Server Error 
{
  "status": 500,
  "message": "Error al buscar los slots del profesional"
}
GET /schedules/slots/available

Get available slots filtered by medical specialty within an organization. Only returns slots with status "free" (available for booking).

Query Parameters

Parameter Type Description
organizationIdREQUIRED string Organization ID
specialtyCodeREQUIRED string SNOMED CT specialty code (e.g., "394802001" for General Medicine)
practitionerIdOPTIONAL string Filter by specific practitioner ID
startOPTIONAL string Start date/time filter (ISO 8601 with timezone)
endOPTIONAL string End date/time filter (ISO 8601 with timezone)
locationIdOPTIONAL string Filter by location/office ID

Common SNOMED CT Specialty Codes:

  • 394802001 - General Medicine
  • 394579002 - Cardiology
  • 394582007 - Dermatology
  • 394537008 - Pediatrics
  • 394587001 - Psychiatry
  • 394609007 - Surgery
  • 394610002 - Orthopedics
  • 394586005 - Gynecology
  • 394594003 - Ophthalmology
  • 394591006 - Neurology

Important: This endpoint only returns slots with status "free". Unlike other slot endpoints, occupied or unavailable slots are not included in the results.

Response Codes

200
Available slots retrieved successfully
400
Missing required parameters
404
No available slots found
500
Server error searching slots

Example Request

cURL 
curl -X GET "https://dev.api.synapse.umasalud.com/nexus/schedules/slots/available?organizationId=org-123&specialtyCode=394802001&practitionerId=prac-456&start=2024-01-15T09:00:00Z&end=2024-01-15T18:00:00Z&locationId=loc-789" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"

Example Response

JSON Response (200 OK) 
{
  "status": 200,
  "message": "Available slots retrieved successfully",
  "totalRecords": 12,
  "data": {
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 12,
    "entry": [
      {
        "fullUrl": "https://api.synapse.com/fhir/Slot/slot-abc123",
        "resource": {
          "resourceType": "Slot",
          "id": "slot-abc123",
          "status": "free",
          "start": "2024-01-15T10:00:00Z",
          "end": "2024-01-15T10:30:00Z",
          "schedule": {
            "reference": "Schedule/schedule-def456"
          },
          "specialty": [{
            "coding": [{
              "system": "http://snomed.info/sct",
              "code": "394802001",
              "display": "General Medicine"
            }],
            "text": "Medicina General"
          }],
          "serviceType": [{
            "coding": [{
              "system": "http://terminology.hl7.org/CodeSystem/service-type",
              "code": "124",
              "display": "General Practice"
            }]
          }],
          "appointmentType": {
            "coding": [{
              "system": "http://terminology.hl7.org/CodeSystem/v2-0276",
              "code": "ROUTINE",
              "display": "Routine appointment"
            }]
          },
          "comment": "Consulta general disponible",
          "extension": [{
            "url": "http://synapse.com/fhir/StructureDefinition/practitioner-name",
            "valueString": "Dr. Juan Pérez"
          }]
        },
        "search": {
          "mode": "match"
        }
      },
      {
        "fullUrl": "https://api.synapse.com/fhir/Slot/slot-abc124",
        "resource": {
          "resourceType": "Slot",
          "id": "slot-abc124",
          "status": "free",
          "start": "2024-01-15T10:30:00Z",
          "end": "2024-01-15T11:00:00Z",
          "schedule": {
            "reference": "Schedule/schedule-def456"
          },
          "specialty": [{
            "coding": [{
              "system": "http://snomed.info/sct",
              "code": "394802001",
              "display": "General Medicine"
            }],
            "text": "Medicina General"
          }]
        },
        "search": {
          "mode": "match"
        }
      }
    ]
  }
}

Error Responses

400 Bad Request 
{
  "status": 400,
  "message": "Missing required parameters",
  "error": {
    "missingFields": ["organizationId", "specialtyCode"]
  }
}
404 Not Found 
{
  "status": 404,
  "message": "No available slots found for this specialty",
  "totalRecords": 0,
  "data": {
    "resourceType": "Bundle",
    "type": "searchset",
    "total": 0,
    "entry": []
  }
}
500 Server Error 
{
  "status": 500,
  "message": "Error al buscar los slots para esa especialidad"
}
POST /encounters/start-consultation

Start a new medical consultation (encounter) from an existing appointment. Generates session credentials for video call using OpenTok.

Request Body

Field Type Description
appointmentIdREQUIRED string Appointment ID to start consultation from

Consultation Flow:

  1. Client sends appointmentId
  2. System validates appointment exists and is valid
  3. FHIR Encounter resource created with status "in-progress"
  4. Video call session generated (OpenTok)
  5. Returns: encounterId, sessionId, token, and encounter data
  6. Client uses credentials to initiate video call

Validations: The appointment must exist, have status "booked" or "arrived", have a valid date/time, and the patient and practitioner must exist in the system.

Response Codes

201
Encounter started successfully
400
Invalid or missing appointmentId
404
Appointment not found
409
Encounter already exists for appointment
500
Error starting encounter

OpenTok Video Call Credentials:

  • sessionId - Unique video session identifier
  • token - JWT token to authenticate user in the session

Use with OpenTok SDK:

const session = OT.initSession(apiKey, sessionId);
session.connect(token, callback);

Encounter Status Values

Status Description
planned Planned encounter
arrived Patient has arrived
in-progress Encounter in progress (typical initial state)
finished Encounter completed
cancelled Encounter cancelled

Encounter Class Types

Code Display
AMB Ambulatory (outpatient)
VR Virtual (telemedicine)
EMER Emergency
IMP Inpatient (hospitalized)
HH Home health (home visit)

Example Request

cURL 
curl -X POST "https://dev.api.synapse.umasalud.com/nexus/encounters/start-consultation" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "appointmentId": "appointment-abc123"
  }'

Example Response

JSON Response (201 Created) 
{
  "status": 201,
  "message": "Encounter started successfully",
  "totalRecords": 1,
  "data": {
    "encounterId": "encounter-xyz789",
    "sessionId": "1_MX4xMjM0NTY3ODl-fjE1MTYyMzk",
    "token": "T1==cGFydG5lcl9pZD00NTY3ODkxMiZzaWc9YWJjZGVm...",
    "encounter": {
      "resourceType": "Encounter",
      "id": "encounter-xyz789",
      "status": "in-progress",
      "class": {
        "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
        "code": "VR",
        "display": "Virtual"
      },
      "type": [{
        "coding": [{
          "system": "http://terminology.hl7.org/CodeSystem/encounter-type",
          "code": "ROUTINE",
          "display": "Routine"
        }],
        "text": "Consulta de rutina"
      }],
      "subject": {
        "reference": "Patient/patient-456",
        "display": "Juan Pérez"
      },
      "participant": [{
        "type": [{
          "coding": [{
            "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationType",
            "code": "PPRF",
            "display": "Primary Performer"
          }]
        }],
        "individual": {
          "reference": "Practitioner/prac-789",
          "display": "Dra. María García"
        }
      }],
      "appointment": [{
        "reference": "Appointment/appointment-abc123"
      }],
      "period": {
        "start": "2024-01-15T10:00:00Z"
      },
      "reasonCode": [{
        "coding": [{
          "system": "http://snomed.info/sct",
          "code": "386661006",
          "display": "Fever"
        }],
        "text": "Control médico general"
      }],
      "serviceProvider": {
        "reference": "Organization/org-123"
      },
      "meta": {
        "versionId": "1",
        "lastUpdated": "2024-01-15T10:00:00Z"
      }
    }
  }
}

Error Responses

400 Bad Request 
{
  "status": 400,
  "message": "Invalid request",
  "error": {
    "field": "appointmentId",
    "message": "appointmentId is required"
  }
}
404 Not Found 
{
  "status": 404,
  "message": "Appointment not found",
  "error": {
    "appointmentId": "appointment-abc123"
  }
}
409 Conflict 
{
  "status": 409,
  "message": "Encounter already exists for this appointment",
  "error": {
    "appointmentId": "appointment-abc123",
    "existingEncounterId": "encounter-existing-123"
  }
}
500 Server Error 
{
  "status": 500,
  "message": "Error starting encounter"
}