@healthcloudai/hc-sdk 3.23.0 → 3.24.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.cjs +101 -5
- package/dist/index.d.cts +1107 -3
- package/dist/index.d.ts +1107 -3
- package/dist/index.js +98 -5
- package/docs/clients/ProviderClient.md +7 -0
- package/docs/configuration.md +2 -2
- package/docs/docs-manifest.json +26 -3
- package/docs/examples/index.md +7 -0
- package/docs/index.md +7 -0
- package/docs/models/CreateProviderPatientRequest.md +22 -0
- package/docs/models/LabOrder.md +35 -0
- package/docs/models/LabOrderDiagnosis.md +18 -0
- package/docs/models/LabOrderErrorResponse.md +21 -0
- package/docs/models/LabOrderItemRequest.md +17 -0
- package/docs/models/LabOrderProvider.md +20 -0
- package/docs/models/LabOrderRequisitionResponse.md +20 -0
- package/docs/models/LabOrderTest.md +19 -0
- package/docs/models/LabOrderUnsentItem.md +19 -0
- package/docs/models/ListLabOrdersResponse.md +18 -0
- package/docs/models/PlaceLabOrderRequest.md +27 -0
- package/docs/models/PlaceLabOrderResponse.md +20 -0
- package/docs/models/ProviderEncounterStatusCounts.md +21 -0
- package/docs/models/ProviderHomeSummaryResponse.md +19 -0
- package/docs/models/ProviderPatientListResponse.md +19 -0
- package/docs/models/ProviderPatientResponse.md +17 -0
- package/docs/models/index.md +16 -0
- package/docs/operations/provider.createPatient.md +155 -0
- package/docs/operations/provider.getHomeSummary.md +115 -0
- package/docs/operations/provider.getLabOrder.md +179 -0
- package/docs/operations/provider.getLabOrderRequisition.md +148 -0
- package/docs/operations/provider.listLabOrders.md +198 -0
- package/docs/operations/provider.listPatients.md +154 -0
- package/docs/operations/provider.placeLabOrder.md +384 -0
- package/package.json +1 -1
|
@@ -0,0 +1,384 @@
|
|
|
1
|
+
# Place a Quest lab order for a tenant patient
|
|
2
|
+
|
|
3
|
+
Operation ID: `provider.placeLabOrder`
|
|
4
|
+
|
|
5
|
+
Place a Quest lab order for a patient in the authenticated provider's tenant. Catalog items (panels are expanded) are grouped into one Quest requisition, and one FHIR ServiceRequest, per collection modality: psc orders are held at a Quest Patient Service Center, home_kit orders need the tenant's home_kit_enabled flag. Rapid tests are not sent to Quest and come back under unsent_items. The ordering NPI (ORC-12/OBR-16) comes from the tenant's Quest roster in integration_attributes.QUEST, or from the tenant default provider for authorized orderers; it is never read from the Practitioner profile. Every active ask-at-order-entry question of every ordered Quest code must be answered, checked against the stored Quest compendium. 201: Quest accepted every requisition. 200: replay of the same idempotency_key and body. 202: Quest's answer is not known yet (timeout, 5xx, empty response); retry with the same idempotency_key and body, which re-sends the identical order, never a new one. 409 quest_rejected: Quest refused a requisition and the key is used up; the body lists every requisition so accepted ones are not ordered twice. Only Provider-pool tokens are accepted. Each call can place real orders: an agent must have the clinician's explicit confirmation.
|
|
6
|
+
|
|
7
|
+
## Public method
|
|
8
|
+
|
|
9
|
+
`placeLabOrder`
|
|
10
|
+
|
|
11
|
+
Signature: `provider.placeLabOrder(patientId, request)`
|
|
12
|
+
|
|
13
|
+
Return type: `Promise<PlaceLabOrderResponse>`
|
|
14
|
+
|
|
15
|
+
## Authentication
|
|
16
|
+
|
|
17
|
+
Classification: **AUTHENTICATED**
|
|
18
|
+
|
|
19
|
+
Schemes: `bearerAuth`
|
|
20
|
+
|
|
21
|
+
## Prerequisites
|
|
22
|
+
|
|
23
|
+
None documented.
|
|
24
|
+
|
|
25
|
+
## HTTP
|
|
26
|
+
|
|
27
|
+
`POST /patients/{patient_id}/lab-orders`
|
|
28
|
+
|
|
29
|
+
## Path parameters
|
|
30
|
+
|
|
31
|
+
| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|
|
32
|
+
|---|---|---:|---|---|---|---:|---|
|
|
33
|
+
| `patient_id` | `string` | Yes | | | | No | |
|
|
34
|
+
|
|
35
|
+
## Query parameters
|
|
36
|
+
|
|
37
|
+
None.
|
|
38
|
+
|
|
39
|
+
## Body parameters
|
|
40
|
+
|
|
41
|
+
| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|
|
42
|
+
|---|---|---:|---|---|---|---:|---|
|
|
43
|
+
| `body` | [`PlaceLabOrderRequest`](../models/PlaceLabOrderRequest.md) | No | | | | Yes | |
|
|
44
|
+
|
|
45
|
+
Request model: [`PlaceLabOrderRequest`](../models/PlaceLabOrderRequest.md)
|
|
46
|
+
|
|
47
|
+
## Request example
|
|
48
|
+
|
|
49
|
+
```json
|
|
50
|
+
{
|
|
51
|
+
"aoe_answers": {
|
|
52
|
+
"395": {
|
|
53
|
+
"75400658": "CLEAN CATCH URINE"
|
|
54
|
+
}
|
|
55
|
+
},
|
|
56
|
+
"collection_timezone": "America/New_York",
|
|
57
|
+
"comments": [
|
|
58
|
+
"FASTING 8 HOURS"
|
|
59
|
+
],
|
|
60
|
+
"diagnoses": [
|
|
61
|
+
{
|
|
62
|
+
"code": "R53.83",
|
|
63
|
+
"description": "Other fatigue"
|
|
64
|
+
}
|
|
65
|
+
],
|
|
66
|
+
"encounter_id": "encounter-example-001",
|
|
67
|
+
"expected_collection_date": "2026-10-29",
|
|
68
|
+
"idempotency_key": "00000000-0000-4000-8000-000000000010",
|
|
69
|
+
"items": [
|
|
70
|
+
{
|
|
71
|
+
"catalog_item_id": "00000000-0000-4000-8000-000000000020"
|
|
72
|
+
}
|
|
73
|
+
]
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Success responses
|
|
78
|
+
|
|
79
|
+
| Status | Shape | Content type | Description |
|
|
80
|
+
|---|---|---|---|
|
|
81
|
+
| `200` | [`PlaceLabOrderResponse`](../models/PlaceLabOrderResponse.md) | application/json | Replay: every requisition already existed with this idempotency_key and body |
|
|
82
|
+
| `201` | [`PlaceLabOrderResponse`](../models/PlaceLabOrderResponse.md) | application/json | Quest accepted every requisition |
|
|
83
|
+
| `202` | [`PlaceLabOrderResponse`](../models/PlaceLabOrderResponse.md) | application/json | At least one requisition is still being sent; retry with the same idempotency_key |
|
|
84
|
+
|
|
85
|
+
## Success response examples
|
|
86
|
+
|
|
87
|
+
### 200
|
|
88
|
+
|
|
89
|
+
```json
|
|
90
|
+
{
|
|
91
|
+
"order_group_id": "00000000-0000-4000-8000-000000000030",
|
|
92
|
+
"orders": [
|
|
93
|
+
{
|
|
94
|
+
"abn_required": false,
|
|
95
|
+
"ack_code": "AA",
|
|
96
|
+
"authored_at": "2026-10-28T09:15:00-04:00",
|
|
97
|
+
"collection_modality": "psc",
|
|
98
|
+
"diagnoses": [
|
|
99
|
+
{
|
|
100
|
+
"code": "R53.83",
|
|
101
|
+
"description": "Other fatigue"
|
|
102
|
+
}
|
|
103
|
+
],
|
|
104
|
+
"expected_collection_at": "2026-10-29T08:00:00-04:00",
|
|
105
|
+
"fhir_status": "active",
|
|
106
|
+
"lab": "MET",
|
|
107
|
+
"order_group_id": "00000000-0000-4000-8000-000000000030",
|
|
108
|
+
"order_id": "00000000-0000-4000-8000-000000000040",
|
|
109
|
+
"ordering_provider": {
|
|
110
|
+
"first_name": "Alex",
|
|
111
|
+
"last_name": "Smith",
|
|
112
|
+
"npi": "1234567893",
|
|
113
|
+
"source": "roster"
|
|
114
|
+
},
|
|
115
|
+
"patient_id": "patient-example-001",
|
|
116
|
+
"placer_order_number": "HC0123456789ABCDEF01",
|
|
117
|
+
"quest_http_status": null,
|
|
118
|
+
"requester": "Practitioner/practitioner-example-001",
|
|
119
|
+
"requisition_available": true,
|
|
120
|
+
"source": "provider_app",
|
|
121
|
+
"status": "accepted",
|
|
122
|
+
"tests": [
|
|
123
|
+
{
|
|
124
|
+
"catalog_item_id": "00000000-0000-4000-8000-000000000020",
|
|
125
|
+
"description": "URINALYSIS, COMPLETE",
|
|
126
|
+
"quest_code": "5463"
|
|
127
|
+
}
|
|
128
|
+
]
|
|
129
|
+
}
|
|
130
|
+
],
|
|
131
|
+
"replayed": true,
|
|
132
|
+
"unsent_items": [
|
|
133
|
+
{
|
|
134
|
+
"catalog_item_id": "00000000-0000-4000-8000-000000000060",
|
|
135
|
+
"name": "Visby CT/NG/TV",
|
|
136
|
+
"reason": "rapid_kit_flow"
|
|
137
|
+
}
|
|
138
|
+
]
|
|
139
|
+
}
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### 201
|
|
143
|
+
|
|
144
|
+
```json
|
|
145
|
+
{
|
|
146
|
+
"order_group_id": "string",
|
|
147
|
+
"orders": [
|
|
148
|
+
{
|
|
149
|
+
"abn_required": true,
|
|
150
|
+
"ack_code": "string",
|
|
151
|
+
"authored_at": "string",
|
|
152
|
+
"collection_modality": "psc",
|
|
153
|
+
"diagnoses": [],
|
|
154
|
+
"expected_collection_at": "string",
|
|
155
|
+
"fhir_status": "string",
|
|
156
|
+
"lab": "string",
|
|
157
|
+
"order_group_id": "string",
|
|
158
|
+
"order_id": "string",
|
|
159
|
+
"ordering_provider": {
|
|
160
|
+
"first_name": "string",
|
|
161
|
+
"last_name": "string",
|
|
162
|
+
"npi": "string",
|
|
163
|
+
"source": "roster"
|
|
164
|
+
},
|
|
165
|
+
"patient_id": "string",
|
|
166
|
+
"placer_order_number": "string",
|
|
167
|
+
"quest_http_status": 0,
|
|
168
|
+
"requester": "string",
|
|
169
|
+
"requisition_available": true,
|
|
170
|
+
"source": "provider_app",
|
|
171
|
+
"status": "submitting",
|
|
172
|
+
"tests": [
|
|
173
|
+
{
|
|
174
|
+
"catalog_item_id": "string",
|
|
175
|
+
"description": "string",
|
|
176
|
+
"quest_code": "string"
|
|
177
|
+
}
|
|
178
|
+
]
|
|
179
|
+
}
|
|
180
|
+
],
|
|
181
|
+
"replayed": true,
|
|
182
|
+
"unsent_items": [
|
|
183
|
+
{
|
|
184
|
+
"catalog_item_id": "string",
|
|
185
|
+
"name": "string",
|
|
186
|
+
"reason": "rapid_kit_flow"
|
|
187
|
+
}
|
|
188
|
+
]
|
|
189
|
+
}
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
### 202
|
|
193
|
+
|
|
194
|
+
```json
|
|
195
|
+
{
|
|
196
|
+
"order_group_id": "string",
|
|
197
|
+
"orders": [
|
|
198
|
+
{
|
|
199
|
+
"abn_required": true,
|
|
200
|
+
"ack_code": "string",
|
|
201
|
+
"authored_at": "string",
|
|
202
|
+
"collection_modality": "psc",
|
|
203
|
+
"diagnoses": [],
|
|
204
|
+
"expected_collection_at": "string",
|
|
205
|
+
"fhir_status": "string",
|
|
206
|
+
"lab": "string",
|
|
207
|
+
"order_group_id": "string",
|
|
208
|
+
"order_id": "string",
|
|
209
|
+
"ordering_provider": {
|
|
210
|
+
"first_name": "string",
|
|
211
|
+
"last_name": "string",
|
|
212
|
+
"npi": "string",
|
|
213
|
+
"source": "roster"
|
|
214
|
+
},
|
|
215
|
+
"patient_id": "string",
|
|
216
|
+
"placer_order_number": "string",
|
|
217
|
+
"quest_http_status": 0,
|
|
218
|
+
"requester": "string",
|
|
219
|
+
"requisition_available": true,
|
|
220
|
+
"source": "provider_app",
|
|
221
|
+
"status": "submitting",
|
|
222
|
+
"tests": [
|
|
223
|
+
{
|
|
224
|
+
"catalog_item_id": "string",
|
|
225
|
+
"description": "string",
|
|
226
|
+
"quest_code": "string"
|
|
227
|
+
}
|
|
228
|
+
]
|
|
229
|
+
}
|
|
230
|
+
],
|
|
231
|
+
"replayed": true,
|
|
232
|
+
"unsent_items": [
|
|
233
|
+
{
|
|
234
|
+
"catalog_item_id": "string",
|
|
235
|
+
"name": "string",
|
|
236
|
+
"reason": "rapid_kit_flow"
|
|
237
|
+
}
|
|
238
|
+
]
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
## Common errors
|
|
243
|
+
|
|
244
|
+
| Status | Shape | Content type | Description |
|
|
245
|
+
|---|---|---|---|
|
|
246
|
+
| `400` | [`LabOrderErrorResponse`](../models/LabOrderErrorResponse.md) | application/json | The body is invalid or an AOE question is not answered |
|
|
247
|
+
| `401` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Provider Bearer authentication is required |
|
|
248
|
+
| `403` | [`LabOrderErrorResponse`](../models/LabOrderErrorResponse.md) | application/json | Not a Provider-pool token, or the caller is neither on the tenant's Quest roster nor authorized to order under the default provider |
|
|
249
|
+
| `404` | [`LabOrderErrorResponse`](../models/LabOrderErrorResponse.md) | application/json | The patient or encounter does not exist in the caller's tenant |
|
|
250
|
+
| `409` | [`LabOrderErrorResponse`](../models/LabOrderErrorResponse.md) | application/json | The tenant's account is not active, Quest ordering is not enabled, the key was used with another body, an item is unavailable, or Quest rejected the order |
|
|
251
|
+
| `500` | [`provider.ErrorResponse`](../models/provider.ErrorResponse.md) | application/json | Unexpected failure; retry with the same idempotency_key |
|
|
252
|
+
| `503` | [`LabOrderErrorResponse`](../models/LabOrderErrorResponse.md) | application/json | The order is saved but not sent, or no Quest compendium is stored; retry with the same key |
|
|
253
|
+
|
|
254
|
+
## Error examples
|
|
255
|
+
|
|
256
|
+
### 400 — Unanswered AOE question
|
|
257
|
+
|
|
258
|
+
```json
|
|
259
|
+
{
|
|
260
|
+
"code": "aoe_answer_missing",
|
|
261
|
+
"error": "An ask-at-order-entry question is not answered",
|
|
262
|
+
"fields": [
|
|
263
|
+
"aoe_answers.395.75400658"
|
|
264
|
+
]
|
|
265
|
+
}
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
### 401 — No provider JWT
|
|
269
|
+
|
|
270
|
+
```json
|
|
271
|
+
{
|
|
272
|
+
"error": "Provider authorization required"
|
|
273
|
+
}
|
|
274
|
+
```
|
|
275
|
+
|
|
276
|
+
### 403 — Caller cannot order
|
|
277
|
+
|
|
278
|
+
```json
|
|
279
|
+
{
|
|
280
|
+
"code": "not_an_ordering_provider",
|
|
281
|
+
"error": "Caller may not order Quest labs in this tenant",
|
|
282
|
+
"fields": []
|
|
283
|
+
}
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
### 404 — Unknown patient
|
|
287
|
+
|
|
288
|
+
```json
|
|
289
|
+
{
|
|
290
|
+
"code": "patient_not_found",
|
|
291
|
+
"error": "Patient not found in this tenant",
|
|
292
|
+
"fields": []
|
|
293
|
+
}
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
### 409 — Same key, different body
|
|
297
|
+
|
|
298
|
+
```json
|
|
299
|
+
{
|
|
300
|
+
"code": "idempotency_key_reused",
|
|
301
|
+
"error": "Idempotency key already used with a different order",
|
|
302
|
+
"fields": [
|
|
303
|
+
"idempotency_key"
|
|
304
|
+
]
|
|
305
|
+
}
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
### 500 — Unexpected failure
|
|
309
|
+
|
|
310
|
+
```json
|
|
311
|
+
{
|
|
312
|
+
"error": "Lab order service failed; retry the request"
|
|
313
|
+
}
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
### 503 — Saved, not sent
|
|
317
|
+
|
|
318
|
+
```json
|
|
319
|
+
{
|
|
320
|
+
"code": "order_not_sent",
|
|
321
|
+
"error": "The order was saved but not sent; retry with the same key",
|
|
322
|
+
"fields": []
|
|
323
|
+
}
|
|
324
|
+
```
|
|
325
|
+
|
|
326
|
+
## NodeJS / TypeScript implementation
|
|
327
|
+
|
|
328
|
+
```ts
|
|
329
|
+
import { HCSDK } from "@healthcloudai/hc-sdk";
|
|
330
|
+
```
|
|
331
|
+
|
|
332
|
+
```ts
|
|
333
|
+
const patientId = "<PATIENT_ID>";
|
|
334
|
+
|
|
335
|
+
const request = {
|
|
336
|
+
"aoe_answers": {
|
|
337
|
+
"395": {
|
|
338
|
+
"75400658": "CLEAN CATCH URINE"
|
|
339
|
+
}
|
|
340
|
+
},
|
|
341
|
+
"collection_timezone": "America/New_York",
|
|
342
|
+
"comments": [
|
|
343
|
+
"FASTING 8 HOURS"
|
|
344
|
+
],
|
|
345
|
+
"diagnoses": [
|
|
346
|
+
{
|
|
347
|
+
"code": "R53.83",
|
|
348
|
+
"description": "Other fatigue"
|
|
349
|
+
}
|
|
350
|
+
],
|
|
351
|
+
"encounter_id": "encounter-example-001",
|
|
352
|
+
"expected_collection_date": "2026-10-29",
|
|
353
|
+
"idempotency_key": "00000000-0000-4000-8000-000000000010",
|
|
354
|
+
"items": [
|
|
355
|
+
{
|
|
356
|
+
"catalog_item_id": "00000000-0000-4000-8000-000000000020"
|
|
357
|
+
}
|
|
358
|
+
]
|
|
359
|
+
};
|
|
360
|
+
|
|
361
|
+
const result = await provider.placeLabOrder(patientId, request);
|
|
362
|
+
```
|
|
363
|
+
|
|
364
|
+
## cURL
|
|
365
|
+
|
|
366
|
+
```bash
|
|
367
|
+
curl -X POST \
|
|
368
|
+
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
|
|
369
|
+
-H 'Content-Type: application/json' \
|
|
370
|
+
-d '{"aoe_answers":{"395":{"75400658":"CLEAN CATCH URINE"}},"collection_timezone":"America/New_York","comments":["FASTING 8 HOURS"],"diagnoses":[{"code":"R53.83","description":"Other fatigue"}],"encounter_id":"encounter-example-001","expected_collection_date":"2026-10-29","idempotency_key":"00000000-0000-4000-8000-000000000010","items":[{"catalog_item_id":"00000000-0000-4000-8000-000000000020"}]}' \
|
|
371
|
+
'https://dev-api-provider.health.cloud/patients/%3CPATIENT_ID%3E/lab-orders'
|
|
372
|
+
```
|
|
373
|
+
|
|
374
|
+
## Notes
|
|
375
|
+
|
|
376
|
+
None.
|
|
377
|
+
|
|
378
|
+
## Prepared Test Console scenario
|
|
379
|
+
|
|
380
|
+
No canonical scenario is currently associated.
|
|
381
|
+
|
|
382
|
+
## Real response
|
|
383
|
+
|
|
384
|
+
No approved real integration response is currently published. Unapproved candidates are never rendered as examples.
|
package/package.json
CHANGED