Phần mềm đang cập nhật, quý khách vui lòng đợi trong giây lát

Trang tải lâu hơn bình thường.

Tải lại trang

AVENIX Open API

Luồng vận hành

Phòng khám và đối tácCổng API của AVENIXLưu trữPhòng khámTạo kết nối, chọn quyềnPhần mềm đối tácMáy chủ của đối tácCấp tokenOAuth 2.0, sống 1 giờKiểm tra lượt gọiToken, quyền, IP, hạn mứcXử lý nghiệp vụCùng luật với phần mềmTrả kết quảChỉ trường đã công bốWebhookBáo sự kiện, có chữ kýDữ liệu phòng khámTách riêng, có mã hoáSổ nhật kýKhông sửa, không xoáMã và bí mậtĐổi lấy tokenHTTPS kèm tokenĐạtĐọc, ghiGhi sổKết quảJSONCó sự kiện mớiBản tin có chữ kýPhòng khám và đối tácCổng API của AVENIXLưu trữPhòng khámPhần mềm đối tácCấp tokenKiểm tra lượtXử lýTrả kết quảWebhookDữ liệuSổ nhật ký
1Phòng khám cấp kết nốiPhòng khám tự tạo kết nối, chọn phần dữ liệu được mở rồi gửi mã và bí mật cho đối tác. Mặc định chưa mở gì, phòng khám thu hồi được bất cứ lúc nào.

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.

Địa chỉ gốchttps://app.avenix.vn/v1/open
  1. 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.
  2. Đổi mã và bí mật lấy token, token sống 1 giờ. Hết hạn thì lấy token mới.
  3. 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 nextCursor vào cursor để 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èm Retry-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
