{
 "openapi": "3.0.3",
 "info": {
  "title": "Caresoft BBMS API",
  "version": "1.0",
  "description": "API for hospital information systems to exchange patients, blood requests, stock and transfusion data with Caresoft BBMS. JSON and HL7 FHIR R4. Authentication: organisation API token (Settings \u2192 API access for HIS). Events back to your HIS are signed webhooks: X-BBMS-Signature: sha256=HMAC-SHA256(secret, timestamp + \".\" + body), X-BBMS-Timestamp, X-BBMS-Event."
 },
 "servers": [
  {
   "url": "{base}/api/v1",
   "variables": {
    "base": {
     "default": "https://bbms.example.in"
    }
   }
  }
 ],
 "security": [
  {
   "bearer": []
  }
 ],
 "paths": {
  "/ping": {
   "get": {
    "summary": "Check the token works",
    "tags": [
     "General"
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/patients": {
   "post": {
    "summary": "Create or update a patient (by his_patient_id)",
    "tags": [
     "JSON"
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/Patient"
       }
      }
     }
    }
   }
  },
  "/requisitions": {
   "post": {
    "summary": "Create a blood request; repeat calls with the same his_ref return the existing request",
    "tags": [
     "JSON"
    ],
    "responses": {
     "201": {
      "description": "OK"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/Requisition"
       }
      }
     }
    }
   }
  },
  "/requisitions/{ref}": {
   "get": {
    "summary": "Request status, patient group, reserved and issued bags",
    "tags": [
     "JSON"
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     }
    },
    "parameters": [
     {
      "name": "ref",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Your HIS order reference (his_ref)"
     }
    ]
   }
  },
  "/requisitions/{ref}/cancel": {
   "post": {
    "summary": "Cancel a request before any bag is issued",
    "tags": [
     "JSON"
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     }
    },
    "parameters": [
     {
      "name": "ref",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      },
      "description": "Your HIS order reference (his_ref)"
     }
    ]
   }
  },
  "/stock": {
   "get": {
    "summary": "Available units by group and component",
    "tags": [
     "JSON"
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/transfusions": {
   "post": {
    "summary": "Record transfusion start/end for an issued bag",
    "tags": [
     "JSON"
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "$ref": "#/components/schemas/Transfusion"
       }
      }
     }
    }
   }
  },
  "/fhir/metadata": {
   "get": {
    "summary": "FHIR CapabilityStatement",
    "tags": [
     "FHIR"
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     }
    }
   }
  },
  "/fhir/Patient": {
   "post": {
    "summary": "Create or update a patient from a FHIR R4 Patient",
    "tags": [
     "FHIR"
    ],
    "responses": {
     "201": {
      "description": "OK"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/fhir+json": {
       "schema": {
        "$ref": "#/components/schemas/FhirResource"
       }
      }
     }
    }
   }
  },
  "/fhir/ServiceRequest": {
   "post": {
    "summary": "One blood component per ServiceRequest. ServiceRequests sharing requisition.value form one BBMS request. code.coding.code = BBMS component code (system https://caresoft.co.in/fhir/CodeSystem/bbms-component); quantityQuantity.value = units; priority routine|urgent|asap|stat.",
    "tags": [
     "FHIR"
    ],
    "responses": {
     "201": {
      "description": "OK"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     }
    },
    "requestBody": {
     "required": true,
     "content": {
      "application/fhir+json": {
       "schema": {
        "$ref": "#/components/schemas/FhirResource"
       }
      }
     }
    }
   },
   "get": {
    "summary": "Search by identifier (order or order line reference); returns a searchset Bundle",
    "tags": [
     "FHIR"
    ],
    "responses": {
     "200": {
      "description": "OK"
     },
     "401": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     }
    },
    "parameters": [
     {
      "name": "identifier",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ]
   }
  }
 },
 "components": {
  "securitySchemes": {
   "bearer": {
    "type": "http",
    "scheme": "bearer"
   }
  },
  "responses": {
   "Error": {
    "description": "Error. JSON endpoints: {ok:false,error}. FHIR endpoints: OperationOutcome.",
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "ok": {
         "type": "boolean"
        },
        "error": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "schemas": {
   "Patient": {
    "type": "object",
    "required": [
     "his_patient_id",
     "uhid",
     "full_name",
     "sex"
    ],
    "properties": {
     "his_patient_id": {
      "type": "string"
     },
     "uhid": {
      "type": "string"
     },
     "full_name": {
      "type": "string"
     },
     "sex": {
      "type": "string",
      "enum": [
       "M",
       "F",
       "O"
      ]
     },
     "dob": {
      "type": "string",
      "format": "date"
     },
     "age_years": {
      "type": "integer"
     },
     "mobile": {
      "type": "string"
     },
     "abha_no": {
      "type": "string"
     }
    }
   },
   "Requisition": {
    "type": "object",
    "required": [
     "his_ref",
     "indication",
     "items"
    ],
    "properties": {
     "his_ref": {
      "type": "string"
     },
     "patient": {
      "$ref": "#/components/schemas/Patient"
     },
     "his_patient_id": {
      "type": "string",
      "description": "Instead of patient, for a patient already sent"
     },
     "urgency": {
      "type": "string",
      "enum": [
       "ROUTINE",
       "URGENT",
       "EMERGENCY"
      ]
     },
     "items": {
      "type": "array",
      "items": {
       "type": "object",
       "required": [
        "component_code",
        "units"
       ],
       "properties": {
        "component_code": {
         "type": "string",
         "example": "PRBC"
        },
        "units": {
         "type": "integer",
         "minimum": 1,
         "maximum": 20
        }
       }
      }
     },
     "indication": {
      "type": "string"
     },
     "diagnosis": {
      "type": "string"
     },
     "ipd_no": {
      "type": "string"
     },
     "ward_code": {
      "type": "string"
     },
     "bed_no": {
      "type": "string"
     },
     "doctor_code": {
      "type": "string"
     },
     "department_code": {
      "type": "string"
     },
     "scheme_code": {
      "type": "string"
     },
     "hb_gdl": {
      "type": "number"
     },
     "platelet_count": {
      "type": "integer"
     },
     "planned_at": {
      "type": "string",
      "example": "2026-10-06 09:00:00"
     }
    }
   },
   "Transfusion": {
    "type": "object",
    "required": [
     "bag_no",
     "uhid"
    ],
    "properties": {
     "bag_no": {
      "type": "string",
      "description": "Scanned bag number"
     },
     "uhid": {
      "type": "string",
      "description": "Scanned patient wristband UHID; must match the issue"
     },
     "checked_by": {
      "type": "string"
     },
     "second_checker": {
      "type": "string"
     },
     "started_at": {
      "type": "string",
      "example": "2026-10-06 10:15:00"
     },
     "ended_at": {
      "type": "string"
     },
     "volume_ml": {
      "type": "integer"
     },
     "vitals_pre": {
      "type": "object"
     },
     "vitals_15": {
      "type": "object"
     },
     "vitals_post": {
      "type": "object"
     },
     "had_reaction": {
      "type": "boolean"
     },
     "stopped": {
      "type": "boolean"
     },
     "notes": {
      "type": "string"
     }
    }
   },
   "FhirResource": {
    "type": "object",
    "required": [
     "resourceType"
    ],
    "properties": {
     "resourceType": {
      "type": "string"
     }
    },
    "additionalProperties": true
   }
  }
 },
 "tags": [
  {
   "name": "General"
  },
  {
   "name": "JSON",
   "description": "BBMS JSON API"
  },
  {
   "name": "FHIR",
   "description": "HL7 FHIR R4"
  }
 ]
}