AVENIX Open API
Luồng vận hành
Bắt đầu
API cho phần mềm đối tác kết nối với một phòng khám dùng AVENIX. Giới hạn 300 lượt mỗi phút cho mỗi kết nối.
https://app.avenix.vn/v1/open- Phòng khám vào Cài đặt, mục Kết nối API, tạo kết nối rồi gửi mã và bí mật cho bạn. Mỗi phòng khám một kết nối riêng.
- Đổi mã và bí mật lấy token, token sống 1 giờ. Hết hạn thì lấy token mới.
- Gửi token trong header
Authorizationở mỗi lượt gọi. Chỉ gọi từ máy chủ của bạn, đừng để bí mật trong ứng dụng hay trình duyệt.
curl -X POST 'https://app.avenix.vn/v1/open/oauth/token' \ -d grant_type=client_credentials \ -d client_id=$CLIENT_ID \ -d client_secret=$CLIENT_SECRET
Dùng AI lập trình thì bấm Sao chép cho AI ở đầu trang để lấy toàn bộ tài liệu rồi dán vào khung chat, hoặc ở từng route khi chỉ cần một việc. Dùng Postman thì bấm Tải về rồi chọn Tệp OpenAPI.
Quy ước
- Tạo mới: gửi kèm header
Idempotency-Key. Gửi lại cùng khoá trong 24 giờ nhận lại đúng kết quả cũ, không tạo trùng. - Danh sách: truyền
nextCursorvàocursorđể lấy trang sau, trống là hết. - Giới hạn: các header
RateLimit-*báo số lượt còn lại, vượt thì nhận 429 kèmRetry-After. - Tương thích: trong phiên bản v1 chỉ thêm trường và route mới, không bỏ hay đổi kiểu. Phần mềm của bạn cần bỏ qua trường lạ.
Mã lỗi
Lỗi trả về theo RFC 9457, dạng application/problem+json. Riêng route đổi token trả lỗi theo RFC 6749, dạng error và error_description.
| Mã | Ý nghĩa |
|---|---|
400 | Dữ liệu gửi lên không hợp lệ. |
401 | Thiếu token, token hết hạn hoặc kết nối đã bị thu hồi. |
403 | Token không có phạm vi này, ngoài chi nhánh được cấp, hoặc gói chưa có tính năng. |
404 | Không tìm thấy bản ghi. |
409 | Xung đột dữ liệu, hoặc khoá chống trùng đang được xử lý. |
422 | Dữ liệu hợp lệ nhưng không làm được theo luật nghiệp vụ. |
429 | Vượt giới hạn gọi. Chờ theo header Retry-After. |
{ "type": "about:blank", "title": "Not Found", "status": 404, "detail": "Không tìm thấy khách hàng", "instance": "/v1/open/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6" }
Webhook
Phòng khám khai địa chỉ https của bạn ở kết nối API. Khi có việc xảy ra, phần mềm gửi một lượt POST. Bản tin chỉ mang mã và trạng thái, hãy gọi API để đọc chi tiết.
- Trả mã 2xx trong 10 giây là đã nhận, xử lý lâu thì đưa vào hàng đợi của bạn.
- Chưa nhận được thì gửi lại sau 5 giây, 5 phút, 30 phút, 2 giờ, 5 giờ, 10 giờ, 10 giờ, cùng
webhook-id. Hãy bỏ qua mã đã xử lý. - Thứ tự không được bảo đảm, dựa vào dữ liệu đọc qua API.
- Nút Gửi thử của phòng khám gửi sự kiện
webhook.testvới dữ liệu trống. - Trả 410 là báo không dùng địa chỉ này nữa, phần mềm sẽ tắt địa chỉ. Không chuyển hướng: mã 3xx tính là hỏng.
Mẫu bản tin
webhook-id: 5f0c2a1e-7d3b-4a9e-8c21-1b6f4e2d9a10
webhook-timestamp: 1793512800
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4={ "id": "5f0c2a1e-7d3b-4a9e-8c21-1b6f4e2d9a10", "type": "customer.created", "timestamp": "2026-11-01T09:00:00+07:00", "data": { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }
Kiểm chữ ký
// Dùng nguyên văn thân bản tin chưa parse. import { createHmac, timingSafeEqual } from 'node:crypto'; function verify(secret, headers, rawBody) { const id = headers['webhook-id']; const ts = headers['webhook-timestamp']; if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; const key = Buffer.from(secret.replace('whsec_', ''), 'base64'); const mac = createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64'); const expected = Buffer.from(`v1,${mac}`); // Trong lúc đổi bí mật, header có thể mang hai chữ ký cách nhau bằng dấu cách. return headers['webhook-signature'].split(' ').some((sig) => { const got = Buffer.from(sig); return got.length === expected.length && timingSafeEqual(got, expected); }); }
Các sự kiện
| Sự kiện | Mô tả | Phạm vi | Dữ liệu |
|---|---|---|---|
customer.created | Có hồ sơ khách mới | customers:read | id |
customer.updated | Hồ sơ khách đổi thông tin | customers:read | id |
customer.deleted | Hồ sơ khách bị xoá | customers:read | id |
appointment.created | Có lịch hẹn mới | appointments:read | idbranchIdcustomerIdstatus |
appointment.updated | Lịch hẹn đổi giờ, bác sĩ hoặc thông tin khác | appointments:read | idbranchIdcustomerIdstatus |
appointment.status_changed | Lịch hẹn đổi trạng thái | appointments:read | idbranchIdcustomerIdstatus |
invoice.created | Có hoá đơn mới | invoices:read | idbranchIdstatus |
invoice.status_changed | Hoá đơn đổi trạng thái | invoices:read | idbranchIdstatus |
payment.created | Có phiếu thu mới | invoices:read | idinvoiceIdbranchId |
payment.refunded | Phiếu thu được hoàn tiền | invoices:read | idinvoiceIdbranchId |
Phạm vi quyền
| Phạm vi | Cho phép |
|---|---|
customers:read | Tìm và xem thông tin hành chính của khách: họ tên, số điện thoại, email, địa chỉ, nghề nghiệp, người liên hệ. |
customers:write | Tạo hồ sơ khách mới và sửa thông tin hành chính. |
customers:identity | Đọc và ghi số CCCD, hộ chiếu, CCCD người giám hộ, thẻ BHYT. Đi kèm phạm vi xem hoặc sửa khách. |
appointments:read | Xem chi nhánh, bác sĩ, giờ trống và lịch hẹn kèm tên khách. |
appointments:write | Tạo lịch hẹn, đổi giờ và huỷ lịch hẹn. |
leads:write | Đưa khách từ form, landing page của đối tác vào phễu Khách tiềm năng. |
catalog:read | Đọc tên, giá bán và thông tin của dịch vụ, hàng hoá. Không có giá vốn, không có tồn kho. |
catalog:cost | Đọc giá vốn của dịch vụ và hàng hoá. Đi kèm phạm vi xem dịch vụ, hàng hoá. |
suppliers:read | Đọc danh sách nhà cung cấp kèm người liên hệ, và nhà cung cấp của lần nhập gần nhất trên từng hàng hoá. |
invoices:read | Đọc hoá đơn, dòng hàng, số tiền và phiếu thu để đưa sang phần mềm kế toán. |
Xác thực
Mọi lượt gọi API đều cần token. Token đổi từ mã kết nối và bí mật do phòng khám cấp, theo chuẩn OAuth 2.0 Client Credentials, không gắn với tài khoản nhân viên nào. Quyền của token là các phạm vi phòng khám đã tích khi tạo kết nối, phòng khám thu hồi kết nối thì token ngừng hoạt động ngay.
Dùng khi
- Máy chủ của bạn khởi động và cần token đầu tiên.
- Token hết hạn: lưu lại dùng tới khi hết hạn, đừng xin token mới cho từng lượt gọi vì route này giới hạn 30 lượt mỗi phút.
Lấy token truy cập
/oauth/tokenNội dung gửi
| Tên trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
grant_type | enum | Bắt buộc | Luôn là client_credentials. |
client_id | string | Bắt buộc | Mã kết nối phòng khám cấp, dạng avxc_.... |
client_secret | string | Bắt buộc | Bí mật của kết nối, dạng avxs_.... |
scope | string | Các phạm vi muốn dùng, ngăn bằng dấu cách. Bỏ trống để lấy mọi phạm vi của kết nối. |
curl -X POST 'https://app.avenix.vn/v1/open/oauth/token' \ -d grant_type=client_credentials \ -d client_id=$CLIENT_ID \ -d client_secret=$CLIENT_SECRET
{ "access_token": "<token>", "token_type": "Bearer", "expires_in": 3600, "scope": "customers:read appointments:read" }
Các trường trả về4
| Tên trường | Kiểu | Mô tả |
|---|---|---|
access_token | string | Token gửi trong header Authorization: Bearer. |
token_type | enum | Luôn là Bearer. |
expires_in | integer | Số giây token còn hiệu lực. |
scope | string | Các phạm vi token mang, ngăn bằng dấu cách. |
Chi nhánh và bác sĩ
Danh mục nền để gọi các route khác. Dữ liệu của phòng khám chia theo chi nhánh, và mỗi kết nối chỉ làm việc trong các chi nhánh được cấp, nên phần mềm của bạn cần biết mã chi nhánh và mã bác sĩ trước khi đặt lịch hay tạo khách.
Dùng khi
- Hiện ô chọn cơ sở và bác sĩ trên website đặt lịch.
- Ghép chi nhánh của AVENIX với chi nhánh trong phần mềm của bạn.
Lấy danh sách chi nhánh
id của chi nhánh làm branchId khi xem giờ trống, tạo lịch hẹn, tạo khách hàng hoặc lọc hoá đơn. Chi nhánh không được cấp sẽ không xuất hiện ở đây, và gửi mã của nó lên các route khác sẽ bị từ chối./branchesappointments:readcurl -X GET 'https://app.avenix.vn/v1/open/branches' \ -H "Authorization: Bearer $TOKEN"
{ "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "name": "Chi nhánh Quận 1", "province": "TP. Hồ Chí Minh", "ward": "Phường Bến Nghé", "streetAddress": "12 Lê Lợi", "phone": "+84901234567", "email": "[email protected]", "taxCode": "string", "googleMapUrl": "string", "latitude": 1, "longitude": 1, "directorName": "string", "operatingLicenseNo": "string" } ] }
Các trường trả về15
| Tên trường | Kiểu | Mô tả |
|---|---|---|
data | array | Các dòng của trang này. |
data[].id | uuid | Mã chi nhánh. |
data[].code | string | Mã ngắn của chi nhánh. |
data[].name | string | Tên chi nhánh. |
data[].province | stringCó thể trống | Tỉnh, thành phố. |
data[].ward | stringCó thể trống | Phường, xã. |
data[].streetAddress | stringCó thể trống | Số nhà, tên đường. |
data[].phone | stringCó thể trống | Số điện thoại chi nhánh. |
data[].email | stringCó thể trống | Email chi nhánh. |
data[].taxCode | stringCó thể trống | Mã số thuế. |
data[].googleMapUrl | stringCó thể trống | Đường dẫn Google Maps. |
data[].latitude | numberCó thể trống | Vĩ độ. |
data[].longitude | numberCó thể trống | Kinh độ. |
data[].directorName | stringCó thể trống | Người phụ trách cơ sở. |
data[].operatingLicenseNo | stringCó thể trống | Số giấy phép hoạt động. |
Lấy danh sách bác sĩ
id làm doctorId khi xem giờ trống hoặc tạo lịch hẹn. Danh sách ít thay đổi nên có thể lưu tạm ở phía bạn thay vì gọi trước mỗi lượt đặt lịch./doctorsappointments:readcurl -X GET 'https://app.avenix.vn/v1/open/doctors' \ -H "Authorization: Bearer $TOKEN"
{ "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "fullName": "Nguyễn Văn An", "jobTitle": "string" } ] }
Các trường trả về4
| Tên trường | Kiểu | Mô tả |
|---|---|---|
data | array | Các dòng của trang này. |
data[].id | uuid | Mã bác sĩ. |
data[].fullName | string | Họ tên bác sĩ. |
data[].jobTitle | stringCó thể trống | Chức danh. |
Khách hàng
Đọc và ghi hồ sơ hành chính của khách: họ tên, các số điện thoại, ngày sinh, giới tính, email, địa chỉ trong và ngoài nước, nghề nghiệp, người liên hệ, nguồn khách. Số CCCD, hộ chiếu, thẻ BHYT cần thêm phạm vi customers:identity. Trường externalId lưu mã khách bên phần mềm của bạn để khỏi phải tự giữ bảng ghép. Đây là cầu nối giữa CRM hay website của bạn với phòng khám. Hồ sơ bệnh án và dữ liệu lâm sàng không có trong API này.
Dùng khi
- Đồng bộ khách hai chiều với CRM: lấy toàn bộ một lần, rồi theo dõi thay đổi bằng webhook.
- Tra khách theo số điện thoại khi có cuộc gọi hoặc form mới, chưa có thì tạo hồ sơ.
Lấy danh sách khách hàng
q, hoặc theo số điện thoại đầy đủ qua phone. Bỏ trống cả hai để lấy lần lượt toàn bộ khách, xếp theo ngày tạo tăng dần nên khách mới nằm ở cuối và không bị sót khi đang lật trang. Kết quả không có email, cần email thì gọi chi tiết. Mỗi lượt gọi có kết quả được ghi vào nhật ký truy cập dữ liệu của phòng khám, nên chỉ gọi khi thật sự cần./customerscustomers:readTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
q | Truy vấn | string | Tìm theo tên hoặc mã, tối thiểu 2 ký tự. | |
phone | Truy vấn | string | Tìm theo số điện thoại đầy đủ. | |
limit | Truy vấn | integer | Số dòng mỗi trang, từ 1 đến 100. | |
cursor | Truy vấn | string | Giá trị nextCursor của trang trước. Bỏ trống để lấy trang đầu. |
curl -X GET 'https://app.avenix.vn/v1/open/customers' \ -H "Authorization: Bearer $TOKEN"
{ "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "fullName": "Nguyễn Văn An", "dateOfBirth": "2026-11-01", "gender": "male", "phone": "+84901234567", "email": "[email protected]", "province": "TP. Hồ Chí Minh", "ward": "Phường Bến Nghé", "streetAddress": "12 Lê Lợi", "homeBranchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "active", "createdAt": "2026-11-01T09:00:00+07:00", "updatedAt": "2026-11-01T09:00:00+07:00", "externalId": "string", "country": "string", "city": "string", "region": "string", "isVip": true, "referralSourceId": "string", "tags": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Chi nhánh Quận 1" } ], "lastInvoiceAt": "2026-11-01T09:00:00+07:00", "extraPhones": [ "string" ], "ethnicity": "string", "occupation": "string", "occupationCode": "string", "workplace": "string", "bloodGroup": "string", "rhFactor": "string", "patientType": "string", "healthCheckSubject": "string", "emergencyContactName": "string", "emergencyContactRelation": "string", "emergencyContactPhone": "string", "note": "string", "walletBalance": 1, "nationalId": "string", "passportNo": "string", "guardianNationalId": "string", "bhytCode": "string", "bhytRegFacilityCode": "string", "bhytValidFrom": "string", "bhytValidTo": "string" } ], "nextCursor": "string" }
Các trường trả về47
| Tên trường | Kiểu | Mô tả |
|---|---|---|
data | array | Các dòng của trang này. |
data[].id | uuid | Mã khách hàng. |
data[].code | string | Mã ngắn hiện trong phần mềm. |
data[].fullName | string | Họ tên. |
data[].dateOfBirth | dateCó thể trống | Ngày sinh, dạng YYYY-MM-DD. |
data[].gender | enumCó thể trống | Giới tính. Giá trị: malefemaleother |
data[].phone | stringCó thể trống | Số điện thoại chính theo chuẩn E.164, ví dụ +84901234567. |
data[].email | stringCó thể trống | Email. Chỉ có khi xem một khách. |
data[].province | stringCó thể trống | Tỉnh, thành phố. |
data[].ward | stringCó thể trống | Phường, xã. |
data[].streetAddress | stringCó thể trống | Số nhà, tên đường. |
data[].homeBranchId | uuid | Chi nhánh gốc của hồ sơ. |
data[].status | enum | Trạng thái hồ sơ. Giá trị: activemergeddeleted |
data[].createdAt | date-time | Thời điểm tạo hồ sơ. |
data[].updatedAt | date-timeCó thể trống | Thời điểm sửa gần nhất. Chỉ có khi xem một khách. |
data[].externalId | stringCó thể trống | Mã khách phía phần mềm của bạn. |
data[].country | stringCó thể trống | Mã quốc gia ISO của địa chỉ, trống là Việt Nam. |
data[].city | stringCó thể trống | Thành phố, khi khách ở nước ngoài. |
data[].region | stringCó thể trống | Bang hoặc vùng, khi khách ở nước ngoài. |
data[].isVip | boolean | Khách VIP. |
data[].referralSourceId | stringCó thể trống | Nguồn khách theo danh mục của phòng khám. |
data[].tags | array | Thẻ phân loại đang gắn. |
data[].tags[].id | uuid | Mã thẻ. |
data[].tags[].name | string | Tên thẻ. |
data[].lastInvoiceAt | date-timeCó thể trống | Lần lập hoá đơn gần nhất. Cần phạm vi invoices:read. |
data[].extraPhones | array | Các số điện thoại thêm. Chỉ có khi xem một khách. |
data[].ethnicity | stringCó thể trống | Dân tộc. Chỉ có khi xem một khách. |
data[].occupation | stringCó thể trống | Nghề nghiệp. Chỉ có khi xem một khách. |
data[].occupationCode | stringCó thể trống | Mã nghề theo danh mục khám sức khoẻ. Chỉ có khi xem một khách. |
data[].workplace | stringCó thể trống | Nơi làm việc. Chỉ có khi xem một khách. |
data[].bloodGroup | stringCó thể trống | Nhóm máu. Chỉ có khi xem một khách. |
data[].rhFactor | stringCó thể trống | Yếu tố Rh. Chỉ có khi xem một khách. |
data[].patientType | stringCó thể trống | Hình thức khám. Chỉ có khi xem một khách. |
data[].healthCheckSubject | stringCó thể trống | Đối tượng khám sức khoẻ theo danh mục Sở Y tế. Chỉ có khi xem một khách. |
data[].emergencyContactName | stringCó thể trống | Người liên hệ khẩn cấp. Chỉ có khi xem một khách. |
data[].emergencyContactRelation | stringCó thể trống | Quan hệ với khách. Chỉ có khi xem một khách. |
data[].emergencyContactPhone | stringCó thể trống | Số điện thoại người liên hệ. Chỉ có khi xem một khách. |
data[].note | stringCó thể trống | Ghi chú của phòng khám. Chỉ có khi xem một khách. |
data[].walletBalance | integer | Số dư trả trước. Cần phạm vi invoices:read. |
data[].nationalId | stringCó thể trống | Số CCCD hoặc định danh cá nhân. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
data[].passportNo | stringCó thể trống | Số hộ chiếu. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
data[].guardianNationalId | stringCó thể trống | CCCD người giám hộ. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
data[].bhytCode | stringCó thể trống | Số thẻ BHYT. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
data[].bhytRegFacilityCode | stringCó thể trống | Nơi đăng ký khám chữa bệnh ban đầu. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
data[].bhytValidFrom | stringCó thể trống | Thẻ BHYT có hiệu lực từ. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
data[].bhytValidTo | stringCó thể trống | Thẻ BHYT có hiệu lực đến. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
nextCursor | stringCó thể trống | Truyền vào cursor để lấy trang sau, trống là hết. |
Tạo khách hàng
/customerscustomers:writeTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
Idempotency-Key | Header | string | Bắt buộc | Chuỗi ngẫu nhiên cho mỗi việc. Gửi lại cùng khoá trong 24 giờ thì không tạo trùng. |
Nội dung gửi
| Tên trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
fullName | string | Bắt buộc | Họ tên. |
phone | string | Bắt buộc | Số điện thoại. Nhận 0901234567 hoặc +84901234567, trả về dạng E.164. |
homeBranchId | uuid | Bắt buộc | Chi nhánh gốc, phải thuộc các chi nhánh kết nối được cấp. |
dateOfBirth | date | Ngày sinh, dạng YYYY-MM-DD. | |
gender | enum | Giới tính. Giá trị: malefemaleother | |
email | email | Email. | |
province | string | Tỉnh, thành phố. | |
ward | string | Phường, xã. | |
streetAddress | string | Số nhà, tên đường. | |
country | string | Mã quốc gia ISO, ví dụ sg. Bỏ trống là Việt Nam. | |
city | string | Thành phố, bắt buộc khi ở nước ngoài. | |
region | string | Bang hoặc vùng ở nước ngoài. | |
extraPhones | array | Các số điện thoại thêm. Gửi cả bộ. | |
note | string | Ghi chú cho phòng khám. | |
referralSourceId | string | Nguồn khách theo danh mục của phòng khám. | |
isVip | boolean | Khách VIP. | |
ethnicity | string | Dân tộc. | |
occupation | string | Nghề nghiệp. | |
occupationCode | string | Mã nghề theo danh mục khám sức khoẻ. | |
workplace | string | Nơi làm việc. | |
bloodGroup | enum | Nhóm máu. Giá trị: ABABO | |
rhFactor | enum | Yếu tố Rh. Giá trị: +- | |
patientType | enum | Hình thức khám. Giá trị: servicebhythealth_checkfree | |
healthCheckSubject | string | Đối tượng khám sức khoẻ theo danh mục Sở Y tế. | |
emergencyContactName | string | Người liên hệ khẩn cấp. | |
emergencyContactRelation | string | Quan hệ với khách. | |
emergencyContactPhone | string | Số điện thoại người liên hệ. | |
externalId | string | Mã khách phía phần mềm của bạn, không trùng trong một kết nối. | |
nationalId | string | Số CCCD, phải khớp ngày sinh và giới tính. Cần phạm vi customers:identity. | |
passportNo | string | Số hộ chiếu. Cần phạm vi customers:identity. | |
guardianNationalId | string | CCCD người giám hộ. Cần phạm vi customers:identity. | |
bhytCode | string | Số thẻ BHYT. Cần phạm vi customers:identity. | |
bhytRegFacilityCode | string | Nơi đăng ký khám chữa bệnh ban đầu. Cần phạm vi customers:identity. | |
bhytValidFrom | date | Thẻ BHYT có hiệu lực từ. Cần phạm vi customers:identity. | |
bhytValidTo | date | Thẻ BHYT có hiệu lực đến. Cần phạm vi customers:identity. |
curl -X POST 'https://app.avenix.vn/v1/open/customers' \ -H "Authorization: Bearer $TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H 'Content-Type: application/json' \ -d '{"fullName":"Nguyễn Thị An","phone":"0901234567","homeBranchId":"3f2b8c1e-7a4d-4c9b-8e21-5d6f7a8b9c01"}'
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "fullName": "Nguyễn Văn An", "dateOfBirth": "2026-11-01", "gender": "male", "phone": "+84901234567", "email": "[email protected]", "province": "TP. Hồ Chí Minh", "ward": "Phường Bến Nghé", "streetAddress": "12 Lê Lợi", "homeBranchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "active", "createdAt": "2026-11-01T09:00:00+07:00", "updatedAt": "2026-11-01T09:00:00+07:00", "externalId": "string", "country": "string", "city": "string", "region": "string", "isVip": true, "referralSourceId": "string", "tags": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Chi nhánh Quận 1" } ], "lastInvoiceAt": "2026-11-01T09:00:00+07:00", "extraPhones": [ "string" ], "ethnicity": "string", "occupation": "string", "occupationCode": "string", "workplace": "string", "bloodGroup": "string", "rhFactor": "string", "patientType": "string", "healthCheckSubject": "string", "emergencyContactName": "string", "emergencyContactRelation": "string", "emergencyContactPhone": "string", "note": "string", "walletBalance": 1, "nationalId": "string", "passportNo": "string", "guardianNationalId": "string", "bhytCode": "string", "bhytRegFacilityCode": "string", "bhytValidFrom": "string", "bhytValidTo": "string" }
Các trường trả về45
| Tên trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | Mã khách hàng. |
code | string | Mã ngắn hiện trong phần mềm. |
fullName | string | Họ tên. |
dateOfBirth | dateCó thể trống | Ngày sinh, dạng YYYY-MM-DD. |
gender | enumCó thể trống | Giới tính. Giá trị: malefemaleother |
phone | stringCó thể trống | Số điện thoại chính theo chuẩn E.164, ví dụ +84901234567. |
email | stringCó thể trống | Email. Chỉ có khi xem một khách. |
province | stringCó thể trống | Tỉnh, thành phố. |
ward | stringCó thể trống | Phường, xã. |
streetAddress | stringCó thể trống | Số nhà, tên đường. |
homeBranchId | uuid | Chi nhánh gốc của hồ sơ. |
status | enum | Trạng thái hồ sơ. Giá trị: activemergeddeleted |
createdAt | date-time | Thời điểm tạo hồ sơ. |
updatedAt | date-timeCó thể trống | Thời điểm sửa gần nhất. Chỉ có khi xem một khách. |
externalId | stringCó thể trống | Mã khách phía phần mềm của bạn. |
country | stringCó thể trống | Mã quốc gia ISO của địa chỉ, trống là Việt Nam. |
city | stringCó thể trống | Thành phố, khi khách ở nước ngoài. |
region | stringCó thể trống | Bang hoặc vùng, khi khách ở nước ngoài. |
isVip | boolean | Khách VIP. |
referralSourceId | stringCó thể trống | Nguồn khách theo danh mục của phòng khám. |
tags | array | Thẻ phân loại đang gắn. |
tags[].id | uuid | Mã thẻ. |
tags[].name | string | Tên thẻ. |
lastInvoiceAt | date-timeCó thể trống | Lần lập hoá đơn gần nhất. Cần phạm vi invoices:read. |
extraPhones | array | Các số điện thoại thêm. Chỉ có khi xem một khách. |
ethnicity | stringCó thể trống | Dân tộc. Chỉ có khi xem một khách. |
occupation | stringCó thể trống | Nghề nghiệp. Chỉ có khi xem một khách. |
occupationCode | stringCó thể trống | Mã nghề theo danh mục khám sức khoẻ. Chỉ có khi xem một khách. |
workplace | stringCó thể trống | Nơi làm việc. Chỉ có khi xem một khách. |
bloodGroup | stringCó thể trống | Nhóm máu. Chỉ có khi xem một khách. |
rhFactor | stringCó thể trống | Yếu tố Rh. Chỉ có khi xem một khách. |
patientType | stringCó thể trống | Hình thức khám. Chỉ có khi xem một khách. |
healthCheckSubject | stringCó thể trống | Đối tượng khám sức khoẻ theo danh mục Sở Y tế. Chỉ có khi xem một khách. |
emergencyContactName | stringCó thể trống | Người liên hệ khẩn cấp. Chỉ có khi xem một khách. |
emergencyContactRelation | stringCó thể trống | Quan hệ với khách. Chỉ có khi xem một khách. |
emergencyContactPhone | stringCó thể trống | Số điện thoại người liên hệ. Chỉ có khi xem một khách. |
note | stringCó thể trống | Ghi chú của phòng khám. Chỉ có khi xem một khách. |
walletBalance | integer | Số dư trả trước. Cần phạm vi invoices:read. |
nationalId | stringCó thể trống | Số CCCD hoặc định danh cá nhân. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
passportNo | stringCó thể trống | Số hộ chiếu. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
guardianNationalId | stringCó thể trống | CCCD người giám hộ. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytCode | stringCó thể trống | Số thẻ BHYT. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytRegFacilityCode | stringCó thể trống | Nơi đăng ký khám chữa bệnh ban đầu. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytValidFrom | stringCó thể trống | Thẻ BHYT có hiệu lực từ. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytValidTo | stringCó thể trống | Thẻ BHYT có hiệu lực đến. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
Lấy khách hàng theo mã của bạn
externalId lúc tạo hoặc cập nhật khách. Mỗi kết nối có bảng ghép riêng, nên kết nối khác không tra được mã của bạn. Không có mã này trả lỗi 404./customers/by-external-id/{externalId}customers:readTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
externalId | Đường dẫn | string | Bắt buộc | Mã khách phía phần mềm của bạn. |
curl -X GET 'https://app.avenix.vn/v1/open/customers/by-external-id/3fa85f64-5717-4562-b3fc-2c963f66afa6' \ -H "Authorization: Bearer $TOKEN"
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "fullName": "Nguyễn Văn An", "dateOfBirth": "2026-11-01", "gender": "male", "phone": "+84901234567", "email": "[email protected]", "province": "TP. Hồ Chí Minh", "ward": "Phường Bến Nghé", "streetAddress": "12 Lê Lợi", "homeBranchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "active", "createdAt": "2026-11-01T09:00:00+07:00", "updatedAt": "2026-11-01T09:00:00+07:00", "externalId": "string", "country": "string", "city": "string", "region": "string", "isVip": true, "referralSourceId": "string", "tags": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Chi nhánh Quận 1" } ], "lastInvoiceAt": "2026-11-01T09:00:00+07:00", "extraPhones": [ "string" ], "ethnicity": "string", "occupation": "string", "occupationCode": "string", "workplace": "string", "bloodGroup": "string", "rhFactor": "string", "patientType": "string", "healthCheckSubject": "string", "emergencyContactName": "string", "emergencyContactRelation": "string", "emergencyContactPhone": "string", "note": "string", "walletBalance": 1, "nationalId": "string", "passportNo": "string", "guardianNationalId": "string", "bhytCode": "string", "bhytRegFacilityCode": "string", "bhytValidFrom": "string", "bhytValidTo": "string" }
Các trường trả về45
| Tên trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | Mã khách hàng. |
code | string | Mã ngắn hiện trong phần mềm. |
fullName | string | Họ tên. |
dateOfBirth | dateCó thể trống | Ngày sinh, dạng YYYY-MM-DD. |
gender | enumCó thể trống | Giới tính. Giá trị: malefemaleother |
phone | stringCó thể trống | Số điện thoại chính theo chuẩn E.164, ví dụ +84901234567. |
email | stringCó thể trống | Email. Chỉ có khi xem một khách. |
province | stringCó thể trống | Tỉnh, thành phố. |
ward | stringCó thể trống | Phường, xã. |
streetAddress | stringCó thể trống | Số nhà, tên đường. |
homeBranchId | uuid | Chi nhánh gốc của hồ sơ. |
status | enum | Trạng thái hồ sơ. Giá trị: activemergeddeleted |
createdAt | date-time | Thời điểm tạo hồ sơ. |
updatedAt | date-timeCó thể trống | Thời điểm sửa gần nhất. Chỉ có khi xem một khách. |
externalId | stringCó thể trống | Mã khách phía phần mềm của bạn. |
country | stringCó thể trống | Mã quốc gia ISO của địa chỉ, trống là Việt Nam. |
city | stringCó thể trống | Thành phố, khi khách ở nước ngoài. |
region | stringCó thể trống | Bang hoặc vùng, khi khách ở nước ngoài. |
isVip | boolean | Khách VIP. |
referralSourceId | stringCó thể trống | Nguồn khách theo danh mục của phòng khám. |
tags | array | Thẻ phân loại đang gắn. |
tags[].id | uuid | Mã thẻ. |
tags[].name | string | Tên thẻ. |
lastInvoiceAt | date-timeCó thể trống | Lần lập hoá đơn gần nhất. Cần phạm vi invoices:read. |
extraPhones | array | Các số điện thoại thêm. Chỉ có khi xem một khách. |
ethnicity | stringCó thể trống | Dân tộc. Chỉ có khi xem một khách. |
occupation | stringCó thể trống | Nghề nghiệp. Chỉ có khi xem một khách. |
occupationCode | stringCó thể trống | Mã nghề theo danh mục khám sức khoẻ. Chỉ có khi xem một khách. |
workplace | stringCó thể trống | Nơi làm việc. Chỉ có khi xem một khách. |
bloodGroup | stringCó thể trống | Nhóm máu. Chỉ có khi xem một khách. |
rhFactor | stringCó thể trống | Yếu tố Rh. Chỉ có khi xem một khách. |
patientType | stringCó thể trống | Hình thức khám. Chỉ có khi xem một khách. |
healthCheckSubject | stringCó thể trống | Đối tượng khám sức khoẻ theo danh mục Sở Y tế. Chỉ có khi xem một khách. |
emergencyContactName | stringCó thể trống | Người liên hệ khẩn cấp. Chỉ có khi xem một khách. |
emergencyContactRelation | stringCó thể trống | Quan hệ với khách. Chỉ có khi xem một khách. |
emergencyContactPhone | stringCó thể trống | Số điện thoại người liên hệ. Chỉ có khi xem một khách. |
note | stringCó thể trống | Ghi chú của phòng khám. Chỉ có khi xem một khách. |
walletBalance | integer | Số dư trả trước. Cần phạm vi invoices:read. |
nationalId | stringCó thể trống | Số CCCD hoặc định danh cá nhân. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
passportNo | stringCó thể trống | Số hộ chiếu. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
guardianNationalId | stringCó thể trống | CCCD người giám hộ. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytCode | stringCó thể trống | Số thẻ BHYT. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytRegFacilityCode | stringCó thể trống | Nơi đăng ký khám chữa bệnh ban đầu. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytValidFrom | stringCó thể trống | Thẻ BHYT có hiệu lực từ. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytValidTo | stringCó thể trống | Thẻ BHYT có hiệu lực đến. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
Lấy chi tiết khách hàng
customer.updated./customers/{id}customers:readTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
id | Đường dẫn | uuid | Bắt buộc | Mã bản ghi. |
curl -X GET 'https://app.avenix.vn/v1/open/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6' \ -H "Authorization: Bearer $TOKEN"
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "fullName": "Nguyễn Văn An", "dateOfBirth": "2026-11-01", "gender": "male", "phone": "+84901234567", "email": "[email protected]", "province": "TP. Hồ Chí Minh", "ward": "Phường Bến Nghé", "streetAddress": "12 Lê Lợi", "homeBranchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "active", "createdAt": "2026-11-01T09:00:00+07:00", "updatedAt": "2026-11-01T09:00:00+07:00", "externalId": "string", "country": "string", "city": "string", "region": "string", "isVip": true, "referralSourceId": "string", "tags": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Chi nhánh Quận 1" } ], "lastInvoiceAt": "2026-11-01T09:00:00+07:00", "extraPhones": [ "string" ], "ethnicity": "string", "occupation": "string", "occupationCode": "string", "workplace": "string", "bloodGroup": "string", "rhFactor": "string", "patientType": "string", "healthCheckSubject": "string", "emergencyContactName": "string", "emergencyContactRelation": "string", "emergencyContactPhone": "string", "note": "string", "walletBalance": 1, "nationalId": "string", "passportNo": "string", "guardianNationalId": "string", "bhytCode": "string", "bhytRegFacilityCode": "string", "bhytValidFrom": "string", "bhytValidTo": "string" }
Các trường trả về45
| Tên trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | Mã khách hàng. |
code | string | Mã ngắn hiện trong phần mềm. |
fullName | string | Họ tên. |
dateOfBirth | dateCó thể trống | Ngày sinh, dạng YYYY-MM-DD. |
gender | enumCó thể trống | Giới tính. Giá trị: malefemaleother |
phone | stringCó thể trống | Số điện thoại chính theo chuẩn E.164, ví dụ +84901234567. |
email | stringCó thể trống | Email. Chỉ có khi xem một khách. |
province | stringCó thể trống | Tỉnh, thành phố. |
ward | stringCó thể trống | Phường, xã. |
streetAddress | stringCó thể trống | Số nhà, tên đường. |
homeBranchId | uuid | Chi nhánh gốc của hồ sơ. |
status | enum | Trạng thái hồ sơ. Giá trị: activemergeddeleted |
createdAt | date-time | Thời điểm tạo hồ sơ. |
updatedAt | date-timeCó thể trống | Thời điểm sửa gần nhất. Chỉ có khi xem một khách. |
externalId | stringCó thể trống | Mã khách phía phần mềm của bạn. |
country | stringCó thể trống | Mã quốc gia ISO của địa chỉ, trống là Việt Nam. |
city | stringCó thể trống | Thành phố, khi khách ở nước ngoài. |
region | stringCó thể trống | Bang hoặc vùng, khi khách ở nước ngoài. |
isVip | boolean | Khách VIP. |
referralSourceId | stringCó thể trống | Nguồn khách theo danh mục của phòng khám. |
tags | array | Thẻ phân loại đang gắn. |
tags[].id | uuid | Mã thẻ. |
tags[].name | string | Tên thẻ. |
lastInvoiceAt | date-timeCó thể trống | Lần lập hoá đơn gần nhất. Cần phạm vi invoices:read. |
extraPhones | array | Các số điện thoại thêm. Chỉ có khi xem một khách. |
ethnicity | stringCó thể trống | Dân tộc. Chỉ có khi xem một khách. |
occupation | stringCó thể trống | Nghề nghiệp. Chỉ có khi xem một khách. |
occupationCode | stringCó thể trống | Mã nghề theo danh mục khám sức khoẻ. Chỉ có khi xem một khách. |
workplace | stringCó thể trống | Nơi làm việc. Chỉ có khi xem một khách. |
bloodGroup | stringCó thể trống | Nhóm máu. Chỉ có khi xem một khách. |
rhFactor | stringCó thể trống | Yếu tố Rh. Chỉ có khi xem một khách. |
patientType | stringCó thể trống | Hình thức khám. Chỉ có khi xem một khách. |
healthCheckSubject | stringCó thể trống | Đối tượng khám sức khoẻ theo danh mục Sở Y tế. Chỉ có khi xem một khách. |
emergencyContactName | stringCó thể trống | Người liên hệ khẩn cấp. Chỉ có khi xem một khách. |
emergencyContactRelation | stringCó thể trống | Quan hệ với khách. Chỉ có khi xem một khách. |
emergencyContactPhone | stringCó thể trống | Số điện thoại người liên hệ. Chỉ có khi xem một khách. |
note | stringCó thể trống | Ghi chú của phòng khám. Chỉ có khi xem một khách. |
walletBalance | integer | Số dư trả trước. Cần phạm vi invoices:read. |
nationalId | stringCó thể trống | Số CCCD hoặc định danh cá nhân. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
passportNo | stringCó thể trống | Số hộ chiếu. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
guardianNationalId | stringCó thể trống | CCCD người giám hộ. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytCode | stringCó thể trống | Số thẻ BHYT. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytRegFacilityCode | stringCó thể trống | Nơi đăng ký khám chữa bệnh ban đầu. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytValidFrom | stringCó thể trống | Thẻ BHYT có hiệu lực từ. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytValidTo | stringCó thể trống | Thẻ BHYT có hiệu lực đến. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
Cập nhật khách hàng
/customers/{id}customers:writeTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
id | Đường dẫn | uuid | Bắt buộc | Mã bản ghi. |
Nội dung gửi
| Tên trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
fullName | string | Họ tên. | |
phone | string | Số điện thoại. Nhận 0901234567 hoặc +84901234567, trả về dạng E.164. | |
dateOfBirth | date | Ngày sinh, dạng YYYY-MM-DD. | |
gender | enum | Giới tính. Giá trị: malefemaleother | |
email | email | Email. | |
province | string | Tỉnh, thành phố. | |
ward | string | Phường, xã. | |
streetAddress | string | Số nhà, tên đường. | |
country | stringCó thể trống | Mã quốc gia ISO, ví dụ sg. Bỏ trống là Việt Nam. | |
city | stringCó thể trống | Thành phố, bắt buộc khi ở nước ngoài. | |
region | stringCó thể trống | Bang hoặc vùng ở nước ngoài. | |
extraPhones | arrayCó thể trống | Các số điện thoại thêm. Gửi cả bộ. | |
note | stringCó thể trống | Ghi chú cho phòng khám. | |
referralSourceId | stringCó thể trống | Nguồn khách theo danh mục của phòng khám. | |
isVip | booleanCó thể trống | Khách VIP. | |
ethnicity | stringCó thể trống | Dân tộc. | |
occupation | stringCó thể trống | Nghề nghiệp. | |
occupationCode | stringCó thể trống | Mã nghề theo danh mục khám sức khoẻ. | |
workplace | stringCó thể trống | Nơi làm việc. | |
bloodGroup | enumCó thể trống | Nhóm máu. Giá trị: ABABO | |
rhFactor | enumCó thể trống | Yếu tố Rh. Giá trị: +- | |
patientType | enumCó thể trống | Hình thức khám. Giá trị: servicebhythealth_checkfree | |
healthCheckSubject | stringCó thể trống | Đối tượng khám sức khoẻ theo danh mục Sở Y tế. | |
emergencyContactName | stringCó thể trống | Người liên hệ khẩn cấp. | |
emergencyContactRelation | stringCó thể trống | Quan hệ với khách. | |
emergencyContactPhone | stringCó thể trống | Số điện thoại người liên hệ. | |
externalId | stringCó thể trống | Mã khách phía phần mềm của bạn, không trùng trong một kết nối. | |
nationalId | stringCó thể trống | Số CCCD, phải khớp ngày sinh và giới tính. Cần phạm vi customers:identity. | |
passportNo | stringCó thể trống | Số hộ chiếu. Cần phạm vi customers:identity. | |
guardianNationalId | stringCó thể trống | CCCD người giám hộ. Cần phạm vi customers:identity. | |
bhytCode | stringCó thể trống | Số thẻ BHYT. Cần phạm vi customers:identity. | |
bhytRegFacilityCode | stringCó thể trống | Nơi đăng ký khám chữa bệnh ban đầu. Cần phạm vi customers:identity. | |
bhytValidFrom | dateCó thể trống | Thẻ BHYT có hiệu lực từ. Cần phạm vi customers:identity. | |
bhytValidTo | dateCó thể trống | Thẻ BHYT có hiệu lực đến. Cần phạm vi customers:identity. |
curl -X PATCH 'https://app.avenix.vn/v1/open/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"email":"[email protected]"}'
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "fullName": "Nguyễn Văn An", "dateOfBirth": "2026-11-01", "gender": "male", "phone": "+84901234567", "email": "[email protected]", "province": "TP. Hồ Chí Minh", "ward": "Phường Bến Nghé", "streetAddress": "12 Lê Lợi", "homeBranchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "active", "createdAt": "2026-11-01T09:00:00+07:00", "updatedAt": "2026-11-01T09:00:00+07:00", "externalId": "string", "country": "string", "city": "string", "region": "string", "isVip": true, "referralSourceId": "string", "tags": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Chi nhánh Quận 1" } ], "lastInvoiceAt": "2026-11-01T09:00:00+07:00", "extraPhones": [ "string" ], "ethnicity": "string", "occupation": "string", "occupationCode": "string", "workplace": "string", "bloodGroup": "string", "rhFactor": "string", "patientType": "string", "healthCheckSubject": "string", "emergencyContactName": "string", "emergencyContactRelation": "string", "emergencyContactPhone": "string", "note": "string", "walletBalance": 1, "nationalId": "string", "passportNo": "string", "guardianNationalId": "string", "bhytCode": "string", "bhytRegFacilityCode": "string", "bhytValidFrom": "string", "bhytValidTo": "string" }
Các trường trả về45
| Tên trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | Mã khách hàng. |
code | string | Mã ngắn hiện trong phần mềm. |
fullName | string | Họ tên. |
dateOfBirth | dateCó thể trống | Ngày sinh, dạng YYYY-MM-DD. |
gender | enumCó thể trống | Giới tính. Giá trị: malefemaleother |
phone | stringCó thể trống | Số điện thoại chính theo chuẩn E.164, ví dụ +84901234567. |
email | stringCó thể trống | Email. Chỉ có khi xem một khách. |
province | stringCó thể trống | Tỉnh, thành phố. |
ward | stringCó thể trống | Phường, xã. |
streetAddress | stringCó thể trống | Số nhà, tên đường. |
homeBranchId | uuid | Chi nhánh gốc của hồ sơ. |
status | enum | Trạng thái hồ sơ. Giá trị: activemergeddeleted |
createdAt | date-time | Thời điểm tạo hồ sơ. |
updatedAt | date-timeCó thể trống | Thời điểm sửa gần nhất. Chỉ có khi xem một khách. |
externalId | stringCó thể trống | Mã khách phía phần mềm của bạn. |
country | stringCó thể trống | Mã quốc gia ISO của địa chỉ, trống là Việt Nam. |
city | stringCó thể trống | Thành phố, khi khách ở nước ngoài. |
region | stringCó thể trống | Bang hoặc vùng, khi khách ở nước ngoài. |
isVip | boolean | Khách VIP. |
referralSourceId | stringCó thể trống | Nguồn khách theo danh mục của phòng khám. |
tags | array | Thẻ phân loại đang gắn. |
tags[].id | uuid | Mã thẻ. |
tags[].name | string | Tên thẻ. |
lastInvoiceAt | date-timeCó thể trống | Lần lập hoá đơn gần nhất. Cần phạm vi invoices:read. |
extraPhones | array | Các số điện thoại thêm. Chỉ có khi xem một khách. |
ethnicity | stringCó thể trống | Dân tộc. Chỉ có khi xem một khách. |
occupation | stringCó thể trống | Nghề nghiệp. Chỉ có khi xem một khách. |
occupationCode | stringCó thể trống | Mã nghề theo danh mục khám sức khoẻ. Chỉ có khi xem một khách. |
workplace | stringCó thể trống | Nơi làm việc. Chỉ có khi xem một khách. |
bloodGroup | stringCó thể trống | Nhóm máu. Chỉ có khi xem một khách. |
rhFactor | stringCó thể trống | Yếu tố Rh. Chỉ có khi xem một khách. |
patientType | stringCó thể trống | Hình thức khám. Chỉ có khi xem một khách. |
healthCheckSubject | stringCó thể trống | Đối tượng khám sức khoẻ theo danh mục Sở Y tế. Chỉ có khi xem một khách. |
emergencyContactName | stringCó thể trống | Người liên hệ khẩn cấp. Chỉ có khi xem một khách. |
emergencyContactRelation | stringCó thể trống | Quan hệ với khách. Chỉ có khi xem một khách. |
emergencyContactPhone | stringCó thể trống | Số điện thoại người liên hệ. Chỉ có khi xem một khách. |
note | stringCó thể trống | Ghi chú của phòng khám. Chỉ có khi xem một khách. |
walletBalance | integer | Số dư trả trước. Cần phạm vi invoices:read. |
nationalId | stringCó thể trống | Số CCCD hoặc định danh cá nhân. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
passportNo | stringCó thể trống | Số hộ chiếu. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
guardianNationalId | stringCó thể trống | CCCD người giám hộ. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytCode | stringCó thể trống | Số thẻ BHYT. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytRegFacilityCode | stringCó thể trống | Nơi đăng ký khám chữa bệnh ban đầu. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytValidFrom | stringCó thể trống | Thẻ BHYT có hiệu lực từ. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
bhytValidTo | stringCó thể trống | Thẻ BHYT có hiệu lực đến. Chỉ có khi xem một khách và token mang phạm vi customers:identity. |
Lịch hẹn
Xem giờ trống, đặt, đổi và huỷ lịch hẹn. Lịch tạo qua API hiện ngay trên màn Lịch hẹn của phòng khám và đi theo đúng luật giờ làm việc như lịch do lễ tân đặt. Thứ tự thường dùng: chọn chi nhánh và bác sĩ, xem giờ trống, tìm hoặc tạo khách, rồi tạo lịch hẹn.
Dùng khi
- Website hoặc ứng dụng của bạn cho khách tự đặt lịch.
- Hiện lịch sắp tới của khách trong CRM hay tổng đài.
Lấy giờ trống trong ngày
doctorId để xem theo lịch của bác sĩ đó, bỏ trống thì xem theo giờ mở cửa. Ngày phòng khám nghỉ có lý do ở closedReason. Nên gọi route này để hiện giờ cho khách chọn trước khi tạo lịch hẹn./appointments/availabilityappointments:readTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
branchId | Truy vấn | uuid | Bắt buộc | Chi nhánh. |
doctorId | Truy vấn | uuid | Bác sĩ. Bỏ trống để xem theo giờ mở cửa. | |
date | Truy vấn | date | Bắt buộc | Ngày cần xem, dạng YYYY-MM-DD. |
curl -X GET 'https://app.avenix.vn/v1/open/appointments/availability' \ -H "Authorization: Bearer $TOKEN"
{ "date": "2026-11-01", "slotMinutes": 1, "closedReason": "string", "slots": [ { "startsAt": "2026-11-01T09:00:00+07:00", "endsAt": "2026-11-01T09:00:00+07:00", "available": true } ] }
Các trường trả về7
| Tên trường | Kiểu | Mô tả |
|---|---|---|
date | date | Ngày đang xem. |
slotMinutes | integer | Độ dài mỗi ô, tính bằng phút. |
closedReason | stringCó thể trống | Lý do đóng cửa, trống khi ngày đó mở cửa. |
slots | array | Các ô giờ trong ngày. |
slots[].startsAt | date-time | Giờ bắt đầu. |
slots[].endsAt | date-time | Giờ kết thúc. |
slots[].available | boolean | Đặt được hay không. |
Lấy danh sách lịch hẹn
from đến to, tối đa 31 ngày mỗi lượt, có thể lọc theo chi nhánh hoặc theo khách. Route này không phân trang: cần khoảng dài hơn thì gọi nhiều lượt nối tiếp nhau. Muốn biết lịch đổi ngay khi có việc thì dùng webhook thay vì gọi lặp lại./appointmentsappointments:readTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
from | Truy vấn | date-time | Bắt buộc | Từ thời điểm. |
to | Truy vấn | date-time | Bắt buộc | Đến thời điểm, cách from tối đa 31 ngày. |
branchId | Truy vấn | uuid | Chỉ lấy một chi nhánh. | |
customerId | Truy vấn | uuid | Chỉ lấy một khách. |
curl -X GET 'https://app.avenix.vn/v1/open/appointments' \ -H "Authorization: Bearer $TOKEN"
{ "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customerCode": "KH-00012", "customerName": "Nguyễn Văn An", "doctorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "startsAt": "2026-11-01T09:00:00+07:00", "endsAt": "2026-11-01T09:00:00+07:00", "allDay": true, "status": "draft", "createdAt": "2026-11-01T09:00:00+07:00", "kind": "string", "source": "string", "autoCreated": true, "chairId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "assistantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "salesStaffId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "plannedServiceIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "doctorName": "string", "branchName": "string", "chairName": "string", "assistantName": "string", "salesStaffName": "string", "note": "string", "cancelReason": "string", "checkedInAt": "2026-11-01T09:00:00+07:00", "completedAt": "2026-11-01T09:00:00+07:00", "updatedAt": "2026-11-01T09:00:00+07:00" } ] }
Các trường trả về30
| Tên trường | Kiểu | Mô tả |
|---|---|---|
data | array | Các dòng của trang này. |
data[].id | uuid | Mã lịch hẹn. |
data[].code | stringCó thể trống | Mã ngắn hiện trong phần mềm. |
data[].branchId | uuid | Chi nhánh. |
data[].customerId | uuid | Khách hàng. |
data[].customerCode | string | Mã ngắn của khách. |
data[].customerName | string | Họ tên khách. |
data[].doctorId | uuidCó thể trống | Bác sĩ, trống khi chưa chọn. |
data[].startsAt | date-time | Giờ bắt đầu. |
data[].endsAt | date-time | Giờ kết thúc. |
data[].allDay | boolean | Hẹn cả ngày, chưa chốt giờ cụ thể. |
data[].status | enum | Trạng thái lịch hẹn. Giá trị: draftbookedconfirmedchecked_inin_progresscompletedcancelledno_show |
data[].createdAt | date-time | Thời điểm tạo. |
data[].kind | string | Loại hẹn: hẹn thường, tái khám hay tiêm chủng. |
data[].source | string | Nơi tạo lịch, ví dụ đặt online. |
data[].autoCreated | boolean | Lịch do phần mềm tự tạo từ mốc tái khám hoặc mũi tiêm. |
data[].chairId | uuidCó thể trống | Ghế hoặc phòng đã giữ. |
data[].assistantId | uuidCó thể trống | Phụ tá. |
data[].salesStaffId | uuidCó thể trống | Nhân viên kinh doanh. |
data[].plannedServiceIds | array | Các dịch vụ dự kiến làm. |
data[].doctorName | stringCó thể trống | Tên bác sĩ. Chỉ có khi xem một lịch. |
data[].branchName | stringCó thể trống | Tên chi nhánh. Chỉ có khi xem một lịch. |
data[].chairName | stringCó thể trống | Tên ghế hoặc phòng. Chỉ có khi xem một lịch. |
data[].assistantName | stringCó thể trống | Tên phụ tá. Chỉ có khi xem một lịch. |
data[].salesStaffName | stringCó thể trống | Tên nhân viên kinh doanh. Chỉ có khi xem một lịch. |
data[].note | stringCó thể trống | Ghi chú. Chỉ có khi xem một lịch. |
data[].cancelReason | stringCó thể trống | Lý do huỷ. Chỉ có khi xem một lịch. |
data[].checkedInAt | date-timeCó thể trống | Lúc khách đến. Chỉ có khi xem một lịch. |
data[].completedAt | date-timeCó thể trống | Lúc hoàn tất. Chỉ có khi xem một lịch. |
data[].updatedAt | date-timeCó thể trống | Lúc sửa gần nhất. Chỉ có khi xem một lịch. |
Tạo lịch hẹn
/appointmentsappointments:writeTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
Idempotency-Key | Header | string | Bắt buộc | Chuỗi ngẫu nhiên cho mỗi việc. Gửi lại cùng khoá trong 24 giờ thì không tạo trùng. |
Nội dung gửi
| Tên trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
branchId | uuid | Bắt buộc | Chi nhánh, phải thuộc các chi nhánh kết nối được cấp. |
customerId | uuid | Bắt buộc | Khách hàng. |
doctorId | uuid | Bác sĩ. | |
startsAt | date-time | Bắt buộc | Giờ bắt đầu. |
endsAt | date-time | Bắt buộc | Giờ kết thúc. |
note | string | Ghi chú cho phòng khám. | |
chairId | uuid | Ghế hoặc phòng giữ cho ca. | |
assistantId | uuid | Phụ tá. | |
salesStaffId | uuid | Nhân viên kinh doanh. | |
plannedServiceIds | array | Các dịch vụ dự kiến làm, mã id ở danh sách dịch vụ. |
curl -X POST 'https://app.avenix.vn/v1/open/appointments' \ -H "Authorization: Bearer $TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H 'Content-Type: application/json' \ -d '{"branchId":"3f2b8c1e-7a4d-4c9b-8e21-5d6f7a8b9c01","customerId":"8a1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d5e","startsAt":"2026-12-01T09:00:00+07:00","endsAt":"2026-12-01T09:30:00+07:00"}'
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customerCode": "KH-00012", "customerName": "Nguyễn Văn An", "doctorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "startsAt": "2026-11-01T09:00:00+07:00", "endsAt": "2026-11-01T09:00:00+07:00", "allDay": true, "status": "draft", "createdAt": "2026-11-01T09:00:00+07:00", "kind": "string", "source": "string", "autoCreated": true, "chairId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "assistantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "salesStaffId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "plannedServiceIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "doctorName": "string", "branchName": "string", "chairName": "string", "assistantName": "string", "salesStaffName": "string", "note": "string", "cancelReason": "string", "checkedInAt": "2026-11-01T09:00:00+07:00", "completedAt": "2026-11-01T09:00:00+07:00", "updatedAt": "2026-11-01T09:00:00+07:00" }
Các trường trả về29
| Tên trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | Mã lịch hẹn. |
code | stringCó thể trống | Mã ngắn hiện trong phần mềm. |
branchId | uuid | Chi nhánh. |
customerId | uuid | Khách hàng. |
customerCode | string | Mã ngắn của khách. |
customerName | string | Họ tên khách. |
doctorId | uuidCó thể trống | Bác sĩ, trống khi chưa chọn. |
startsAt | date-time | Giờ bắt đầu. |
endsAt | date-time | Giờ kết thúc. |
allDay | boolean | Hẹn cả ngày, chưa chốt giờ cụ thể. |
status | enum | Trạng thái lịch hẹn. Giá trị: draftbookedconfirmedchecked_inin_progresscompletedcancelledno_show |
createdAt | date-time | Thời điểm tạo. |
kind | string | Loại hẹn: hẹn thường, tái khám hay tiêm chủng. |
source | string | Nơi tạo lịch, ví dụ đặt online. |
autoCreated | boolean | Lịch do phần mềm tự tạo từ mốc tái khám hoặc mũi tiêm. |
chairId | uuidCó thể trống | Ghế hoặc phòng đã giữ. |
assistantId | uuidCó thể trống | Phụ tá. |
salesStaffId | uuidCó thể trống | Nhân viên kinh doanh. |
plannedServiceIds | array | Các dịch vụ dự kiến làm. |
doctorName | stringCó thể trống | Tên bác sĩ. Chỉ có khi xem một lịch. |
branchName | stringCó thể trống | Tên chi nhánh. Chỉ có khi xem một lịch. |
chairName | stringCó thể trống | Tên ghế hoặc phòng. Chỉ có khi xem một lịch. |
assistantName | stringCó thể trống | Tên phụ tá. Chỉ có khi xem một lịch. |
salesStaffName | stringCó thể trống | Tên nhân viên kinh doanh. Chỉ có khi xem một lịch. |
note | stringCó thể trống | Ghi chú. Chỉ có khi xem một lịch. |
cancelReason | stringCó thể trống | Lý do huỷ. Chỉ có khi xem một lịch. |
checkedInAt | date-timeCó thể trống | Lúc khách đến. Chỉ có khi xem một lịch. |
completedAt | date-timeCó thể trống | Lúc hoàn tất. Chỉ có khi xem một lịch. |
updatedAt | date-timeCó thể trống | Lúc sửa gần nhất. Chỉ có khi xem một lịch. |
Lấy chi tiết lịch hẹn
appointment.updated hoặc appointment.status_changed./appointments/{id}appointments:readTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
id | Đường dẫn | uuid | Bắt buộc | Mã bản ghi. |
curl -X GET 'https://app.avenix.vn/v1/open/appointments/3fa85f64-5717-4562-b3fc-2c963f66afa6' \ -H "Authorization: Bearer $TOKEN"
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customerCode": "KH-00012", "customerName": "Nguyễn Văn An", "doctorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "startsAt": "2026-11-01T09:00:00+07:00", "endsAt": "2026-11-01T09:00:00+07:00", "allDay": true, "status": "draft", "createdAt": "2026-11-01T09:00:00+07:00", "kind": "string", "source": "string", "autoCreated": true, "chairId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "assistantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "salesStaffId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "plannedServiceIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "doctorName": "string", "branchName": "string", "chairName": "string", "assistantName": "string", "salesStaffName": "string", "note": "string", "cancelReason": "string", "checkedInAt": "2026-11-01T09:00:00+07:00", "completedAt": "2026-11-01T09:00:00+07:00", "updatedAt": "2026-11-01T09:00:00+07:00" }
Các trường trả về29
| Tên trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | Mã lịch hẹn. |
code | stringCó thể trống | Mã ngắn hiện trong phần mềm. |
branchId | uuid | Chi nhánh. |
customerId | uuid | Khách hàng. |
customerCode | string | Mã ngắn của khách. |
customerName | string | Họ tên khách. |
doctorId | uuidCó thể trống | Bác sĩ, trống khi chưa chọn. |
startsAt | date-time | Giờ bắt đầu. |
endsAt | date-time | Giờ kết thúc. |
allDay | boolean | Hẹn cả ngày, chưa chốt giờ cụ thể. |
status | enum | Trạng thái lịch hẹn. Giá trị: draftbookedconfirmedchecked_inin_progresscompletedcancelledno_show |
createdAt | date-time | Thời điểm tạo. |
kind | string | Loại hẹn: hẹn thường, tái khám hay tiêm chủng. |
source | string | Nơi tạo lịch, ví dụ đặt online. |
autoCreated | boolean | Lịch do phần mềm tự tạo từ mốc tái khám hoặc mũi tiêm. |
chairId | uuidCó thể trống | Ghế hoặc phòng đã giữ. |
assistantId | uuidCó thể trống | Phụ tá. |
salesStaffId | uuidCó thể trống | Nhân viên kinh doanh. |
plannedServiceIds | array | Các dịch vụ dự kiến làm. |
doctorName | stringCó thể trống | Tên bác sĩ. Chỉ có khi xem một lịch. |
branchName | stringCó thể trống | Tên chi nhánh. Chỉ có khi xem một lịch. |
chairName | stringCó thể trống | Tên ghế hoặc phòng. Chỉ có khi xem một lịch. |
assistantName | stringCó thể trống | Tên phụ tá. Chỉ có khi xem một lịch. |
salesStaffName | stringCó thể trống | Tên nhân viên kinh doanh. Chỉ có khi xem một lịch. |
note | stringCó thể trống | Ghi chú. Chỉ có khi xem một lịch. |
cancelReason | stringCó thể trống | Lý do huỷ. Chỉ có khi xem một lịch. |
checkedInAt | date-timeCó thể trống | Lúc khách đến. Chỉ có khi xem một lịch. |
completedAt | date-timeCó thể trống | Lúc hoàn tất. Chỉ có khi xem một lịch. |
updatedAt | date-timeCó thể trống | Lúc sửa gần nhất. Chỉ có khi xem một lịch. |
Cập nhật lịch hẹn
/appointments/{id}appointments:writeTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
id | Đường dẫn | uuid | Bắt buộc | Mã bản ghi. |
Nội dung gửi
| Tên trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
startsAt | date-time | Bắt buộc | Giờ bắt đầu mới. |
endsAt | date-time | Bắt buộc | Giờ kết thúc mới. |
doctorId | uuid | Bác sĩ mới. | |
chairId | uuidCó thể trống | Ghế hoặc phòng, trống là bỏ. | |
note | stringCó thể trống | Ghi chú, trống là xoá. | |
assistantId | uuidCó thể trống | Phụ tá, trống là bỏ. | |
salesStaffId | uuidCó thể trống | Nhân viên kinh doanh, trống là bỏ. | |
plannedServiceIds | array | Các dịch vụ dự kiến làm. Gửi cả bộ. |
curl -X PATCH 'https://app.avenix.vn/v1/open/appointments/3fa85f64-5717-4562-b3fc-2c963f66afa6' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"startsAt":"2026-12-01T10:00:00+07:00","endsAt":"2026-12-01T10:30:00+07:00"}'
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customerCode": "KH-00012", "customerName": "Nguyễn Văn An", "doctorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "startsAt": "2026-11-01T09:00:00+07:00", "endsAt": "2026-11-01T09:00:00+07:00", "allDay": true, "status": "draft", "createdAt": "2026-11-01T09:00:00+07:00", "kind": "string", "source": "string", "autoCreated": true, "chairId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "assistantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "salesStaffId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "plannedServiceIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "doctorName": "string", "branchName": "string", "chairName": "string", "assistantName": "string", "salesStaffName": "string", "note": "string", "cancelReason": "string", "checkedInAt": "2026-11-01T09:00:00+07:00", "completedAt": "2026-11-01T09:00:00+07:00", "updatedAt": "2026-11-01T09:00:00+07:00" }
Các trường trả về29
| Tên trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | Mã lịch hẹn. |
code | stringCó thể trống | Mã ngắn hiện trong phần mềm. |
branchId | uuid | Chi nhánh. |
customerId | uuid | Khách hàng. |
customerCode | string | Mã ngắn của khách. |
customerName | string | Họ tên khách. |
doctorId | uuidCó thể trống | Bác sĩ, trống khi chưa chọn. |
startsAt | date-time | Giờ bắt đầu. |
endsAt | date-time | Giờ kết thúc. |
allDay | boolean | Hẹn cả ngày, chưa chốt giờ cụ thể. |
status | enum | Trạng thái lịch hẹn. Giá trị: draftbookedconfirmedchecked_inin_progresscompletedcancelledno_show |
createdAt | date-time | Thời điểm tạo. |
kind | string | Loại hẹn: hẹn thường, tái khám hay tiêm chủng. |
source | string | Nơi tạo lịch, ví dụ đặt online. |
autoCreated | boolean | Lịch do phần mềm tự tạo từ mốc tái khám hoặc mũi tiêm. |
chairId | uuidCó thể trống | Ghế hoặc phòng đã giữ. |
assistantId | uuidCó thể trống | Phụ tá. |
salesStaffId | uuidCó thể trống | Nhân viên kinh doanh. |
plannedServiceIds | array | Các dịch vụ dự kiến làm. |
doctorName | stringCó thể trống | Tên bác sĩ. Chỉ có khi xem một lịch. |
branchName | stringCó thể trống | Tên chi nhánh. Chỉ có khi xem một lịch. |
chairName | stringCó thể trống | Tên ghế hoặc phòng. Chỉ có khi xem một lịch. |
assistantName | stringCó thể trống | Tên phụ tá. Chỉ có khi xem một lịch. |
salesStaffName | stringCó thể trống | Tên nhân viên kinh doanh. Chỉ có khi xem một lịch. |
note | stringCó thể trống | Ghi chú. Chỉ có khi xem một lịch. |
cancelReason | stringCó thể trống | Lý do huỷ. Chỉ có khi xem một lịch. |
checkedInAt | date-timeCó thể trống | Lúc khách đến. Chỉ có khi xem một lịch. |
completedAt | date-timeCó thể trống | Lúc hoàn tất. Chỉ có khi xem một lịch. |
updatedAt | date-timeCó thể trống | Lúc sửa gần nhất. Chỉ có khi xem một lịch. |
Huỷ lịch hẹn
/appointments/{id}/cancelappointments:writeTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
id | Đường dẫn | uuid | Bắt buộc | Mã bản ghi. |
Nội dung gửi
| Tên trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
reason | string | Lý do huỷ, tối thiểu 10 ký tự. |
curl -X POST 'https://app.avenix.vn/v1/open/appointments/3fa85f64-5717-4562-b3fc-2c963f66afa6/cancel' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"reason":"Khách báo đổi kế hoạch"}'
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customerCode": "KH-00012", "customerName": "Nguyễn Văn An", "doctorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "startsAt": "2026-11-01T09:00:00+07:00", "endsAt": "2026-11-01T09:00:00+07:00", "allDay": true, "status": "draft", "createdAt": "2026-11-01T09:00:00+07:00", "kind": "string", "source": "string", "autoCreated": true, "chairId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "assistantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "salesStaffId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "plannedServiceIds": [ "3fa85f64-5717-4562-b3fc-2c963f66afa6" ], "doctorName": "string", "branchName": "string", "chairName": "string", "assistantName": "string", "salesStaffName": "string", "note": "string", "cancelReason": "string", "checkedInAt": "2026-11-01T09:00:00+07:00", "completedAt": "2026-11-01T09:00:00+07:00", "updatedAt": "2026-11-01T09:00:00+07:00" }
Các trường trả về29
| Tên trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | Mã lịch hẹn. |
code | stringCó thể trống | Mã ngắn hiện trong phần mềm. |
branchId | uuid | Chi nhánh. |
customerId | uuid | Khách hàng. |
customerCode | string | Mã ngắn của khách. |
customerName | string | Họ tên khách. |
doctorId | uuidCó thể trống | Bác sĩ, trống khi chưa chọn. |
startsAt | date-time | Giờ bắt đầu. |
endsAt | date-time | Giờ kết thúc. |
allDay | boolean | Hẹn cả ngày, chưa chốt giờ cụ thể. |
status | enum | Trạng thái lịch hẹn. Giá trị: draftbookedconfirmedchecked_inin_progresscompletedcancelledno_show |
createdAt | date-time | Thời điểm tạo. |
kind | string | Loại hẹn: hẹn thường, tái khám hay tiêm chủng. |
source | string | Nơi tạo lịch, ví dụ đặt online. |
autoCreated | boolean | Lịch do phần mềm tự tạo từ mốc tái khám hoặc mũi tiêm. |
chairId | uuidCó thể trống | Ghế hoặc phòng đã giữ. |
assistantId | uuidCó thể trống | Phụ tá. |
salesStaffId | uuidCó thể trống | Nhân viên kinh doanh. |
plannedServiceIds | array | Các dịch vụ dự kiến làm. |
doctorName | stringCó thể trống | Tên bác sĩ. Chỉ có khi xem một lịch. |
branchName | stringCó thể trống | Tên chi nhánh. Chỉ có khi xem một lịch. |
chairName | stringCó thể trống | Tên ghế hoặc phòng. Chỉ có khi xem một lịch. |
assistantName | stringCó thể trống | Tên phụ tá. Chỉ có khi xem một lịch. |
salesStaffName | stringCó thể trống | Tên nhân viên kinh doanh. Chỉ có khi xem một lịch. |
note | stringCó thể trống | Ghi chú. Chỉ có khi xem một lịch. |
cancelReason | stringCó thể trống | Lý do huỷ. Chỉ có khi xem một lịch. |
checkedInAt | date-timeCó thể trống | Lúc khách đến. Chỉ có khi xem một lịch. |
completedAt | date-timeCó thể trống | Lúc hoàn tất. Chỉ có khi xem một lịch. |
updatedAt | date-timeCó thể trống | Lúc sửa gần nhất. Chỉ có khi xem một lịch. |
Cơ hội
Đẩy khách tiềm năng từ form, landing page hay chiến dịch quảng cáo vào phễu bán hàng của phòng khám. Khác với tạo khách hàng, route này không cần chọn chi nhánh và không tạo hồ sơ khám: đội tư vấn nhận cơ hội ở màn Cơ hội rồi tự liên hệ.
Dùng khi
- Khách để lại số trên landing page chạy quảng cáo.
- Chuyển khách từ phần mềm CRM hoặc tổng đài bên ngoài sang đội tư vấn của phòng khám.
Tạo cơ hội
source được ghi vào ghi chú đầu tiên của cơ hội. Mỗi lượt gọi là một cơ hội mới, kể cả cùng số điện thoại; gửi lại do đứt mạng thì dùng cùng Idempotency-Key để không tạo trùng./leadsleads:writeTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
Idempotency-Key | Header | string | Bắt buộc | Chuỗi ngẫu nhiên cho mỗi việc. Gửi lại cùng khoá trong 24 giờ thì không tạo trùng. |
Nội dung gửi
| Tên trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
fullName | string | Bắt buộc | Họ tên khách. |
phone | string | Bắt buộc | Số điện thoại khách. |
note | string | Nội dung khách để lại. | |
source | string | Nguồn khách, ví dụ tên landing page. | |
expectedRevenue | integer | Doanh thu dự kiến, tính bằng đồng. | |
expectedClosingDate | date | Ngày dự kiến chốt, dạng YYYY-MM-DD. | |
customerId | uuid | Gắn cơ hội với hồ sơ khách đã có. |
curl -X POST 'https://app.avenix.vn/v1/open/leads' \ -H "Authorization: Bearer $TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H 'Content-Type: application/json' \ -d '{"fullName":"Trần Văn Bình","phone":"0912345678","source":"Landing tẩy trắng"}'
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012" }
Các trường trả về2
| Tên trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | Mã cơ hội. |
code | stringCó thể trống | Mã ngắn hiện trong phần mềm. |
Dịch vụ và hàng hoá
Đọc dịch vụ, hàng hoá đang bán kèm danh mục nhóm, hãng sản xuất và nhà cung cấp, chỉ đọc. Giá vốn chỉ trả khi kết nối có phạm vi catalog:cost, số tồn kho không có trong API, nên bản mặc định an toàn để đưa ra website. Mã dịch vụ, mã hàng hoá ở đây cũng là mã trên dòng hoá đơn, nên dùng được để ghép dữ liệu với phần mềm kế toán.
Dùng khi
- Hiện bảng giá trên website của phòng khám, giá tự theo phần mềm.
- Ghép danh mục hàng với phần mềm kế toán hoặc bán hàng.
Lấy danh sách dịch vụ
catalog:cost. Dùng để hiện bảng giá trên website hoặc ghép mã dịch vụ với phần mềm của bạn. priceIncludesVat cho biết giá đã gồm VAT hay chưa./servicescatalog:readTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
q | Truy vấn | string | Tìm theo tên hoặc mã. | |
limit | Truy vấn | integer | Số dòng mỗi trang, từ 1 đến 100. | |
cursor | Truy vấn | string | Giá trị nextCursor của trang trước. Bỏ trống để lấy trang đầu. | |
category | Truy vấn | string | Chỉ lấy một nhóm, mã key ở danh sách nhóm dịch vụ. |
curl -X GET 'https://app.avenix.vn/v1/open/services' \ -H "Authorization: Bearer $TOKEN"
{ "data": [ { "code": "KH-00012", "name": "Chi nhánh Quận 1", "category": "string", "unit": "string", "price": 1, "durationMinutes": 1, "vatRate": 1, "priceIncludesVat": true, "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "barcode": "string", "imageUrl": "string", "technicalCodes": [ "string" ], "eInvoiceName": "string", "sessionCount": 1, "sessionIntervalDays": 1, "sessionNames": [ "string" ], "isWarrantable": true, "warrantyMonths": 1, "warrantyPolicy": "string", "costPrice": 1, "labCost": 1 } ], "nextCursor": "string" }
Các trường trả về23
| Tên trường | Kiểu | Mô tả |
|---|---|---|
data | array | Các dòng của trang này. |
data[].code | string | Mã dịch vụ. |
data[].name | string | Tên dịch vụ. |
data[].category | string | Nhóm dịch vụ. |
data[].unit | string | Đơn vị tính. |
data[].price | integer | Giá bán, tính bằng đồng. |
data[].durationMinutes | integer | Thời lượng dự kiến, tính bằng phút. |
data[].vatRate | integer | Thuế suất VAT, tính bằng phần trăm. |
data[].priceIncludesVat | boolean | Giá bán đã gồm VAT hay chưa. |
data[].id | uuid | Mã bản ghi, dùng cho plannedServiceIds của lịch hẹn. |
data[].barcode | stringCó thể trống | Mã vạch. |
data[].imageUrl | stringCó thể trống | Đường dẫn ảnh. |
data[].technicalCodes | array | Các mã dịch vụ kỹ thuật. |
data[].eInvoiceName | stringCó thể trống | Tên in trên hoá đơn điện tử, trống là theo tên dịch vụ. |
data[].sessionCount | integerCó thể trống | Số bước tiến trình. |
data[].sessionIntervalDays | integerCó thể trống | Số ngày giữa hai bước. |
data[].sessionNames | arrayCó thể trống | Tên từng bước. |
data[].isWarrantable | boolean | Có bảo hành. |
data[].warrantyMonths | integerCó thể trống | Số tháng bảo hành. |
data[].warrantyPolicy | stringCó thể trống | Chính sách bảo hành. |
data[].costPrice | integer | Giá vốn. Cần phạm vi catalog:cost. |
data[].labCost | integerCó thể trống | Giá labo. Cần phạm vi catalog:cost. |
nextCursor | stringCó thể trống | Truyền vào cursor để lấy trang sau, trống là hết. |
Lấy danh sách hàng hoá
catalog:cost. Không có số tồn kho. Hàng có biến thể trả từng biến thể thành một dòng riêng, parentId cho biết chúng cùng một hàng gốc, variantAttribute1 và variantOption1 cho biết thuộc tính, ví dụ Màu: Đỏ. Lọc được theo loại, nhóm và hãng./productscatalog:readTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
q | Truy vấn | string | Tìm theo tên hoặc mã. | |
limit | Truy vấn | integer | Số dòng mỗi trang, từ 1 đến 100. | |
cursor | Truy vấn | string | Giá trị nextCursor của trang trước. Bỏ trống để lấy trang đầu. | |
category | Truy vấn | enum | Chỉ lấy một loại hàng. Giá trị: productconsumablevaccinemedication | |
groupId | Truy vấn | uuid | Chỉ lấy một nhóm hàng. | |
manufacturerId | Truy vấn | uuid | Chỉ lấy một hãng. |
curl -X GET 'https://app.avenix.vn/v1/open/products' \ -H "Authorization: Bearer $TOKEN"
{ "data": [ { "code": "KH-00012", "name": "Chi nhánh Quận 1", "category": "string", "groupName": "string", "manufacturerName": "string", "unit": "string", "salePrice": 1, "secondaryUnit": "string", "secondaryPrice": 1, "units": [ { "name": "Chi nhánh Quận 1", "ratio": 1, "divide": true, "salePrice": 1, "autoApply": true, "barcode": "string" } ], "barcode": "string", "vatRate": 1, "priceIncludesVat": true, "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "groupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "manufacturerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "parentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "variantAttribute1": "string", "variantAttribute2": "string", "lastSupplierId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "lastSupplierName": "string", "imageUrl": "string", "conversionRatio": 1, "minStockAlert": 1, "trackExpiryDate": true, "description": "string", "dosage": "string", "usageInstructions": "string", "activeIngredient": "string", "route": "string", "nationalDrugCode": "string", "registrationNumber": "string", "parentCode": "string", "parentName": "string", "variantOption1": "string", "variantOption2": "string", "isWarrantable": true, "warrantyMonths": 1, "warrantyPolicy": "string", "costPrice": 1 } ], "nextCursor": "string" }
Các trường trả về48
| Tên trường | Kiểu | Mô tả |
|---|---|---|
data | array | Các dòng của trang này. |
data[].code | string | Mã hàng hoá. |
data[].name | string | Tên hàng hoá. |
data[].category | string | Loại hàng. |
data[].groupName | stringCó thể trống | Nhóm hàng. |
data[].manufacturerName | stringCó thể trống | Hãng sản xuất. |
data[].unit | string | Đơn vị tính. |
data[].salePrice | integer | Giá bán, tính bằng đồng. |
data[].secondaryUnit | stringCó thể trống | Đơn vị thứ hai, ví dụ Hộp. |
data[].secondaryPrice | integerCó thể trống | Giá bán theo đơn vị thứ hai. |
data[].units | array | Các đơn vị quy đổi, ví dụ Bộ 6 gói. ratio là số đơn vị cơ bản trong một đơn vị (chiều chia: số đơn vị này trong một đơn vị cơ bản), salePrice là giá một đơn vị, autoApply là tự tính theo đơn vị này khi khách mua đủ số lượng. |
data[].units[].name | string | |
data[].units[].ratio | integer | |
data[].units[].divide | boolean | |
data[].units[].salePrice | integer | |
data[].units[].autoApply | boolean | |
data[].units[].barcode | stringCó thể trống | |
data[].barcode | stringCó thể trống | Mã vạch. |
data[].vatRate | integer | Thuế suất VAT, tính bằng phần trăm. |
data[].priceIncludesVat | boolean | Giá bán đã gồm VAT hay chưa. |
data[].id | uuid | Mã bản ghi. |
data[].groupId | uuidCó thể trống | Nhóm hàng. |
data[].manufacturerId | uuidCó thể trống | Hãng sản xuất. |
data[].parentId | uuidCó thể trống | Hàng gốc, khi dòng này là biến thể. |
data[].variantAttribute1 | stringCó thể trống | Tên thuộc tính thứ nhất của biến thể, ví dụ Màu. |
data[].variantAttribute2 | stringCó thể trống | Tên thuộc tính thứ hai của biến thể, ví dụ Size. |
data[].lastSupplierId | uuidCó thể trống | Nhà cung cấp của lần nhập gần nhất. Cần phạm vi suppliers:read. |
data[].lastSupplierName | stringCó thể trống | Tên nhà cung cấp của lần nhập gần nhất. Cần phạm vi suppliers:read. |
data[].imageUrl | stringCó thể trống | Đường dẫn ảnh. |
data[].conversionRatio | integer | Số đơn vị cơ bản trong một đơn vị thứ hai. |
data[].minStockAlert | integer | Mức cảnh báo tồn tối thiểu. |
data[].trackExpiryDate | boolean | Có theo dõi hạn dùng. |
data[].description | stringCó thể trống | Mô tả. |
data[].dosage | stringCó thể trống | Hàm lượng. |
data[].usageInstructions | stringCó thể trống | Hướng dẫn sử dụng. |
data[].activeIngredient | stringCó thể trống | Hoạt chất. |
data[].route | stringCó thể trống | Đường dùng. |
data[].nationalDrugCode | stringCó thể trống | Mã thuốc quốc gia. |
data[].registrationNumber | stringCó thể trống | Số đăng ký. |
data[].parentCode | stringCó thể trống | Mã hàng gốc, khi dòng này là biến thể. |
data[].parentName | stringCó thể trống | Tên hàng gốc. |
data[].variantOption1 | stringCó thể trống | Giá trị thuộc tính thứ nhất của biến thể. |
data[].variantOption2 | stringCó thể trống | Giá trị thuộc tính thứ hai của biến thể. |
data[].isWarrantable | boolean | Có bảo hành. |
data[].warrantyMonths | integerCó thể trống | Số tháng bảo hành. |
data[].warrantyPolicy | stringCó thể trống | Chính sách bảo hành. |
data[].costPrice | integer | Giá vốn. Cần phạm vi catalog:cost. |
nextCursor | stringCó thể trống | Truyền vào cursor để lấy trang sau, trống là hết. |
Lấy danh mục nhóm dịch vụ
key để lọc danh sách dịch vụ qua tham số category, hoặc để dựng cây danh mục trên website./service-categoriescatalog:readcurl -X GET 'https://app.avenix.vn/v1/open/service-categories' \ -H "Authorization: Bearer $TOKEN"
{ "data": [ { "key": "string", "name": "Chi nhánh Quận 1" } ] }
Các trường trả về3
| Tên trường | Kiểu | Mô tả |
|---|---|---|
data | array | Các dòng của trang này. |
data[].key | string | Mã nhóm, trùng trường category của dịch vụ. |
data[].name | string | Tên nhóm do phòng khám đặt. |
Lấy danh mục nhóm hàng hoá
id để lọc danh sách hàng hoá qua tham số groupId./product-groupscatalog:readcurl -X GET 'https://app.avenix.vn/v1/open/product-groups' \ -H "Authorization: Bearer $TOKEN"
{ "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "name": "Chi nhánh Quận 1", "category": "string", "description": "string" } ] }
Các trường trả về6
| Tên trường | Kiểu | Mô tả |
|---|---|---|
data | array | Các dòng của trang này. |
data[].id | uuid | Mã nhóm hàng, trùng trường groupId của hàng hoá. |
data[].code | string | Mã ngắn của nhóm. |
data[].name | string | Tên nhóm. |
data[].category | string | Loại hàng của nhóm. |
data[].description | stringCó thể trống | Mô tả. |
Lấy danh sách hãng sản xuất
id để lọc danh sách hàng hoá qua tham số manufacturerId./manufacturerscatalog:readcurl -X GET 'https://app.avenix.vn/v1/open/manufacturers' \ -H "Authorization: Bearer $TOKEN"
{ "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Chi nhánh Quận 1", "country": "string", "logoUrl": "string" } ] }
Các trường trả về5
| Tên trường | Kiểu | Mô tả |
|---|---|---|
data | array | Các dòng của trang này. |
data[].id | uuid | Mã hãng, trùng trường manufacturerId của hàng hoá. |
data[].name | string | Tên hãng. |
data[].country | stringCó thể trống | Quốc gia. |
data[].logoUrl | stringCó thể trống | Đường dẫn logo. |
Lấy danh sách nhà cung cấp
lastSupplierId ở danh sách hàng hoá, là nhà cung cấp của lần nhập gần nhất. Không có công nợ nhà cung cấp./supplierssuppliers:readTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
q | Truy vấn | string | Tìm theo tên, mã số thuế hoặc mã. | |
limit | Truy vấn | integer | Số dòng mỗi trang, từ 1 đến 100. | |
cursor | Truy vấn | string | Giá trị nextCursor của trang trước. Bỏ trống để lấy trang đầu. |
curl -X GET 'https://app.avenix.vn/v1/open/suppliers' \ -H "Authorization: Bearer $TOKEN"
{ "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "name": "Chi nhánh Quận 1", "taxCode": "string", "phone": "+84901234567", "email": "[email protected]", "province": "TP. Hồ Chí Minh", "ward": "Phường Bến Nghé", "streetAddress": "12 Lê Lợi", "contactPerson": "string", "note": "string" } ], "nextCursor": "string" }
Các trường trả về13
| Tên trường | Kiểu | Mô tả |
|---|---|---|
data | array | Các dòng của trang này. |
data[].id | uuid | Mã nhà cung cấp. |
data[].code | string | Mã ngắn hiện trong phần mềm. |
data[].name | string | Tên nhà cung cấp. |
data[].taxCode | stringCó thể trống | Mã số thuế. |
data[].phone | stringCó thể trống | Số điện thoại. |
data[].email | stringCó thể trống | Email. |
data[].province | stringCó thể trống | Tỉnh, thành phố. |
data[].ward | stringCó thể trống | Phường, xã. |
data[].streetAddress | stringCó thể trống | Số nhà, tên đường. |
data[].contactPerson | stringCó thể trống | Người liên hệ. |
data[].note | stringCó thể trống | Ghi chú. |
nextCursor | stringCó thể trống | Truyền vào cursor để lấy trang sau, trống là hết. |
Hoá đơn
Đọc hoá đơn và phiếu thu để đưa sang phần mềm kế toán hoặc báo cáo tổng hợp, chỉ đọc. API không tạo, sửa hay thu tiền hoá đơn: mọi việc ghi tiền vẫn làm trong phần mềm của phòng khám. Cách làm thường dùng: nhận webhook invoice.created và payment.created, rồi gọi chi tiết để lấy số liệu.
Dùng khi
- Tự động đưa doanh thu sang MISA hoặc phần mềm kế toán khác.
- Đối chiếu phiếu thu với sao kê ngân hàng ở phần mềm của bạn.
Lấy danh sách hoá đơn
from đến to, tối đa 366 ngày mỗi lượt, xếp theo thời điểm lập tăng dần. Có đủ nháp, đã phát hành, đã thu và đã huỷ, lọc bằng status nếu chỉ cần một loại. Kết quả chỉ có số tổng, cần dòng hàng và phiếu thu thì gọi chi tiết từng hoá đơn./invoicesinvoices:readTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
from | Truy vấn | date-time | Bắt buộc | Lập từ thời điểm. |
to | Truy vấn | date-time | Bắt buộc | Lập đến thời điểm, cách from tối đa 366 ngày. |
branchId | Truy vấn | uuid | Chỉ lấy một chi nhánh. | |
customerId | Truy vấn | uuid | Chỉ lấy một khách. | |
status | Truy vấn | enum | Chỉ lấy một trạng thái. Giá trị: draftissuedpartially_paidpaidvoidedrefunded | |
limit | Truy vấn | integer | Số dòng mỗi trang, từ 1 đến 100. | |
cursor | Truy vấn | string | Giá trị nextCursor của trang trước. Bỏ trống để lấy trang đầu. |
curl -X GET 'https://app.avenix.vn/v1/open/invoices' \ -H "Authorization: Bearer $TOKEN"
{ "data": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "draft", "subtotal": 1, "discount": 1, "vatAmount": 1, "total": 1, "amountPaid": 1, "amountDue": 1, "issuedAt": "2026-11-01T09:00:00+07:00", "createdAt": "2026-11-01T09:00:00+07:00", "customerCode": "KH-00012", "customerName": "Nguyễn Văn An", "note": "string", "voidReason": "string", "encounterId": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } ], "nextCursor": "string" }
Các trường trả về20
| Tên trường | Kiểu | Mô tả |
|---|---|---|
data | array | Các dòng của trang này. |
data[].id | uuid | Mã hoá đơn. |
data[].code | string | Mã ngắn hiện trong phần mềm. |
data[].branchId | uuid | Chi nhánh. |
data[].customerId | uuidCó thể trống | Khách hàng, trống với khách lẻ. |
data[].status | enum | Trạng thái hoá đơn. Giá trị: draftissuedpartially_paidpaidvoidedrefunded |
data[].subtotal | integer | Tiền hàng, tính bằng đồng. |
data[].discount | integer | Giảm giá cả đơn. |
data[].vatAmount | integer | Tiền thuế GTGT. |
data[].total | integer | Tổng phải trả. |
data[].amountPaid | integer | Đã thu. |
data[].amountDue | integer | Còn nợ. |
data[].issuedAt | date-timeCó thể trống | Thời điểm phát hành, trống với nháp. |
data[].createdAt | date-time | Thời điểm lập. |
data[].customerCode | stringCó thể trống | Mã ngắn của khách. |
data[].customerName | stringCó thể trống | Họ tên khách. |
data[].note | stringCó thể trống | Ghi chú của đơn. |
data[].voidReason | stringCó thể trống | Lý do huỷ. |
data[].encounterId | uuidCó thể trống | Phiếu khám của hoá đơn, trống khi bán lẻ. |
nextCursor | stringCó thể trống | Truyền vào cursor để lấy trang sau, trống là hết. |
Lấy chi tiết hoá đơn
amountDue là số khách còn nợ, refundedAmount trên phiếu thu là số đã hoàn. Hoá đơn đã phát hành không sửa được, sai thì phòng khám huỷ và lập lại, nên hãy theo dõi sự kiện invoice.status_changed./invoices/{id}invoices:readTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
id | Đường dẫn | uuid | Bắt buộc | Mã bản ghi. |
curl -X GET 'https://app.avenix.vn/v1/open/invoices/3fa85f64-5717-4562-b3fc-2c963f66afa6' \ -H "Authorization: Bearer $TOKEN"
{ "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "code": "KH-00012", "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "status": "draft", "subtotal": 1, "discount": 1, "vatAmount": 1, "total": 1, "amountPaid": 1, "amountDue": 1, "issuedAt": "2026-11-01T09:00:00+07:00", "createdAt": "2026-11-01T09:00:00+07:00", "customerCode": "KH-00012", "customerName": "Nguyễn Văn An", "note": "string", "voidReason": "string", "encounterId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "vatRateDefault": 1, "discountReason": "string", "encounterCode": "string", "doctorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "doctorName": "string", "createdByName": "string", "updatedAt": "2026-11-01T09:00:00+07:00", "lines": [ { "code": "KH-00012", "name": "Chi nhánh Quận 1", "unit": "string", "quantity": 1, "unitPrice": 1, "discount": 1, "lineTotal": 1, "vatRate": 1, "vatAmount": 1, "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "discountPercent": 1, "priceIncludesVat": true, "positions": [ "string" ], "note": "string", "plannedDate": "string", "promotionName": "string", "promotionDiscount": 1, "membershipDiscount": 1 } ], "payments": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "method": "cash", "amount": 1, "refundedAmount": 1, "status": "pending", "confirmedAt": "2026-11-01T09:00:00+07:00", "accountName": "string", "reference": "string", "createdAt": "2026-11-01T09:00:00+07:00", "refundedAt": "2026-11-01T09:00:00+07:00", "refundReason": "string" } ] }
Các trường trả về56
| Tên trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | Mã hoá đơn. |
code | string | Mã ngắn hiện trong phần mềm. |
branchId | uuid | Chi nhánh. |
customerId | uuidCó thể trống | Khách hàng, trống với khách lẻ. |
status | enum | Trạng thái hoá đơn. Giá trị: draftissuedpartially_paidpaidvoidedrefunded |
subtotal | integer | Tiền hàng, tính bằng đồng. |
discount | integer | Giảm giá cả đơn. |
vatAmount | integer | Tiền thuế GTGT. |
total | integer | Tổng phải trả. |
amountPaid | integer | Đã thu. |
amountDue | integer | Còn nợ. |
issuedAt | date-timeCó thể trống | Thời điểm phát hành, trống với nháp. |
createdAt | date-time | Thời điểm lập. |
customerCode | stringCó thể trống | Mã ngắn của khách. |
customerName | stringCó thể trống | Họ tên khách. |
note | stringCó thể trống | Ghi chú của đơn. |
voidReason | stringCó thể trống | Lý do huỷ. |
encounterId | uuidCó thể trống | Phiếu khám của hoá đơn, trống khi bán lẻ. |
vatRateDefault | integer | Thuế suất mặc định của đơn. |
discountReason | stringCó thể trống | Lý do giảm giá cả đơn. |
encounterCode | stringCó thể trống | Mã phiếu khám. |
doctorId | uuidCó thể trống | Bác sĩ phụ trách. |
doctorName | stringCó thể trống | Tên bác sĩ phụ trách. |
createdByName | stringCó thể trống | Người lập hoá đơn. |
updatedAt | date-timeCó thể trống | Thời điểm sửa gần nhất. |
lines | array | Các dòng hàng. |
lines[].code | string | Mã dịch vụ hoặc hàng hoá. |
lines[].name | string | Tên trên hoá đơn. |
lines[].unit | string | Đơn vị tính. |
lines[].quantity | integer | Số lượng. |
lines[].unitPrice | integer | Đơn giá. |
lines[].discount | integer | Giảm giá của dòng. |
lines[].lineTotal | integer | Thành tiền của dòng. |
lines[].vatRate | integer | Thuế suất, tính bằng phần trăm. |
lines[].vatAmount | integer | Tiền thuế của dòng. |
lines[].id | uuid | Mã dòng. |
lines[].discountPercent | number | Mức phần trăm đã thoả thuận của dòng. |
lines[].priceIncludesVat | boolean | Thành tiền đã gồm thuế của dòng hay chưa. |
lines[].positions | array | Vị trí làm dịch vụ, ví dụ số răng. |
lines[].note | stringCó thể trống | Ghi chú của dòng. |
lines[].plannedDate | stringCó thể trống | Mốc thời gian đã chốt của dòng. |
lines[].promotionName | stringCó thể trống | Chương trình khuyến mãi đã áp. |
lines[].promotionDiscount | integer | Phần chương trình khuyến mãi giảm, đã nằm trong discount. |
lines[].membershipDiscount | integer | Phần hạng thành viên giảm, đã nằm trong discount. |
payments | array | Các phiếu thu của hoá đơn. |
payments[].id | uuid | Mã phiếu thu. |
payments[].method | enum | Hình thức thu. Giá trị: cashtransfervietqrbalancedepositpointscard |
payments[].amount | integer | Số tiền thu. |
payments[].refundedAmount | integer | Số tiền đã hoàn. |
payments[].status | enum | Trạng thái phiếu thu. Giá trị: pendingconfirmedrefunded |
payments[].confirmedAt | date-timeCó thể trống | Thời điểm thu. |
payments[].accountName | stringCó thể trống | Tài khoản nhận tiền. |
payments[].reference | stringCó thể trống | Mã tham chiếu giao dịch. |
payments[].createdAt | date-time | Thời điểm ghi phiếu. |
payments[].refundedAt | date-timeCó thể trống | Thời điểm hoàn gần nhất. |
payments[].refundReason | stringCó thể trống | Lý do hoàn. |
Kết nối phần mềm labo
API riêng cho phần mềm quản lý xét nghiệm của xưởng labo: tự lấy đơn phòng khám gửi và đẩy kết quả thẳng vào phiếu khám. Khoá, token và webhook của phần này tách hẳn khỏi Open API của phòng khám.
Giới hạn 300 lượt mỗi phút cho mỗi đường và mỗi địa chỉ IP, riêng lấy token 30 lượt. Dữ liệu gửi và nhận là JSON, mã hoá UTF-8. Thời điểm theo ISO 8601 giờ UTC, ngày (như dueDate) dạng YYYY-MM-DD theo lịch của phòng khám.
https://ma-phong-kham.avenix.vn/v1/lab-connectMỗi phòng khám một địa chỉ riêng, lấy ở ô Địa chỉ API trong hộp Kết nối phần mềm labo. Labo làm việc với nhiều phòng khám thì mỗi phòng khám cấp một khoá và một địa chỉ.
Phạm vi của khoá
- Khoá do phòng khám cấp cho đúng một xưởng labo: mã kết nối dạng
avxl_..., bí mật dạngavxls_.... - Token của khoá chỉ gọi được các đường dưới
/v1/lab-connect: lấy token, danh sách đơn, một đơn, cập nhật đơn, gửi kết quả, tải tệp kết quả. Gọi API khác của phần mềm (khách hàng, lịch hẹn, hoá đơn, Open API) đều bị từ chối401. - Chỉ thấy và chỉ ghi được đơn phòng khám gửi cho chính xưởng đó. Đơn của xưởng khác hay của phòng khám khác trả
404như không tồn tại. - Dữ liệu khách tối thiểu: mã khách, giới tính, tuổi. Họ tên chỉ có khi phòng khám bật Gửi họ tên khách. Không bao giờ có số điện thoại, địa chỉ, giấy tờ, chẩn đoán hay tiền.
- Không huỷ, không hoàn tất đơn, không xoá kết quả được. Đó là việc của phòng khám.
- Mỗi lượt gọi đọc lại khoá: phòng khám bấm Tắt kết nối, đổi danh sách IP hay gói hết phần Labo là có hiệu lực ngay, kể cả với token còn hạn.
- Token Open API của phòng khám và token đăng nhập của nhân viên không dùng được ở đây, và ngược lại: ba loại token ký bằng ba khoá khác nhau.
- Mỗi lượt xem đơn, cập nhật, gửi kết quả đều vào nhật ký của phòng khám, người thực hiện là kết nối của xưởng kèm tên kỹ thuật viên gửi lên.
Lấy khoá
- Phòng khám vào Labo, mục Xưởng labo, bấm nút ba chấm ở dòng của xưởng, chọn Kết nối phần mềm labo.
- Bấm Tạo khoá kết nối. Hộp hiện Mã kết nối, bí mật và Địa chỉ API. Bí mật chỉ hiện một lần, đóng hộp là không xem lại được.
- Phòng khám gửi ba thứ đó cho bên làm phần mềm của xưởng qua kênh riêng, không dán vào nhóm chat chung.
- Muốn khoá chỉ dùng được từ máy chủ của xưởng thì điền IP ở ô Chỉ nhận từ địa chỉ IP.
- Lộ bí mật thì bấm Đổi khoá: bí mật cũ còn dùng được 24 giờ để xưởng kịp thay. Ngừng hợp tác thì bấm Tắt kết nối, khoá hết hiệu lực ngay.
- Chỉ người có quyền Kết nối phần mềm labo mới tạo, đổi, tắt khoá được; mặc định chỉ chủ phòng khám.
curl -X POST 'https://ma-phong-kham.avenix.vn/v1/lab-connect/oauth/token' \ -d grant_type=client_credentials \ -d client_id=$CLIENT_ID \ -d client_secret=$CLIENT_SECRET
Luồng làm việc
- Đổi mã và bí mật lấy token ở
POST /oauth/token, dùng tới gần hếtexpires_inrồi xin lại. - Biết đơn mới: nhận webhook
lab_order.created, hoặc vài phút gọiGET /orders?updatedSince=...một lần. - Gọi
GET /orders/{code}lấy các dòng xét nghiệm, bảng chỉ số, mã khách, giới tính, tuổi. - Nhận mẫu thì gọi
PATCH /orders/{code}vớistatuslàprocessing; có ngày trả thì gửidueDate. - Có tệp PDF kết quả thì tải lên qua
/orders/{code}/filestrước để lấy mã tệp. - Gửi kết quả từng dòng ở
POST /orders/{code}/items/{itemId}/resultkèmIdempotency-Key. Đủ mọi dòng thì đơn tự sang Đã có kết quả và bác sĩ nhận thông báo. - Nhận webhook
lab_order.cancelled, hoặc thấystatuslàcancelledở danh sách đơn, thì dừng làm đơn đó: đơn đã huỷ đọc chi tiết trả404. Đơncompletedlà phòng khám đã đóng, không gửi gì thêm.
Nhận mẫu bằng mã vạch trên phiếu
- Phiếu giao nhận mẫu phòng khám gửi kèm mẫu in mã đơn ở góc trên bên phải (ví dụ
LAB-000123), dưới là mã vạch Code 128 của chính mã đó. Đây là{code}của mọi đường dẫn/orders/{code}. - Lúc nhận mẫu, quét mã vạch bằng máy quét (máy quét gõ mã vào ô đang chọn như bàn phím) hoặc gõ tay mã in trên phiếu, rồi gọi
GET /orders/{code}để lấy đơn và các dòng xét nghiệm, không cần chờ webhook. - Mã đơn không phân biệt chữ hoa thường: gõ
lab-000123vẫn ra đơnLAB-000123. - Mã QR trên phiếu (khối Dành cho đơn vị xét nghiệm) là liên kết để nhập kết quả tay trên web, không chứa mã đơn. Phần mềm labo quét mã vạch, không quét mã QR.
- Mã đơn chỉ là duy nhất trong một phòng khám. Labo làm cho nhiều phòng khám thì phần mềm labo phải biết phiếu của phòng khám nào để dùng đúng khoá và địa chỉ, ví dụ cho người nhận mẫu chọn phòng khám trước khi quét. Khoá của phòng khám khác trả
404, không bao giờ trả nhầm đơn.
Ghép mã chỉ số
- Gửi
analyteIdlấy từitems[].analytes[].idlà cách chắc nhất. - Phần mềm labo chỉ có mã của mình thì gửi
code, kèmloincvàlabelnếu có: mã khớp LOINC, khoá hay tên chỉ số của phòng khám thì tự ghép. - Phòng khám không cần khai sẵn bảng chỉ số: labo gửi
code,label,value,unit,refTextlà đủ, kết quả lưu và in đúng như labo gửi. Mã lạ hiện ở tab Ghép mã xét nghiệm của phòng khám, ghép hay không tuỳ phòng khám. - Dòng có
valuesAcceptedlàfalse(thú y, dòng ghi tay) vẫn nhậnvalues: kết quả được dựng thành chữ, mỗi chỉ số một dòng kèm đơn vị, tham chiếu và cờ.
Bất thường và nguy hiểm
- Gửi
refTextlà khoảng tham chiếu của labo. Giá trị số ngoài khoảng tự thành bất thường (low,high), trong khoảng là bình thường. - Khoảng
Âm tínhmà kết quảDương tính(và ngược lại) cũng tự thành bất thường. Chữ khác thì gửi kèmflaglàabnormalhoặcnormal. - Mức nguy hiểm chỉ có khi labo gửi
flaglàcritical_lowhoặccritical_high(HL7 làLL,HH), hoặc khi phòng khám tự khai ngưỡng nguy hiểm cho chỉ số đó. Cờ nguy hiểm của labo luôn được giữ. - Dòng có giá trị bất thường hoặc nguy hiểm thì bác sĩ nhận thông báo ngay.
Đơn sản phẩm
- Đơn có
kindlàproductlà đơn gia công (răng sứ, hàm, máng...). Mỗi dòng là một sản phẩm:labProductCode,quantity,positions(nha khoa là số răng FDI),details(thông số phòng khám ghi, như Màu, Cầu). - Dòng sản phẩm không nhận kết quả: gọi đường gửi kết quả cho dòng này trả
422. - Báo tiến độ bằng
PATCH /orders/{code}:processingkhi bắt đầu làm,try_inkhi giao mẫu thử cho phòng khám, phòng khám báo thử chưa đạt thì vềprocessing,receivedkhi giao thành phẩm. try_inchỉ dùng cho đơn sản phẩm, đơn xét nghiệm trả422. Ngày hẹn thử và ngày hẹn nhận ởsampleTryDate,sampleReceiveDate.
Thử kết nối
- Chưa có môi trường thử riêng: thử trên phòng khám thật, với một hồ sơ khách thử.
- Phòng khám tạo khoá cho xưởng, rồi lập một đơn thử gửi xưởng đó (Labo, mục Đơn gửi mẫu, chọn đúng xưởng) với hai dòng xét nghiệm.
- Phần mềm labo lấy token, thấy đơn ở
GET /orders, đọc chi tiết, chuyểnprocessing, gửi kết quả cho một dòng. - Phòng khám mở đơn kiểm kết quả, cờ bất thường, tệp, thông báo, và tab Ghép mã xét nghiệm. Xong thì huỷ đơn thử: đơn còn dòng chưa có kết quả mới huỷ được.
Webhook
Lấy địa chỉ và bí mật ký
- Bên làm phần mềm labo dựng một địa chỉ
httpscông khai nhậnPOSTJSON, ví dụhttps://lis.xuong-labo.vn/avenix/webhook, rồi gửi địa chỉ đó cho phòng khám. - Phòng khám mở hộp Kết nối phần mềm labo của xưởng, dán địa chỉ vào ô Địa chỉ nhận webhook, bấm Lưu.
- Hộp hiện bí mật ký webhook dạng
whsec_..., chỉ hiện một lần. Phòng khám gửi bí mật này cho xưởng, phần mềm labo dùng nó để kiểm chữ ký từng bản tin. - Mỗi lần lưu lại địa chỉ là cấp bí mật mới, bí mật cũ hết dùng, nên phòng khám phải gửi lại bí mật mới cho xưởng. Bấm Bỏ để ngừng webhook, khi đó phần mềm labo tự hỏi định kỳ.
- Bản tin chỉ có mã đơn, không có dữ liệu khách. Nhận xong gọi
GET /orders/{code}lấy chi tiết. - Trả mã 2xx trong 10 giây là đã nhận, xử lý lâu thì đưa vào hàng đợi của bạn.
- Chưa nhận được thì gửi lại sau 5 giây, 5 phút, 30 phút, 2 giờ, 5 giờ, 10 giờ, 10 giờ, cùng
webhook-id. Hãy bỏ qua mã đã xử lý. - Trả
410thì thôi gửi lại bản tin đó. Không chuyển hướng: mã 3xx tính là hỏng. Hết lượt gửi lại thì bỏ bản tin, đơn vẫn đọc được quaGET /orders?updatedSince=.... - Thứ tự không được bảo đảm, dựa vào trạng thái đọc qua API.
- Chữ ký theo chuẩn Standard Webhooks: HMAC SHA-256 của chuỗi
webhook-id.webhook-timestamp.thân bản tin, khoá là phần sauwhsec_giải mã base64, kết quả base64 đứng sauv1,. Mã kiểm mẫu ở dưới.
Mẫu bản tin
webhook-id: 7c1e9f3a-2b4d-4e8a-9f10-3d5c6b7a8e21
webhook-timestamp: 1794900600
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4={ "id": "7c1e9f3a-2b4d-4e8a-9f10-3d5c6b7a8e21", "type": "lab_order.created", "timestamp": "2026-11-17T07:30:00.000Z", "data": { "orderCode": "LAB-000045" } }
Kiểm chữ ký
// Dùng nguyên văn thân bản tin chưa parse. import { createHmac, timingSafeEqual } from 'node:crypto'; function verify(secret, headers, rawBody) { const id = headers['webhook-id']; const ts = headers['webhook-timestamp']; if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false; const key = Buffer.from(secret.replace('whsec_', ''), 'base64'); const mac = createHmac('sha256', key).update(`${id}.${ts}.${rawBody}`).digest('base64'); const expected = Buffer.from(`v1,${mac}`); // Trong lúc đổi bí mật, header có thể mang hai chữ ký cách nhau bằng dấu cách. return headers['webhook-signature'].split(' ').some((sig) => { const got = Buffer.from(sig); return got.length === expected.length && timingSafeEqual(got, expected); }); }
Các sự kiện
| Sự kiện | Mô tả |
|---|---|
lab_order.created | Phòng khám gửi đơn mới cho xưởng |
lab_order.cancelled | Phòng khám huỷ một đơn đã gửi |
Mã lỗi
Đường lấy token trả lỗi theo OAuth 2.0 (error, error_description). Các đường còn lại trả lỗi dạng application/problem+json (RFC 7807): status là mã lỗi, detail là câu giải thích tiếng Việt, nên ghi detail vào nhật ký của phần mềm labo.
{ "type": "about:blank", "title": "Unprocessable Entity", "status": 422, "detail": "Chỉ số không thuộc xét nghiệm này", "instance": "/v1/lab-connect/orders/LAB-000045/items/0b7d3c52-6f1e-4a9b-9c2d-8e5f4a3b2c11/result" }
{ "error": "invalid_client", "error_description": "Mã kết nối hoặc bí mật không đúng" }
| Mã | Ý nghĩa |
|---|---|
400 | Dữ liệu gửi lên không hợp lệ, hoặc thiếu header Idempotency-Key. |
401 | Thiếu token, token hết hạn, hoặc khoá đã bị tắt hay đổi. Token Open API không dùng được ở đây. |
403 | Gọi từ địa chỉ IP ngoài danh sách phòng khám khai, hoặc gói của phòng khám không còn Labo. |
404 | Không có đơn này, đơn không gửi cho xưởng của khoá, hoặc đơn đã huỷ. |
409 | Phòng khám đã hoàn tất đơn, hoặc chuyển Đã có kết quả khi còn dòng chưa có kết quả. |
422 | Không làm được theo luật nghiệp vụ: chỉ số không thuộc dòng, hai giá trị cùng một chỉ số, gửi kết quả cho dòng sản phẩm, chuyển try_in với đơn xét nghiệm, tệp chưa tải xong, thiếu tệp PDF khi phòng khám bắt buộc, hoặc Idempotency-Key đã dùng cho nội dung khác. |
429 | Vượt giới hạn gọi. Chờ theo header Retry-After. |
API kết nối phần mềm labo
Lấy token truy cập
invalid_client./oauth/tokenNội dung gửi
| Tên trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
grant_type | enum | Bắt buộc | Luôn là client_credentials. |
client_id | string | Bắt buộc | Mã kết nối, dạng avxl_.... |
client_secret | string | Bắt buộc | Bí mật của khoá, dạng avxls_.... |
curl -X POST 'https://ma-phong-kham.avenix.vn/v1/lab-connect/oauth/token' \ -d grant_type=client_credentials \ -d client_id=$CLIENT_ID \ -d client_secret=$CLIENT_SECRET
{ "access_token": "<token>", "token_type": "Bearer", "expires_in": 3600 }
Các trường trả về3
| Tên trường | Kiểu | Mô tả |
|---|---|---|
access_token | string | Token gửi trong header Authorization: Bearer. |
token_type | enum | Luôn là Bearer. |
expires_in | integer | Số giây token còn hiệu lực. |
Danh sách đơn
updatedSince để biết đơn mới./ordersTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
status | Truy vấn | string | Lọc trạng thái, nhiều giá trị cách nhau bằng dấu phẩy. Bỏ trống thì trả đơn còn làm việc được (sent, processing, try_in, received). | |
updatedSince | Truy vấn | date-time | Chỉ đơn cập nhật sau mốc này (ISO 8601). Lưu updatedAt lớn nhất đã đọc rồi gửi lại ở lượt sau để chỉ lấy phần thay đổi. | |
cursor | Truy vấn | string | Giá trị nextCursor của trang trước. Bỏ trống để lấy trang đầu. | |
limit | Truy vấn | integer | Số đơn mỗi trang, từ 1 đến 100, mặc định 50. |
curl -X GET 'https://ma-phong-kham.avenix.vn/v1/lab-connect/orders' \ -H "Authorization: Bearer $TOKEN"
{ "items": [ { "code": "LAB-000045", "status": "sent", "kind": "test", "testCategory": "Huyết học", "sentAt": "2026-11-17T07:30:00.000Z", "dueDate": "2026-11-18", "updatedAt": "2026-11-17T07:30:00.000Z" } ], "nextCursor": null }
Các trường trả về9
| Tên trường | Kiểu | Mô tả |
|---|---|---|
items | array | Các đơn, mới gửi trước. |
items[].code | string | Mã đơn labo, dùng ở mọi đường dẫn /orders/{code}. |
items[].status | enum | Trạng thái đơn: sent đã gửi mẫu, processing đang phân tích, try_in thử mẫu, received đã có kết quả, completed phòng khám đã hoàn tất, cancelled đã huỷ.Giá trị: sentprocessingtry_inreceivedcompletedcancelled |
items[].kind | enum | test là đơn xét nghiệm, product là đơn gia công sản phẩm.Giá trị: producttest |
items[].testCategory | string | Nhóm xét nghiệm. |
items[].sentAt | date-time | Lúc phòng khám gửi đơn. |
items[].dueDate | dateCó thể trống | Ngày hẹn trả kết quả, hay ngày hẹn giao thành phẩm với đơn sản phẩm. |
items[].updatedAt | date-time | Lần đổi gần nhất của đơn. |
nextCursor | stringCó thể trống | Gửi vào cursor để lấy trang tiếp. null là hết. |
Một đơn
/orders/{code}Tham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
code | Đường dẫn | string | Bắt buộc | Mã đơn labo (items[].code của danh sách đơn, data.orderCode của webhook, hoặc mã in và mã vạch trên phiếu giao nhận mẫu). Không phân biệt chữ hoa thường. |
curl -X GET 'https://ma-phong-kham.avenix.vn/v1/lab-connect/orders/LAB-000045' \ -H "Authorization: Bearer $TOKEN"
{ "code": "LAB-000045", "status": "processing", "kind": "test", "partnerName": "Xưởng xét nghiệm Việt Lab", "patientCode": "KH-000123", "patientName": null, "sex": "male", "ageYears": 46, "subjectLabel": null, "encounterCode": "PK-000210", "sampleType": "Máu toàn phần", "testCategory": "Huyết học", "note": "Lấy máu lúc 7 giờ, khách chưa ăn sáng", "dueDate": "2026-11-18", "sampleTryDate": null, "sampleReceiveDate": null, "sentAt": "2026-11-17T07:30:00.000Z", "processingAt": "2026-11-17T09:05:00.000Z", "tryInAt": null, "receivedAt": null, "completedAt": null, "canEdit": true, "resultPdfRequired": false, "items": [ { "id": "0b7d3c52-6f1e-4a9b-9c2d-8e5f4a3b2c11", "label": "Công thức máu", "serviceCode": "XN-CTM", "labProductCode": null, "quantity": 1, "unit": "Lần", "positions": [], "details": [], "result": null, "resultFileIds": [], "abnormal": null, "resultedAt": null, "resultedByName": null, "valuesAccepted": true, "editable": true, "analytes": [ { "id": "5c9e1a7f-3b2d-4c6e-8f0a-1d2e3f4a5b61", "key": "wbc", "label": "Bạch cầu (WBC)", "valueKind": "numeric", "unit": "G/L", "decimals": 1, "choices": [], "refRanges": [ { "low": 4, "high": 10 } ], "loincCode": "6690-2" } ], "values": [] } ] }
Các trường trả về64
| Tên trường | Kiểu | Mô tả |
|---|---|---|
code | string | Mã đơn labo, dùng ở mọi đường dẫn /orders/{code}. |
status | enum | Trạng thái đơn: sent đã gửi mẫu, processing đang phân tích, try_in thử mẫu, received đã có kết quả, completed phòng khám đã hoàn tất, cancelled đã huỷ.Giá trị: sentprocessingtry_inreceivedcompletedcancelled |
kind | enum | test là đơn xét nghiệm, product là đơn gia công sản phẩm.Giá trị: producttest |
partnerName | string | Tên xưởng labo nhận đơn (chính xưởng của khoá). |
patientCode | stringCó thể trống | Mã khách của phòng khám, in lên phiếu kết quả để đối chiếu. |
patientName | stringCó thể trống | Họ tên khách. Luôn null trừ khi phòng khám bật Gửi họ tên khách cho xưởng. |
sex | stringCó thể trống | Giới tính, để chọn khoảng tham chiếu. |
ageYears | numberCó thể trống | Tuổi tính theo năm, để chọn khoảng tham chiếu. |
subjectLabel | stringCó thể trống | Đối tượng lấy mẫu theo chuyên khoa của phòng khám, có thể trống. |
encounterCode | stringCó thể trống | Mã phiếu khám đã chỉ định, có thể trống. |
sampleType | string | Loại mẫu (máu toàn phần, huyết thanh...). |
testCategory | string | Nhóm xét nghiệm. |
note | stringCó thể trống | Ghi chú của phòng khám gửi xưởng. |
dueDate | dateCó thể trống | Ngày hẹn trả kết quả, hay ngày hẹn giao thành phẩm với đơn sản phẩm. |
sampleTryDate | dateCó thể trống | Đơn sản phẩm: ngày hẹn thử mẫu trên khách. |
sampleReceiveDate | dateCó thể trống | Đơn sản phẩm: ngày hẹn nhận thành phẩm. |
sentAt | date-time | Lúc phòng khám gửi đơn. |
processingAt | date-timeCó thể trống | Lúc chuyển Đang phân tích. |
tryInAt | date-timeCó thể trống | Đơn sản phẩm: lúc chuyển Thử mẫu. |
receivedAt | date-timeCó thể trống | Lúc có đủ kết quả. |
completedAt | date-timeCó thể trống | Lúc phòng khám hoàn tất đơn. |
canEdit | boolean | false khi đơn đã hoàn tất: không cập nhật, không gửi kết quả được nữa. |
resultPdfRequired | boolean | Phòng khám bắt buộc kèm tệp PDF kết quả: lượt gửi kết quả không có tệp PDF trả 422. |
items | array | Các dòng của đơn: xét nghiệm với đơn test, sản phẩm với đơn product. |
items[].id | uuid | Mã dòng, dùng ở /orders/{code}/items/{itemId}/result. |
items[].label | string | Tên xét nghiệm. |
items[].serviceCode | stringCó thể trống | Mã dịch vụ của phòng khám. |
items[].labProductCode | stringCó thể trống | Mã sản phẩm labo của phòng khám (dòng sản phẩm). null với dòng xét nghiệm: chỉ dòng xét nghiệm nhận kết quả. |
items[].quantity | integer | Số lượng. |
items[].unit | stringCó thể trống | Đơn vị tính của dòng. |
items[].positions | array | Vị trí của dòng. Nha khoa là số răng FDI, như 11, 21. |
items[].details | array | Thông số của dòng sản phẩm do phòng khám ghi, như Màu, Cầu. Mỗi mục có key, label, value. |
items[].details[].key | string | |
items[].details[].label | string | |
items[].details[].value | string | |
items[].result | stringCó thể trống | Kết quả dạng chữ đã gửi. |
items[].resultFileIds | array | Các tệp kết quả đã đính. |
items[].abnormal | booleanCó thể trống | Kết quả bất thường. |
items[].resultedAt | date-timeCó thể trống | Lúc có kết quả. |
items[].resultedByName | stringCó thể trống | Kỹ thuật viên đã gửi kết quả. |
items[].valuesAccepted | boolean | true thì dòng lưu kết quả theo từng chỉ số. false (thú y, dòng ghi tay) thì values gửi lên được dựng thành kết quả chữ, mỗi chỉ số một dòng. |
items[].editable | boolean | false khi không còn gửi hay sửa kết quả được (hồ sơ đã ký số, đơn đã đóng). |
items[].analytes | array | Bảng chỉ số phòng khám khai cho xét nghiệm này. Thường trống khi phòng khám không khai: khi đó gửi chỉ số theo code và label của labo. |
items[].analytes[].id | uuid | Gửi lại trong values[].analyteId để kết quả vào đúng chỉ số. |
items[].analytes[].key | string | Khoá chỉ số của phòng khám. |
items[].analytes[].label | string | Tên chỉ số. |
items[].analytes[].valueKind | enum | numeric gửi số, choice gửi một trong choices, text gửi chữ.Giá trị: numericchoicetext |
items[].analytes[].unit | stringCó thể trống | Đơn vị của chỉ số. |
items[].analytes[].decimals | integer | Số chữ số thập phân hiển thị. |
items[].analytes[].choices | array | Các lựa chọn khi valueKind là choice. |
items[].analytes[].refRanges | array | Khoảng tham chiếu theo giới tính và tuổi. |
items[].analytes[].refRanges[].sex | enum | Giá trị: malefemale |
items[].analytes[].refRanges[].ageMinYears | number | |
items[].analytes[].refRanges[].ageMaxYears | number | |
items[].analytes[].refRanges[].low | number | |
items[].analytes[].refRanges[].high | number | |
items[].analytes[].loincCode | stringCó thể trống | Mã LOINC nếu phòng khám đã khai. |
items[].values | array | Các giá trị đã có, để phần mềm labo hiện lại và sửa. |
items[].values[].analyteId | uuid | |
items[].values[].label | string | |
items[].values[].value | number | string | |
items[].values[].unit | stringCó thể trống | |
items[].values[].refText | stringCó thể trống | |
items[].values[].flag | enumCó thể trống | Giá trị: normallowhighabnormalcritical_lowcritical_high |
Cập nhật trạng thái, hẹn trả
received chỉ được khi mọi dòng đã có kết quả; gửi đủ kết quả thì đơn tự chuyển, không cần gọi. Đơn sản phẩm: processing khi bắt đầu làm, try_in khi giao mẫu thử, thử chưa đạt thì về processing, received khi giao thành phẩm. Không huỷ, không hoàn tất đơn được: đó là việc của phòng khám./orders/{code}Tham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
code | Đường dẫn | string | Bắt buộc | Mã đơn labo (items[].code của danh sách đơn, data.orderCode của webhook, hoặc mã in và mã vạch trên phiếu giao nhận mẫu). Không phân biệt chữ hoa thường. |
Nội dung gửi
| Tên trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
technicianName | string | Bắt buộc | Tên kỹ thuật viên, ghi vào nhật ký của phòng khám. |
status | enum | Trạng thái mới: processing, try_in hoặc received.Giá trị: processingtry_inreceived | |
dueDate | dateCó thể trống | Ngày hẹn trả kết quả, null để bỏ hẹn. |
curl -X PATCH 'https://ma-phong-kham.avenix.vn/v1/lab-connect/orders/LAB-000045' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"technicianName":"KTV Trần Bình","status":"processing","dueDate":"2026-11-20"}'
{ "code": "LAB-000045", "status": "processing", "kind": "test", "partnerName": "Xưởng xét nghiệm Việt Lab", "patientCode": "KH-000123", "patientName": null, "sex": "male", "ageYears": 46, "subjectLabel": null, "encounterCode": "PK-000210", "sampleType": "Máu toàn phần", "testCategory": "Huyết học", "note": "Lấy máu lúc 7 giờ, khách chưa ăn sáng", "dueDate": "2026-11-18", "sampleTryDate": null, "sampleReceiveDate": null, "sentAt": "2026-11-17T07:30:00.000Z", "processingAt": "2026-11-17T09:05:00.000Z", "tryInAt": null, "receivedAt": null, "completedAt": null, "canEdit": true, "resultPdfRequired": false, "items": [ { "id": "0b7d3c52-6f1e-4a9b-9c2d-8e5f4a3b2c11", "label": "Công thức máu", "serviceCode": "XN-CTM", "labProductCode": null, "quantity": 1, "unit": "Lần", "positions": [], "details": [], "result": null, "resultFileIds": [], "abnormal": null, "resultedAt": null, "resultedByName": null, "valuesAccepted": true, "editable": true, "analytes": [ { "id": "5c9e1a7f-3b2d-4c6e-8f0a-1d2e3f4a5b61", "key": "wbc", "label": "Bạch cầu (WBC)", "valueKind": "numeric", "unit": "G/L", "decimals": 1, "choices": [], "refRanges": [ { "low": 4, "high": 10 } ], "loincCode": "6690-2" } ], "values": [] } ] }
Các trường trả về64
| Tên trường | Kiểu | Mô tả |
|---|---|---|
code | string | Mã đơn labo, dùng ở mọi đường dẫn /orders/{code}. |
status | enum | Trạng thái đơn: sent đã gửi mẫu, processing đang phân tích, try_in thử mẫu, received đã có kết quả, completed phòng khám đã hoàn tất, cancelled đã huỷ.Giá trị: sentprocessingtry_inreceivedcompletedcancelled |
kind | enum | test là đơn xét nghiệm, product là đơn gia công sản phẩm.Giá trị: producttest |
partnerName | string | Tên xưởng labo nhận đơn (chính xưởng của khoá). |
patientCode | stringCó thể trống | Mã khách của phòng khám, in lên phiếu kết quả để đối chiếu. |
patientName | stringCó thể trống | Họ tên khách. Luôn null trừ khi phòng khám bật Gửi họ tên khách cho xưởng. |
sex | stringCó thể trống | Giới tính, để chọn khoảng tham chiếu. |
ageYears | numberCó thể trống | Tuổi tính theo năm, để chọn khoảng tham chiếu. |
subjectLabel | stringCó thể trống | Đối tượng lấy mẫu theo chuyên khoa của phòng khám, có thể trống. |
encounterCode | stringCó thể trống | Mã phiếu khám đã chỉ định, có thể trống. |
sampleType | string | Loại mẫu (máu toàn phần, huyết thanh...). |
testCategory | string | Nhóm xét nghiệm. |
note | stringCó thể trống | Ghi chú của phòng khám gửi xưởng. |
dueDate | dateCó thể trống | Ngày hẹn trả kết quả, hay ngày hẹn giao thành phẩm với đơn sản phẩm. |
sampleTryDate | dateCó thể trống | Đơn sản phẩm: ngày hẹn thử mẫu trên khách. |
sampleReceiveDate | dateCó thể trống | Đơn sản phẩm: ngày hẹn nhận thành phẩm. |
sentAt | date-time | Lúc phòng khám gửi đơn. |
processingAt | date-timeCó thể trống | Lúc chuyển Đang phân tích. |
tryInAt | date-timeCó thể trống | Đơn sản phẩm: lúc chuyển Thử mẫu. |
receivedAt | date-timeCó thể trống | Lúc có đủ kết quả. |
completedAt | date-timeCó thể trống | Lúc phòng khám hoàn tất đơn. |
canEdit | boolean | false khi đơn đã hoàn tất: không cập nhật, không gửi kết quả được nữa. |
resultPdfRequired | boolean | Phòng khám bắt buộc kèm tệp PDF kết quả: lượt gửi kết quả không có tệp PDF trả 422. |
items | array | Các dòng của đơn: xét nghiệm với đơn test, sản phẩm với đơn product. |
items[].id | uuid | Mã dòng, dùng ở /orders/{code}/items/{itemId}/result. |
items[].label | string | Tên xét nghiệm. |
items[].serviceCode | stringCó thể trống | Mã dịch vụ của phòng khám. |
items[].labProductCode | stringCó thể trống | Mã sản phẩm labo của phòng khám (dòng sản phẩm). null với dòng xét nghiệm: chỉ dòng xét nghiệm nhận kết quả. |
items[].quantity | integer | Số lượng. |
items[].unit | stringCó thể trống | Đơn vị tính của dòng. |
items[].positions | array | Vị trí của dòng. Nha khoa là số răng FDI, như 11, 21. |
items[].details | array | Thông số của dòng sản phẩm do phòng khám ghi, như Màu, Cầu. Mỗi mục có key, label, value. |
items[].details[].key | string | |
items[].details[].label | string | |
items[].details[].value | string | |
items[].result | stringCó thể trống | Kết quả dạng chữ đã gửi. |
items[].resultFileIds | array | Các tệp kết quả đã đính. |
items[].abnormal | booleanCó thể trống | Kết quả bất thường. |
items[].resultedAt | date-timeCó thể trống | Lúc có kết quả. |
items[].resultedByName | stringCó thể trống | Kỹ thuật viên đã gửi kết quả. |
items[].valuesAccepted | boolean | true thì dòng lưu kết quả theo từng chỉ số. false (thú y, dòng ghi tay) thì values gửi lên được dựng thành kết quả chữ, mỗi chỉ số một dòng. |
items[].editable | boolean | false khi không còn gửi hay sửa kết quả được (hồ sơ đã ký số, đơn đã đóng). |
items[].analytes | array | Bảng chỉ số phòng khám khai cho xét nghiệm này. Thường trống khi phòng khám không khai: khi đó gửi chỉ số theo code và label của labo. |
items[].analytes[].id | uuid | Gửi lại trong values[].analyteId để kết quả vào đúng chỉ số. |
items[].analytes[].key | string | Khoá chỉ số của phòng khám. |
items[].analytes[].label | string | Tên chỉ số. |
items[].analytes[].valueKind | enum | numeric gửi số, choice gửi một trong choices, text gửi chữ.Giá trị: numericchoicetext |
items[].analytes[].unit | stringCó thể trống | Đơn vị của chỉ số. |
items[].analytes[].decimals | integer | Số chữ số thập phân hiển thị. |
items[].analytes[].choices | array | Các lựa chọn khi valueKind là choice. |
items[].analytes[].refRanges | array | Khoảng tham chiếu theo giới tính và tuổi. |
items[].analytes[].refRanges[].sex | enum | Giá trị: malefemale |
items[].analytes[].refRanges[].ageMinYears | number | |
items[].analytes[].refRanges[].ageMaxYears | number | |
items[].analytes[].refRanges[].low | number | |
items[].analytes[].refRanges[].high | number | |
items[].analytes[].loincCode | stringCó thể trống | Mã LOINC nếu phòng khám đã khai. |
items[].values | array | Các giá trị đã có, để phần mềm labo hiện lại và sửa. |
items[].values[].analyteId | uuid | |
items[].values[].label | string | |
items[].values[].value | number | string | |
items[].values[].unit | stringCó thể trống | |
items[].values[].refText | stringCó thể trống | |
items[].values[].flag | enumCó thể trống | Giá trị: normallowhighabnormalcritical_lowcritical_high |
Gửi kết quả một dòng
Idempotency-Key cùng nội dung thì không ghi lần hai, cùng khoá khác nội dung thì 422. Sửa kết quả bằng lượt gửi mới với khoá mới, được tới khi hồ sơ ký số. Đủ kết quả mọi dòng thì đơn tự sang Đã có kết quả./orders/{code}/items/{itemId}/resultTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
code | Đường dẫn | string | Bắt buộc | Mã đơn labo (items[].code của danh sách đơn, data.orderCode của webhook, hoặc mã in và mã vạch trên phiếu giao nhận mẫu). Không phân biệt chữ hoa thường. |
itemId | Đường dẫn | uuid | Bắt buộc | Mã dòng lấy từ items[].id. |
Idempotency-Key | Header | string | Bắt buộc | Chuỗi ngẫu nhiên cho mỗi lượt gửi, 8 đến 200 ký tự. |
Nội dung gửi
| Tên trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
technicianName | string | Bắt buộc | Tên kỹ thuật viên, ghi vào nhật ký của phòng khám. |
result | stringCó thể trống | Kết quả dạng chữ (kết luận, ghi chú). | |
resultFileId | uuidCó thể trống | Cách cũ của resultFileIds, dùng resultFileIds. | |
resultFileIds | array | Các tệp PDF hoặc ảnh đã tải lên qua /orders/{code}/files. | |
abnormal | booleanCó thể trống | Đánh dấu kết quả bất thường. | |
values | array | Kết quả theo từng chỉ số. Cần ít nhất một trong result, values, tệp. | |
values[].analyteId | uuid | Mã chỉ số lấy từ items[].analytes[].id. | |
values[].code | string | Mã chỉ số trong phần mềm labo. Đã ghép thì vào đúng chỉ số, chưa ghép thì phòng khám ghép một lần. | |
values[].loinc | string | Mã LOINC, dùng để tự khớp với chỉ số của phòng khám. | |
values[].label | string | Tên chỉ số in trên phiếu labo, dùng khi mã lạ. | |
values[].value | number | string | Bắt buộc | Số với chỉ số numeric, chữ với choice và text. |
values[].unit | stringCó thể trống | Đơn vị labo ghi. Bỏ trống thì theo đơn vị phòng khám khai. | |
values[].refText | stringCó thể trống | Khoảng tham chiếu labo ghi, như 4 - 10, < 5 hay Âm tính. Ngoài khoảng số là bất thường (thấp, cao); khoảng Âm tính / Dương tính mà kết quả là chữ còn lại cũng là bất thường. | |
values[].flag | enumCó thể trống | Cờ của labo: normal, low, high, abnormal dùng khi không tính được từ khoảng tham chiếu; critical_low, critical_high là mức nguy hiểm, luôn được giữ và báo bác sĩ.Giá trị: normallowhighabnormalcritical_lowcritical_high |
curl -X POST 'https://ma-phong-kham.avenix.vn/v1/lab-connect/orders/LAB-000045/items/0b7d3c52-6f1e-4a9b-9c2d-8e5f4a3b2c11/result' \ -H "Authorization: Bearer $TOKEN" \ -H "Idempotency-Key: $(uuidgen)" \ -H 'Content-Type: application/json' \ -d '{"technicianName":"KTV Trần Bình","result":"Huyết sắc tố giảm nặng, đề nghị bác sĩ xem lại.","values":[{"analyteId":"5c9e1a7f-3b2d-4c6e-8f0a-1d2e3f4a5b61","value":7.2,"unit":"G/L","refText":"4 - 10"},{"code":"HGB","loinc":"718-7","label":"Huyết sắc tố (HGB)","value":62,"unit":"g/L","refText":"130 - 170","flag":"critical_low"},{"code":"HBSAG","label":"HBsAg","value":"Âm tính","refText":"Âm tính"}],"resultFileIds":["9b2f4c1e-0a7d-4e3b-8f21-5c6d7e8f9a01"]}'
{ "code": "LAB-000045", "status": "received", "kind": "test", "partnerName": "Xưởng xét nghiệm Việt Lab", "patientCode": "KH-000123", "patientName": null, "sex": "male", "ageYears": 46, "subjectLabel": null, "encounterCode": "PK-000210", "sampleType": "Máu toàn phần", "testCategory": "Huyết học", "note": "Lấy máu lúc 7 giờ, khách chưa ăn sáng", "dueDate": "2026-11-18", "sampleTryDate": null, "sampleReceiveDate": null, "sentAt": "2026-11-17T07:30:00.000Z", "processingAt": "2026-11-17T09:05:00.000Z", "tryInAt": null, "receivedAt": "2026-11-17T15:40:00.000Z", "completedAt": null, "canEdit": true, "resultPdfRequired": false, "items": [ { "id": "0b7d3c52-6f1e-4a9b-9c2d-8e5f4a3b2c11", "label": "Công thức máu", "serviceCode": "XN-CTM", "labProductCode": null, "quantity": 1, "unit": "Lần", "positions": [], "details": [], "result": "Huyết sắc tố giảm nặng, đề nghị bác sĩ xem lại.", "resultFileIds": [ "9b2f4c1e-0a7d-4e3b-8f21-5c6d7e8f9a01" ], "abnormal": true, "resultedAt": "2026-11-17T15:40:00.000Z", "resultedByName": "KTV Trần Bình", "valuesAccepted": true, "editable": true, "analytes": [ { "id": "5c9e1a7f-3b2d-4c6e-8f0a-1d2e3f4a5b61", "key": "wbc", "label": "Bạch cầu (WBC)", "valueKind": "numeric", "unit": "G/L", "decimals": 1, "choices": [], "refRanges": [ { "low": 4, "high": 10 } ], "loincCode": "6690-2" } ], "values": [ { "analyteId": "5c9e1a7f-3b2d-4c6e-8f0a-1d2e3f4a5b61", "label": "Bạch cầu (WBC)", "value": 7.2, "unit": "G/L", "refText": "4 - 10", "flag": null }, { "label": "Huyết sắc tố (HGB)", "value": 62, "unit": "g/L", "refText": "130 - 170", "flag": "critical_low" }, { "label": "HBsAg", "value": "Âm tính", "unit": null, "refText": "Âm tính", "flag": null } ] } ] }
Các trường trả về64
| Tên trường | Kiểu | Mô tả |
|---|---|---|
code | string | Mã đơn labo, dùng ở mọi đường dẫn /orders/{code}. |
status | enum | Trạng thái đơn: sent đã gửi mẫu, processing đang phân tích, try_in thử mẫu, received đã có kết quả, completed phòng khám đã hoàn tất, cancelled đã huỷ.Giá trị: sentprocessingtry_inreceivedcompletedcancelled |
kind | enum | test là đơn xét nghiệm, product là đơn gia công sản phẩm.Giá trị: producttest |
partnerName | string | Tên xưởng labo nhận đơn (chính xưởng của khoá). |
patientCode | stringCó thể trống | Mã khách của phòng khám, in lên phiếu kết quả để đối chiếu. |
patientName | stringCó thể trống | Họ tên khách. Luôn null trừ khi phòng khám bật Gửi họ tên khách cho xưởng. |
sex | stringCó thể trống | Giới tính, để chọn khoảng tham chiếu. |
ageYears | numberCó thể trống | Tuổi tính theo năm, để chọn khoảng tham chiếu. |
subjectLabel | stringCó thể trống | Đối tượng lấy mẫu theo chuyên khoa của phòng khám, có thể trống. |
encounterCode | stringCó thể trống | Mã phiếu khám đã chỉ định, có thể trống. |
sampleType | string | Loại mẫu (máu toàn phần, huyết thanh...). |
testCategory | string | Nhóm xét nghiệm. |
note | stringCó thể trống | Ghi chú của phòng khám gửi xưởng. |
dueDate | dateCó thể trống | Ngày hẹn trả kết quả, hay ngày hẹn giao thành phẩm với đơn sản phẩm. |
sampleTryDate | dateCó thể trống | Đơn sản phẩm: ngày hẹn thử mẫu trên khách. |
sampleReceiveDate | dateCó thể trống | Đơn sản phẩm: ngày hẹn nhận thành phẩm. |
sentAt | date-time | Lúc phòng khám gửi đơn. |
processingAt | date-timeCó thể trống | Lúc chuyển Đang phân tích. |
tryInAt | date-timeCó thể trống | Đơn sản phẩm: lúc chuyển Thử mẫu. |
receivedAt | date-timeCó thể trống | Lúc có đủ kết quả. |
completedAt | date-timeCó thể trống | Lúc phòng khám hoàn tất đơn. |
canEdit | boolean | false khi đơn đã hoàn tất: không cập nhật, không gửi kết quả được nữa. |
resultPdfRequired | boolean | Phòng khám bắt buộc kèm tệp PDF kết quả: lượt gửi kết quả không có tệp PDF trả 422. |
items | array | Các dòng của đơn: xét nghiệm với đơn test, sản phẩm với đơn product. |
items[].id | uuid | Mã dòng, dùng ở /orders/{code}/items/{itemId}/result. |
items[].label | string | Tên xét nghiệm. |
items[].serviceCode | stringCó thể trống | Mã dịch vụ của phòng khám. |
items[].labProductCode | stringCó thể trống | Mã sản phẩm labo của phòng khám (dòng sản phẩm). null với dòng xét nghiệm: chỉ dòng xét nghiệm nhận kết quả. |
items[].quantity | integer | Số lượng. |
items[].unit | stringCó thể trống | Đơn vị tính của dòng. |
items[].positions | array | Vị trí của dòng. Nha khoa là số răng FDI, như 11, 21. |
items[].details | array | Thông số của dòng sản phẩm do phòng khám ghi, như Màu, Cầu. Mỗi mục có key, label, value. |
items[].details[].key | string | |
items[].details[].label | string | |
items[].details[].value | string | |
items[].result | stringCó thể trống | Kết quả dạng chữ đã gửi. |
items[].resultFileIds | array | Các tệp kết quả đã đính. |
items[].abnormal | booleanCó thể trống | Kết quả bất thường. |
items[].resultedAt | date-timeCó thể trống | Lúc có kết quả. |
items[].resultedByName | stringCó thể trống | Kỹ thuật viên đã gửi kết quả. |
items[].valuesAccepted | boolean | true thì dòng lưu kết quả theo từng chỉ số. false (thú y, dòng ghi tay) thì values gửi lên được dựng thành kết quả chữ, mỗi chỉ số một dòng. |
items[].editable | boolean | false khi không còn gửi hay sửa kết quả được (hồ sơ đã ký số, đơn đã đóng). |
items[].analytes | array | Bảng chỉ số phòng khám khai cho xét nghiệm này. Thường trống khi phòng khám không khai: khi đó gửi chỉ số theo code và label của labo. |
items[].analytes[].id | uuid | Gửi lại trong values[].analyteId để kết quả vào đúng chỉ số. |
items[].analytes[].key | string | Khoá chỉ số của phòng khám. |
items[].analytes[].label | string | Tên chỉ số. |
items[].analytes[].valueKind | enum | numeric gửi số, choice gửi một trong choices, text gửi chữ.Giá trị: numericchoicetext |
items[].analytes[].unit | stringCó thể trống | Đơn vị của chỉ số. |
items[].analytes[].decimals | integer | Số chữ số thập phân hiển thị. |
items[].analytes[].choices | array | Các lựa chọn khi valueKind là choice. |
items[].analytes[].refRanges | array | Khoảng tham chiếu theo giới tính và tuổi. |
items[].analytes[].refRanges[].sex | enum | Giá trị: malefemale |
items[].analytes[].refRanges[].ageMinYears | number | |
items[].analytes[].refRanges[].ageMaxYears | number | |
items[].analytes[].refRanges[].low | number | |
items[].analytes[].refRanges[].high | number | |
items[].analytes[].loincCode | stringCó thể trống | Mã LOINC nếu phòng khám đã khai. |
items[].values | array | Các giá trị đã có, để phần mềm labo hiện lại và sửa. |
items[].values[].analyteId | uuid | |
items[].values[].label | string | |
items[].values[].value | number | string | |
items[].values[].unit | stringCó thể trống | |
items[].values[].refText | stringCó thể trống | |
items[].values[].flag | enumCó thể trống | Giá trị: normallowhighabnormalcritical_lowcritical_high |
Xin vé tải tệp kết quả
PUT thân là nội dung tệp tới uploadUrl, header Content-Type đúng mimeType đã khai, không gửi token (ví dụ curl -X PUT -H 'Content-Type: application/pdf' --data-binary @ket-qua.pdf "$UPLOAD_URL"). Bước 3: gọi Hoàn tất tải tệp. Nhận PDF, JPEG, PNG./orders/{code}/filesTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
code | Đường dẫn | string | Bắt buộc | Mã đơn labo (items[].code của danh sách đơn, data.orderCode của webhook, hoặc mã in và mã vạch trên phiếu giao nhận mẫu). Không phân biệt chữ hoa thường. |
Nội dung gửi
| Tên trường | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|
mimeType | string | Bắt buộc | Loại tệp: application/pdf, image/jpeg hoặc image/png. |
sizeBytes | integer | Bắt buộc | Dung lượng tệp (byte). |
originalFilename | string | Bắt buộc | Tên tệp. |
curl -X POST 'https://ma-phong-kham.avenix.vn/v1/lab-connect/orders/LAB-000045/files' \ -H "Authorization: Bearer $TOKEN" \ -H 'Content-Type: application/json' \ -d '{"mimeType":"application/pdf","sizeBytes":182044,"originalFilename":"ket-qua-LAB-000045.pdf"}'
{ "id": "9b2f4c1e-0a7d-4e3b-8f21-5c6d7e8f9a01", "fileId": "9b2f4c1e-0a7d-4e3b-8f21-5c6d7e8f9a01", "uploadUrl": "https://<địa chỉ tải lên có hạn>", "expiresInSeconds": 300 }
Các trường trả về4
| Tên trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | Mã tệp, dùng ở bước Hoàn tất và trong resultFileIds. |
fileId | uuid | Trùng id. |
uploadUrl | string | Địa chỉ PUT nội dung tệp, có hạn, đã ký sẵn: không gửi kèm token. |
expiresInSeconds | integer | Số giây vé còn dùng được. |
Hoàn tất tải tệp
PUT xong. Máy chủ kiểm tệp rồi mới cho dùng trong resultFileIds của lượt gửi kết quả./orders/{code}/files/{fileId}/completeTham số
| Tên trường | Vị trí | Kiểu | Bắt buộc | Mô tả |
|---|---|---|---|---|
code | Đường dẫn | string | Bắt buộc | Mã đơn labo (items[].code của danh sách đơn, data.orderCode của webhook, hoặc mã in và mã vạch trên phiếu giao nhận mẫu). Không phân biệt chữ hoa thường. |
fileId | Đường dẫn | uuid | Bắt buộc | Mã tệp trả về ở bước xin vé. |
curl -X POST 'https://ma-phong-kham.avenix.vn/v1/lab-connect/orders/LAB-000045/files/9b2f4c1e-0a7d-4e3b-8f21-5c6d7e8f9a01/complete' \ -H "Authorization: Bearer $TOKEN"
{ "id": "9b2f4c1e-0a7d-4e3b-8f21-5c6d7e8f9a01", "status": "clean", "mimeType": "application/pdf", "sizeBytes": 182044, "originalFilename": "ket-qua-LAB-000045.pdf" }
Các trường trả về5
| Tên trường | Kiểu | Mô tả |
|---|---|---|
id | uuid | Mã tệp. |
status | string | clean là tệp đã kiểm xong, dùng được. |
mimeType | string | Loại tệp. |
sizeBytes | integer | Dung lượng (byte). |
originalFilename | stringCó thể trống | Tên tệp. |