400Dữ liệu gửi lên không hợp lệ.
401Thiếu token, token hết hạn hoặc kết nối đã bị thu hồi.
403Token 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.
404Không tìm thấy bản ghi.
409Xung đột dữ liệu, hoặc khoá chống trùng đang được xử lý.
422Dữ liệu hợp lệ nhưng không làm được theo luật nghiệp vụ.
429Vượt giới hạn gọi. Chờ theo header Retry-After.
Mẫu lỗi
{
  "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.test vớ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

Header
webhook-id: 5f0c2a1e-7d3b-4a9e-8c21-1b6f4e2d9a10
webhook-timestamp: 1793512800
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
Nội dung
{
  "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ý

Node.js
// 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ệnMô tảPhạm viDữ liệu
customer.createdCó hồ sơ khách mớicustomers:read
id
customer.updatedHồ sơ khách đổi thông tincustomers:read
id
customer.deletedHồ sơ khách bị xoácustomers:read
id
appointment.createdCó lịch hẹn mớiappointments:read
idbranchIdcustomerIdstatus
appointment.updatedLịch hẹn đổi giờ, bác sĩ hoặc thông tin khácappointments:read
idbranchIdcustomerIdstatus
appointment.status_changedLịch hẹn đổi trạng tháiappointments:read
idbranchIdcustomerIdstatus
invoice.createdCó hoá đơn mớiinvoices:read
idbranchIdstatus
invoice.status_changedHoá đơn đổi trạng tháiinvoices:read
idbranchIdstatus
payment.createdCó phiếu thu mớiinvoices:read
idinvoiceIdbranchId
payment.refundedPhiếu thu được hoàn tiềninvoices:read
idinvoiceIdbranchId

Phạm vi quyền

Phạm viCho phép
customers:readTì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:writeTạ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:readXem chi nhánh, bác sĩ, giờ trống và lịch hẹn kèm tên khách.
appointments:writeTạ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 2.0 Client Credentials. Có thể gửi mã bằng HTTP Basic.
POST/oauth/token

Nội dung gửi

Tên trườngKiểuBắt buộcMô tả
grant_type
enum
Bắt buộcLuôn là client_credentials.
client_id
string
Bắt buộcMã kết nối phòng khám cấp, dạng avxc_....
client_secret
string
Bắt buộcBí 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
Kết quả 200
{
  "access_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "customers:read appointments:read"
}
Các trường trả về4
Tên trườngKiểuMô 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.
Mã lỗi có thể gặp:400401429

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

Trả các chi nhánh đang hoạt động mà phòng khám đã cấp cho kết nối này. Dùng 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.
GET/branches
Phạm vi cần cóappointments:read
curl -X GET 'https://app.avenix.vn/v1/open/branches' \
  -H "Authorization: Bearer $TOKEN"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:401403429

Lấy danh sách bác sĩ

Trả các bác sĩ đang hoạt động của phòng khám, gồm mã và họ tên. Dùng 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.
GET/doctors
Phạm vi cần cóappointments:read
curl -X GET 'https://app.avenix.vn/v1/open/doctors' \
  -H "Authorization: Bearer $TOKEN"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:401403429

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

Tìm hồ sơ khách theo tên hoặc mã qua 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.
GET/customers
Phạm vi cần cócustomers:read

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
qTruy vấn
string
Tìm theo tên hoặc mã, tối thiểu 2 ký tự.
phoneTruy vấn
string
Tìm theo số điện thoại đầy đủ.
limitTruy vấn
integer
Số dòng mỗi trang, từ 1 đến 100.
cursorTruy 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"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403429

Tạo khách hàng

Tạo hồ sơ mới với họ tên, số điện thoại và chi nhánh gốc, các trường khác có thể bổ sung sau. Số điện thoại đã có hồ sơ thì trả lỗi 409, nên tìm khách theo số trước khi tạo để tránh hồ sơ trùng. Hồ sơ tạo qua API hiện trong phần mềm như hồ sơ do lễ tân nhập.
POST/customers
Phạm vi cần cócustomers:write

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
Idempotency-KeyHeader
string
Bắt buộcChuỗ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ườngKiểuBắt buộcMô tả
fullName
string
Bắt buộcHọ tên.
phone
string
Bắt buộcSố điện thoại. Nhận 0901234567 hoặc +84901234567, trả về dạng E.164.
homeBranchId
uuid
Bắt buộcChi 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"}'
Kết quả 201
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403409422429

Lấy khách hàng theo mã của bạn

Tra hồ sơ bằng mã khách bên phần mềm của bạn, đã lưu qua trường 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.
GET/customers/by-external-id/{externalId}
Phạm vi cần cócustomers:read

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
externalIdĐường dẫn
string
Bắt buộcMã 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"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:401403404429

Lấy chi tiết khách hàng

Trả đầy đủ thông tin hành chính của một khách, gồm cả email. Dùng khi đã có mã khách, ví dụ sau khi nhận sự kiện webhook customer.updated.
GET/customers/{id}
Phạm vi cần cócustomers:read

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
idĐường dẫn
uuid
Bắt buộcMã bản ghi.
curl -X GET 'https://app.avenix.vn/v1/open/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H "Authorization: Bearer $TOKEN"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:401403404429

Cập nhật khách hàng

Sửa thông tin hành chính của khách: họ tên, số điện thoại, ngày sinh, giới tính, email, địa chỉ. Chỉ gửi các trường cần đổi, trường không gửi giữ nguyên. Route này không đụng tới hồ sơ bệnh án.
PATCH/customers/{id}
Phạm vi cần cócustomers:write

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
idĐường dẫn
uuid
Bắt buộcMã bản ghi.

Nội dung gửi

Tên trườngKiểuBắt buộcMô 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]"}'
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403404409422429

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

Trả các ô giờ trong một ngày của chi nhánh, mỗi ô cho biết đặt được hay không. Truyền 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.
GET/appointments/availability
Phạm vi cần cóappointments:read

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
branchIdTruy vấn
uuid
Bắt buộcChi nhánh.
doctorIdTruy vấn
uuid
Bác sĩ. Bỏ trống để xem theo giờ mở cửa.
dateTruy vấn
date
Bắt buộcNgày cần xem, dạng YYYY-MM-DD.
curl -X GET 'https://app.avenix.vn/v1/open/appointments/availability' \
  -H "Authorization: Bearer $TOKEN"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403429

Lấy danh sách lịch hẹn

Trả các lịch hẹn trong khoảng từ 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.
GET/appointments
Phạm vi cần cóappointments:read

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
fromTruy vấn
date-time
Bắt buộcTừ thời điểm.
toTruy vấn
date-time
Bắt buộcĐến thời điểm, cách from tối đa 31 ngày.
branchIdTruy vấn
uuid
Chỉ lấy một chi nhánh.
customerIdTruy vấn
uuid
Chỉ lấy một khách.
curl -X GET 'https://app.avenix.vn/v1/open/appointments' \
  -H "Authorization: Bearer $TOKEN"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403429

Tạo lịch hẹn

Đặt lịch cho một khách đã có hồ sơ tại chi nhánh được cấp. Chưa có khách thì tạo khách trước, rồi gọi route xem giờ trống để chọn giờ. Giờ ngoài lịch làm việc hoặc trùng lịch có thể bị từ chối tuỳ cấu hình của phòng khám, khi đó hiện lại danh sách giờ trống cho khách chọn.
POST/appointments
Phạm vi cần cóappointments:write

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
Idempotency-KeyHeader
string
Bắt buộcChuỗ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ườngKiểuBắt buộcMô tả
branchId
uuid
Bắt buộcChi nhánh, phải thuộc các chi nhánh kết nối được cấp.
customerId
uuid
Bắt buộcKhách hàng.
doctorId
uuid
Bác sĩ.
startsAt
date-time
Bắt buộcGiờ bắt đầu.
endsAt
date-time
Bắt buộcGiờ 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"}'
Kết quả 201
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403409422429

Lấy chi tiết lịch hẹn

Trả một lịch hẹn kèm trạng thái hiện tại, khách và bác sĩ. Dùng để đọc lại lịch sau khi nhận sự kiện webhook appointment.updated hoặc appointment.status_changed.
GET/appointments/{id}
Phạm vi cần cóappointments:read

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
idĐường dẫn
uuid
Bắt buộcMã bản ghi.
curl -X GET 'https://app.avenix.vn/v1/open/appointments/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H "Authorization: Bearer $TOKEN"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:401403404429

Cập nhật lịch hẹn

Đổi giờ hẹn, có thể đổi luôn bác sĩ. Phải gửi đủ giờ bắt đầu và giờ kết thúc mới. Chỉ đổi được lịch chưa tới trạng thái khách đã đến, lịch đã qua bước đó bị từ chối.
PATCH/appointments/{id}
Phạm vi cần cóappointments:write

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
idĐường dẫn
uuid
Bắt buộcMã bản ghi.

Nội dung gửi

Tên trườngKiểuBắt buộcMô tả
startsAt
date-time
Bắt buộcGiờ bắt đầu mới.
endsAt
date-time
Bắt buộcGiờ 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"}'
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403404409422429

Huỷ lịch hẹn

Huỷ lịch hẹn, có thể kèm lý do. Gọi lại với lịch đã huỷ vẫn trả về lịch đó nên thử lại khi đứt mạng là an toàn.
POST/appointments/{id}/cancel
Phạm vi cần cóappointments:write

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
idĐường dẫn
uuid
Bắt buộcMã bản ghi.

Nội dung gửi

Tên trườngKiểuBắt buộcMô 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"}'
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403404409422429

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

Đưa khách từ form, landing page hoặc phần mềm khác vào màn Cơ hội của phòng khám để đội tư vấn liên hệ. Cơ hội vào phễu Khách tiềm năng, chưa phân công người phụ trách. Nội dung 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.
POST/leads
Phạm vi cần cóleads:write

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
Idempotency-KeyHeader
string
Bắt buộcChuỗ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ườngKiểuBắt buộcMô tả
fullName
string
Bắt buộcHọ tên khách.
phone
string
Bắt buộcSố đ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"}'
Kết quả 201
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code": "KH-00012"
}
Các trường trả về2
Tên trườngKiểuMô tả
id
uuid
Mã cơ hội.
code
stringCó thể trống
Mã ngắn hiện trong phần mềm.
Mã lỗi có thể gặp:400401403409422429

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ụ

Trả bảng giá dịch vụ đang bán: mã, tên, nhóm, đơn vị tính, giá, thời lượng, thuế suất, mã kỹ thuật, số bước tiến trình, bảo hành. Giá vốn chỉ có khi token mang phạm vi 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.
GET/services
Phạm vi cần cócatalog:read

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
qTruy vấn
string
Tìm theo tên hoặc mã.
limitTruy vấn
integer
Số dòng mỗi trang, từ 1 đến 100.
cursorTruy vấn
string
Giá trị nextCursor của trang trước. Bỏ trống để lấy trang đầu.
categoryTruy 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"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403429

Lấy danh sách hàng hoá

Trả hàng hoá đang bán: mã, tên, nhóm, hãng, đơn vị tính, giá theo từng đơn vị, mã vạch, thuế suất, hoạt chất, hướng dẫn dùng, bảo hành. Giá vốn chỉ có khi token mang phạm vi 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.
GET/products
Phạm vi cần cócatalog:read

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
qTruy vấn
string
Tìm theo tên hoặc mã.
limitTruy vấn
integer
Số dòng mỗi trang, từ 1 đến 100.
cursorTruy vấn
string
Giá trị nextCursor của trang trước. Bỏ trống để lấy trang đầu.
categoryTruy vấn
enum
Chỉ lấy một loại hàng.
Giá trị:productconsumablevaccinemedication
groupIdTruy vấn
uuid
Chỉ lấy một nhóm hàng.
manufacturerIdTruy vấn
uuid
Chỉ lấy một hãng.
curl -X GET 'https://app.avenix.vn/v1/open/products' \
  -H "Authorization: Bearer $TOKEN"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403429

Lấy danh mục nhóm dịch vụ

Trả các nhóm đang có dịch vụ bán, tên theo cách phòng khám đặt. Dùng 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.
GET/service-categories
Phạm vi cần cócatalog:read
curl -X GET 'https://app.avenix.vn/v1/open/service-categories' \
  -H "Authorization: Bearer $TOKEN"
Kết quả 200
{
  "data": [
    {
      "key": "string",
      "name": "Chi nhánh Quận 1"
    }
  ]
}
Các trường trả về3
Tên trườngKiểuMô 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.
Mã lỗi có thể gặp:401403429

Lấy danh mục nhóm hàng hoá

Trả các nhóm hàng đang dùng, theo thứ tự phòng khám sắp. Dùng id để lọc danh sách hàng hoá qua tham số groupId.
GET/product-groups
Phạm vi cần cócatalog:read
curl -X GET 'https://app.avenix.vn/v1/open/product-groups' \
  -H "Authorization: Bearer $TOKEN"
Kết quả 200
{
  "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ườngKiểuMô 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ả.
Mã lỗi có thể gặp:401403429

Lấy danh sách hãng sản xuất

Trả các hãng đang dùng. Dùng id để lọc danh sách hàng hoá qua tham số manufacturerId.
GET/manufacturers
Phạm vi cần cócatalog:read
curl -X GET 'https://app.avenix.vn/v1/open/manufacturers' \
  -H "Authorization: Bearer $TOKEN"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:401403429

Lấy danh sách nhà cung cấp

Trả các nhà cung cấp đang dùng kèm mã số thuế và người liên hệ. Hàng hoá không gắn cố định với một nhà cung cấp: muốn biết món hàng nhập từ đâu thì đọc 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.
GET/suppliers
Phạm vi cần cósuppliers:read

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
qTruy vấn
string
Tìm theo tên, mã số thuế hoặc mã.
limitTruy vấn
integer
Số dòng mỗi trang, từ 1 đến 100.
cursorTruy 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"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403429

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

Trả các hoá đơn lập trong khoảng từ 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.
GET/invoices
Phạm vi cần cóinvoices:read

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
fromTruy vấn
date-time
Bắt buộcLập từ thời điểm.
toTruy vấn
date-time
Bắt buộcLập đến thời điểm, cách from tối đa 366 ngày.
branchIdTruy vấn
uuid
Chỉ lấy một chi nhánh.
customerIdTruy vấn
uuid
Chỉ lấy một khách.
statusTruy vấn
enum
Chỉ lấy một trạng thái.
Giá trị:draftissuedpartially_paidpaidvoidedrefunded
limitTruy vấn
integer
Số dòng mỗi trang, từ 1 đến 100.
cursorTruy 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"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403429

Lấy chi tiết hoá đơn

Trả một hoá đơn kèm từng dòng hàng và các phiếu thu, đủ để đưa sang phần mềm kế toá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.
GET/invoices/{id}
Phạm vi cần cóinvoices:read

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
idĐường dẫn
uuid
Bắt buộcMã bản ghi.
curl -X GET 'https://app.avenix.vn/v1/open/invoices/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H "Authorization: Bearer $TOKEN"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:401403404429

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.

Địa chỉ gốchttps://ma-phong-kham.avenix.vn/v1/lab-connect

Mỗ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ạng avxls_....
  • 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ối 401.
  • 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ả 404 như 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á

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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

  1. Đổi mã và bí mật lấy token ở POST /oauth/token, dùng tới gần hết expires_in rồi xin lại.
  2. Biết đơn mới: nhận webhook lab_order.created, hoặc vài phút gọi GET /orders?updatedSince=... một lần.
  3. 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.
  4. Nhận mẫu thì gọi PATCH /orders/{code} với status là processing; có ngày trả thì gửi dueDate.
  5. Có tệp PDF kết quả thì tải lên qua /orders/{code}/files trước để lấy mã tệp.
  6. Gửi kết quả từng dòng ở POST /orders/{code}/items/{itemId}/result kèm Idempotency-Key. Đủ mọi dòng thì đơn tự sang Đã có kết quả và bác sĩ nhận thông báo.
  7. Nhận webhook lab_order.cancelled, hoặc thấy status là cancelled ở danh sách đơn, thì dừng làm đơn đó: đơn đã huỷ đọc chi tiết trả 404. Đơn completed là 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-000123 vẫn ra đơn LAB-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 analyteId lấy từ items[].analytes[].id là cách chắc nhất.
  • Phần mềm labo chỉ có mã của mình thì gửi code, kèm loinc và label nế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, refText là đủ, 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ó valuesAccepted là false (thú y, dòng ghi tay) vẫn nhận values: 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 refText là 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ính mà 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èm flag là abnormal hoặc normal.
  • Mức nguy hiểm chỉ có khi labo gửi flag là critical_low hoặc critical_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ó kind là product là đơ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}: processing khi bắt đầu làm, try_in khi giao mẫu thử cho phòng khám, phòng khám báo thử chưa đạt thì về processing, received khi giao thành phẩm.
  • try_in chỉ 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

  1. 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ử.
  2. 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.
  3. Phần mềm labo lấy token, thấy đơn ở GET /orders, đọc chi tiết, chuyển processing, gửi kết quả cho một dòng.
  4. 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ý

  1. Bên làm phần mềm labo dựng một địa chỉ https công khai nhận POST JSON, ví dụ https://lis.xuong-labo.vn/avenix/webhook, rồi gửi địa chỉ đó cho phòng khám.
  2. 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.
  3. 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.
  4. 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ả 410 thì 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 qua GET /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 sau whsec_ giải mã base64, kết quả base64 đứng sau v1,. Mã kiểm mẫu ở dưới.

Mẫu bản tin

Header
webhook-id: 7c1e9f3a-2b4d-4e8a-9f10-3d5c6b7a8e21
webhook-timestamp: 1794900600
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=
Nội dung
{
  "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ý

Node.js
// 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ệnMô tả
lab_order.createdPhòng khám gửi đơn mới cho xưởng
lab_order.cancelledPhò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.

Lỗi nghiệp vụ
{
  "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"
}
Lỗi lấy token
{
  "error": "invalid_client",
  "error_description": "Mã kết nối hoặc bí mật không đúng"
}
MãÝ nghĩa
400Dữ liệu gửi lên không hợp lệ, hoặc thiếu header Idempotency-Key.
401Thiếu token, token hết hạn, hoặc khoá đã bị tắt hay đổi. Token Open API không dùng được ở đây.
403Gọ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.
404Không có đơn này, đơn không gửi cho xưởng của khoá, hoặc đơn đã huỷ.
409Phò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ả.
422Khô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.
429Vượ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

OAuth 2.0 Client Credentials. Gửi thân dạng form, JSON, hoặc mã và bí mật bằng HTTP Basic. Token sống 1 giờ, hết hạn thì xin lại, không có refresh token. Sai mã, sai bí mật, khoá đã tắt hay IP ngoài danh sách đều trả cùng một lỗi invalid_client.
POST/oauth/token

Nội dung gửi

Tên trườngKiểuBắt buộcMô tả
grant_type
enum
Bắt buộcLuôn là client_credentials.
client_id
string
Bắt buộcMã kết nối, dạng avxl_....
client_secret
string
Bắt buộcBí 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
Kết quả 200
{
  "access_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 3600
}
Các trường trả về3
Tên trườngKiểuMô 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.
Mã lỗi có thể gặp:400401429

Danh sách đơn

Các đơn phòng khám gửi cho xưởng của khoá, mới gửi trước. Chỉ có mã và trạng thái, gọi Một đơn để lấy chi tiết. Không cấu hình webhook thì gọi định kỳ với updatedSince để biết đơn mới.
GET/orders

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
statusTruy 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).
updatedSinceTruy 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.
cursorTruy vấn
string
Giá trị nextCursor của trang trước. Bỏ trống để lấy trang đầu.
limitTruy 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"
Kết quả 200
{
  "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ườngKiểuMô 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ã lỗi có thể gặp:400401403422429

Một đơn

Chi tiết đơn: mẫu, các dòng xét nghiệm, bảng chỉ số kèm đơn vị và khoảng tham chiếu, mã khách, giới tính, tuổi. Không bao giờ có số điện thoại, địa chỉ, giấy tờ, chẩn đoán hay tiền. Mỗi lượt xem được ghi vào nhật ký của phòng khám. Có thể có thêm trường không liệt kê ở đây, hãy bỏ qua trường không biết.
GET/orders/{code}

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
codeĐường dẫn
string
Bắt buộcMã đơ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"
Kết quả 200
{
  "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ườngKiểuMô 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
Mã lỗi có thể gặp:401403404429

Cập nhật trạng thái, hẹn trả

Báo phòng khám đơn đang làm, đang thử mẫu hay đã xong, hoặc đổi ngày hẹn trả. Đơn xét nghiệm: chuyển 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.
PATCH/orders/{code}

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
codeĐường dẫn
string
Bắt buộcMã đơ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ườngKiểuBắt buộcMô tả
technicianName
string
Bắt buộcTê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"}'
Kết quả 200
{
  "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ườngKiểuMô 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
Mã lỗi có thể gặp:400401403404409422429

Gửi kết quả một dòng

Kết quả tự ghi vào phiếu khám và báo bác sĩ như khi labo nhập qua mã QR; máy chủ tự tính cờ cao thấp. Gửi lại cù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ả.
POST/orders/{code}/items/{itemId}/result

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
codeĐường dẫn
string
Bắt buộcMã đơ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ộcMã dòng lấy từ items[].id.
Idempotency-KeyHeader
string
Bắt buộcChuỗ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ườngKiểuBắt buộcMô tả
technicianName
string
Bắt buộcTê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ộcSố 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"]}'
Kết quả 200
{
  "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ườngKiểuMô 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
Mã lỗi có thể gặp:400401403404409422429

Xin vé tải tệp kết quả

Bước 1 của tải tệp: nhận địa chỉ tải lên có hạn (5 phút). Bước 2: gửi 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.
POST/orders/{code}/files

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
codeĐường dẫn
string
Bắt buộcMã đơ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ườngKiểuBắt buộcMô tả
mimeType
string
Bắt buộcLoại tệp: application/pdf, image/jpeg hoặc image/png.
sizeBytes
integer
Bắt buộcDung lượng tệp (byte).
originalFilename
string
Bắt buộcTê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"}'
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:400401403404409422429

Hoàn tất tải tệp

Gọi sau khi 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ả.
POST/orders/{code}/files/{fileId}/complete

Tham số

Tên trườngVị tríKiểuBắt buộcMô tả
codeĐường dẫn
string
Bắt buộcMã đơ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ộcMã 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"
Kết quả 200
{
  "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ườngKiểuMô 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.
Mã lỗi có thể gặp:401403404409422429
Hướng dẫn kết nối API với AVENIX | Tài liệu Open API | AVENIX Clinic