AVENIX Open API

Luồng vận hành

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

Phòng khám vào Cài đặt, mục Kết nối API, tạo kết nối rồi gửi mã và bí mật cho bạn. Mỗi phòng khám một kết nối riêng.
Đổi mã và bí mật lấy token, token sống 1 giờ. Hết hạn thì lấy token mới.
Gửi token trong header Authorization ở mỗi lượt gọi. Chỉ gọi từ máy chủ của bạn, đừng để bí mật trong ứng dụng hay trình duyệt.

curl -X POST 'https://app.avenix.vn/v1/open/oauth/token' \
  -d grant_type=client_credentials \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET

Dùng AI lập trình thì bấm Sao chép cho AI ở đầu trang để lấy toàn bộ tài liệu rồi dán vào khung chat, hoặc ở từng route khi chỉ cần một việc. Dùng Postman thì bấm Tải về rồi chọn Tệp OpenAPI.

Quy ước

Tạo mới: gửi kèm header Idempotency-Key. Gửi lại cùng khoá trong 24 giờ nhận lại đúng kết quả cũ, không tạo trùng.
Danh sách: truyền 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
`400`	Dữ liệu gửi lên không hợp lệ.
`401`	Thiếu token, token hết hạn hoặc kết nối đã bị thu hồi.
`403`	Token không có phạm vi này, ngoài chi nhánh được cấp, hoặc gói chưa có tính năng.
`404`	Không tìm thấy bản ghi.
`409`	Xung đột dữ liệu, hoặc khoá chống trùng đang được xử lý.
`422`	Dữ liệu hợp lệ nhưng không làm được theo luật nghiệp vụ.
`429`	Vượt giới hạn gọi. Chờ theo header `Retry-After`.

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ện	Mô tả	Phạm vi	Dữ liệu
`customer.created`	Có hồ sơ khách mới	`customers:read`	`id`
`customer.updated`	Hồ sơ khách đổi thông tin	`customers:read`	`id`
`customer.deleted`	Hồ sơ khách bị xoá	`customers:read`	`id`
`appointment.created`	Có lịch hẹn mới	`appointments:read`	`idbranchIdcustomerIdstatus`
`appointment.updated`	Lịch hẹn đổi giờ, bác sĩ hoặc thông tin khác	`appointments:read`	`idbranchIdcustomerIdstatus`
`appointment.status_changed`	Lịch hẹn đổi trạng thái	`appointments:read`	`idbranchIdcustomerIdstatus`
`invoice.created`	Có hoá đơn mới	`invoices:read`	`idbranchIdstatus`
`invoice.status_changed`	Hoá đơn đổi trạng thái	`invoices:read`	`idbranchIdstatus`
`payment.created`	Có phiếu thu mới	`invoices:read`	`idinvoiceIdbranchId`
`payment.refunded`	Phiếu thu được hoàn tiền	`invoices:read`	`idinvoiceIdbranchId`

Phạm vi quyền

Phạm vi	Cho phép
`customers:read`	Tìm và xem thông tin hành chính của khách: họ tên, số điện thoại, email, địa chỉ, nghề nghiệp, người liên hệ.
`customers:write`	Tạo hồ sơ khách mới và sửa thông tin hành chính.
`customers:identity`	Đọc và ghi số CCCD, hộ chiếu, CCCD người giám hộ, thẻ BHYT. Đi kèm phạm vi xem hoặc sửa khách.
`appointments:read`	Xem chi nhánh, bác sĩ, giờ trống và lịch hẹn kèm tên khách.
`appointments:write`	Tạo lịch hẹn, đổi giờ và huỷ lịch hẹn.
`leads:write`	Đưa khách từ form, landing page của đối tác vào phễu Khách tiềm năng.
`catalog:read`	Đọc tên, giá bán và thông tin của dịch vụ, hàng hoá. Không có giá vốn, không có tồn kho.
`catalog:cost`	Đọc giá vốn của dịch vụ và hàng hoá. Đi kèm phạm vi xem dịch vụ, hàng hoá.
`suppliers:read`	Đọc danh sách nhà cung cấp kèm người liên hệ, và nhà cung cấp của lần nhập gần nhất trên từng hàng hoá.
`invoices:read`	Đọc hoá đơn, dòng hàng, số tiền và phiếu thu để đưa sang phần mềm kế toán.

Xác thực

Mọi lượt gọi API đều cần token. Token đổi từ mã kết nối và bí mật do phòng khám cấp, theo chuẩn OAuth 2.0 Client Credentials, không gắn với tài khoản nhân viên nào. Quyền của token là các phạm vi phòng khám đã tích khi tạo kết nối, phòng khám thu hồi kết nối thì token ngừng hoạt động ngay.

Dùng khi

Máy chủ của bạn khởi động và cần token đầu tiên.
Token hết hạn: lưu lại dùng tới khi hết hạn, đừng xin token mới cho từng lượt gọi vì route này giới hạn 30 lượt mỗi phút.

Lấy token truy cập

OAuth 2.0 Client Credentials. Có thể gửi mã bằng HTTP Basic.

POST/oauth/token

Nội dung gửi

Tên trường	Kiểu	Bắt buộc	Mô tả
`grant_type`	`enum`	Bắt buộc	Luôn là `client_credentials`.
`client_id`	`string`	Bắt buộc	Mã kết nối phòng khám cấp, dạng `avxc_...`.
`client_secret`	`string`	Bắt buộc	Bí mật của kết nối, dạng `avxs_...`.
`scope`	`string`		Các phạm vi muốn dùng, ngăn bằng dấu cách. Bỏ trống để lấy mọi phạm vi của kết nối.

curl -X POST 'https://app.avenix.vn/v1/open/oauth/token' \
  -d grant_type=client_credentials \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET

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ường	Kiểu	Mô tả
`access_token`	`string`	Token gửi trong header `Authorization: Bearer`.
`token_type`	`enum`	Luôn là `Bearer`.
`expires_in`	`integer`	Số giây token còn hiệu lực.
`scope`	`string`	Các phạm vi token mang, ngăn bằng dấu cách.

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ường	Kiểu	Mô tả
`data`	`array`	Các dòng của trang này.
`data[].id`	`uuid`	Mã chi nhánh.
`data[].code`	`string`	Mã ngắn của chi nhánh.
`data[].name`	`string`	Tên chi nhánh.
`data[].province`	`string`Có thể trống	Tỉnh, thành phố.
`data[].ward`	`string`Có thể trống	Phường, xã.
`data[].streetAddress`	`string`Có thể trống	Số nhà, tên đường.
`data[].phone`	`string`Có thể trống	Số điện thoại chi nhánh.
`data[].email`	`string`Có thể trống	Email chi nhánh.
`data[].taxCode`	`string`Có thể trống	Mã số thuế.
`data[].googleMapUrl`	`string`Có thể trống	Đường dẫn Google Maps.
`data[].latitude`	`number`Có thể trống	Vĩ độ.
`data[].longitude`	`number`Có thể trống	Kinh độ.
`data[].directorName`	`string`Có thể trống	Người phụ trách cơ sở.
`data[].operatingLicenseNo`	`string`Có 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ường	Kiểu	Mô tả
`data`	`array`	Các dòng của trang này.
`data[].id`	`uuid`	Mã bác sĩ.
`data[].fullName`	`string`	Họ tên bác sĩ.
`data[].jobTitle`	`string`Có 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ường	Vị trí	Kiểu	Mô tả
`q`	Truy vấn	`string`	Tìm theo tên hoặc mã, tối thiểu 2 ký tự.
`phone`	Truy vấn	`string`	Tìm theo số điện thoại đầy đủ.
`limit`	Truy vấn	`integer`	Số dòng mỗi trang, từ 1 đến 100.
`cursor`	Truy vấn	`string`	Giá trị `nextCursor` của trang trước. Bỏ trống để lấy trang đầu.

curl -X GET 'https://app.avenix.vn/v1/open/customers' \
  -H "Authorization: Bearer $TOKEN"

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ường	Kiểu	Mô tả
`data`	`array`	Các dòng của trang này.
`data[].id`	`uuid`	Mã khách hàng.
`data[].code`	`string`	Mã ngắn hiện trong phần mềm.
`data[].fullName`	`string`	Họ tên.
`data[].dateOfBirth`	`date`Có thể trống	Ngày sinh, dạng YYYY-MM-DD.
`data[].gender`	`enum`Có thể trống	Giới tính. Giá trị:`malefemaleother`
`data[].phone`	`string`Có thể trống	Số điện thoại chính theo chuẩn E.164, ví dụ +84901234567.
`data[].email`	`string`Có thể trống	Email. Chỉ có khi xem một khách.
`data[].province`	`string`Có thể trống	Tỉnh, thành phố.
`data[].ward`	`string`Có thể trống	Phường, xã.
`data[].streetAddress`	`string`Có 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-time`Có thể trống	Thời điểm sửa gần nhất. Chỉ có khi xem một khách.
`data[].externalId`	`string`Có thể trống	Mã khách phía phần mềm của bạn.
`data[].country`	`string`Có thể trống	Mã quốc gia ISO của địa chỉ, trống là Việt Nam.
`data[].city`	`string`Có thể trống	Thành phố, khi khách ở nước ngoài.
`data[].region`	`string`Có thể trống	Bang hoặc vùng, khi khách ở nước ngoài.
`data[].isVip`	`boolean`	Khách VIP.
`data[].referralSourceId`	`string`Có 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-time`Có 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`	`string`Có thể trống	Dân tộc. Chỉ có khi xem một khách.
`data[].occupation`	`string`Có thể trống	Nghề nghiệp. Chỉ có khi xem một khách.
`data[].occupationCode`	`string`Có thể trống	Mã nghề theo danh mục khám sức khoẻ. Chỉ có khi xem một khách.
`data[].workplace`	`string`Có thể trống	Nơi làm việc. Chỉ có khi xem một khách.
`data[].bloodGroup`	`string`Có thể trống	Nhóm máu. Chỉ có khi xem một khách.
`data[].rhFactor`	`string`Có thể trống	Yếu tố Rh. Chỉ có khi xem một khách.
`data[].patientType`	`string`Có thể trống	Hình thức khám. Chỉ có khi xem một khách.
`data[].healthCheckSubject`	`string`Có 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`	`string`Có thể trống	Người liên hệ khẩn cấp. Chỉ có khi xem một khách.
`data[].emergencyContactRelation`	`string`Có thể trống	Quan hệ với khách. Chỉ có khi xem một khách.
`data[].emergencyContactPhone`	`string`Có thể trống	Số điện thoại người liên hệ. Chỉ có khi xem một khách.
`data[].note`	`string`Có 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`	`string`Có 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`	`string`Có 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`	`string`Có 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`	`string`Có thể trống	Số thẻ BHYT. Chỉ có khi xem một khách và token mang phạm vi `customers:identity`.
`data[].bhytRegFacilityCode`	`string`Có 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`	`string`Có 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`	`string`Có 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`	`string`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`Idempotency-Key`	Header	`string`	Bắt buộc	Chuỗi ngẫu nhiên cho mỗi việc. Gửi lại cùng khoá trong 24 giờ thì không tạo trùng.

Nội dung gửi

Tên trường	Kiểu	Bắt buộc	Mô tả
`fullName`	`string`	Bắt buộc	Họ tên.
`phone`	`string`	Bắt buộc	Số điện thoại. Nhận 0901234567 hoặc +84901234567, trả về dạng E.164.
`homeBranchId`	`uuid`	Bắt buộc	Chi nhánh gốc, phải thuộc các chi nhánh kết nối được cấp.
`dateOfBirth`	`date`		Ngày sinh, dạng YYYY-MM-DD.
`gender`	`enum`		Giới tính. Giá trị:`malefemaleother`
`email`	`email`		Email.
`province`	`string`		Tỉnh, thành phố.
`ward`	`string`		Phường, xã.
`streetAddress`	`string`		Số nhà, tên đường.
`country`	`string`		Mã quốc gia ISO, ví dụ `sg`. Bỏ trống là Việt Nam.
`city`	`string`		Thành phố, bắt buộc khi ở nước ngoài.
`region`	`string`		Bang hoặc vùng ở nước ngoài.
`extraPhones`	`array`		Các số điện thoại thêm. Gửi cả bộ.
`note`	`string`		Ghi chú cho phòng khám.
`referralSourceId`	`string`		Nguồn khách theo danh mục của phòng khám.
`isVip`	`boolean`		Khách VIP.
`ethnicity`	`string`		Dân tộc.
`occupation`	`string`		Nghề nghiệp.
`occupationCode`	`string`		Mã nghề theo danh mục khám sức khoẻ.
`workplace`	`string`		Nơi làm việc.
`bloodGroup`	`enum`		Nhóm máu. Giá trị:`ABABO`
`rhFactor`	`enum`		Yếu tố Rh. Giá trị:`+-`
`patientType`	`enum`		Hình thức khám. Giá trị:`servicebhythealth_checkfree`
`healthCheckSubject`	`string`		Đối tượng khám sức khoẻ theo danh mục Sở Y tế.
`emergencyContactName`	`string`		Người liên hệ khẩn cấp.
`emergencyContactRelation`	`string`		Quan hệ với khách.
`emergencyContactPhone`	`string`		Số điện thoại người liên hệ.
`externalId`	`string`		Mã khách phía phần mềm của bạn, không trùng trong một kết nối.
`nationalId`	`string`		Số CCCD, phải khớp ngày sinh và giới tính. Cần phạm vi `customers:identity`.
`passportNo`	`string`		Số hộ chiếu. Cần phạm vi `customers:identity`.
`guardianNationalId`	`string`		CCCD người giám hộ. Cần phạm vi `customers:identity`.
`bhytCode`	`string`		Số thẻ BHYT. Cần phạm vi `customers:identity`.
`bhytRegFacilityCode`	`string`		Nơi đăng ký khám chữa bệnh ban đầu. Cần phạm vi `customers:identity`.
`bhytValidFrom`	`date`		Thẻ BHYT có hiệu lực từ. Cần phạm vi `customers:identity`.
`bhytValidTo`	`date`		Thẻ BHYT có hiệu lực đến. Cần phạm vi `customers:identity`.

curl -X POST 'https://app.avenix.vn/v1/open/customers' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"fullName":"Nguyễn Thị An","phone":"0901234567","homeBranchId":"3f2b8c1e-7a4d-4c9b-8e21-5d6f7a8b9c01"}'

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ường	Kiểu	Mô tả
`id`	`uuid`	Mã khách hàng.
`code`	`string`	Mã ngắn hiện trong phần mềm.
`fullName`	`string`	Họ tên.
`dateOfBirth`	`date`Có thể trống	Ngày sinh, dạng YYYY-MM-DD.
`gender`	`enum`Có thể trống	Giới tính. Giá trị:`malefemaleother`
`phone`	`string`Có thể trống	Số điện thoại chính theo chuẩn E.164, ví dụ +84901234567.
`email`	`string`Có thể trống	Email. Chỉ có khi xem một khách.
`province`	`string`Có thể trống	Tỉnh, thành phố.
`ward`	`string`Có thể trống	Phường, xã.
`streetAddress`	`string`Có 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-time`Có thể trống	Thời điểm sửa gần nhất. Chỉ có khi xem một khách.
`externalId`	`string`Có thể trống	Mã khách phía phần mềm của bạn.
`country`	`string`Có thể trống	Mã quốc gia ISO của địa chỉ, trống là Việt Nam.
`city`	`string`Có thể trống	Thành phố, khi khách ở nước ngoài.
`region`	`string`Có thể trống	Bang hoặc vùng, khi khách ở nước ngoài.
`isVip`	`boolean`	Khách VIP.
`referralSourceId`	`string`Có 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-time`Có 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`	`string`Có thể trống	Dân tộc. Chỉ có khi xem một khách.
`occupation`	`string`Có thể trống	Nghề nghiệp. Chỉ có khi xem một khách.
`occupationCode`	`string`Có thể trống	Mã nghề theo danh mục khám sức khoẻ. Chỉ có khi xem một khách.
`workplace`	`string`Có thể trống	Nơi làm việc. Chỉ có khi xem một khách.
`bloodGroup`	`string`Có thể trống	Nhóm máu. Chỉ có khi xem một khách.
`rhFactor`	`string`Có thể trống	Yếu tố Rh. Chỉ có khi xem một khách.
`patientType`	`string`Có thể trống	Hình thức khám. Chỉ có khi xem một khách.
`healthCheckSubject`	`string`Có 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`	`string`Có thể trống	Người liên hệ khẩn cấp. Chỉ có khi xem một khách.
`emergencyContactRelation`	`string`Có thể trống	Quan hệ với khách. Chỉ có khi xem một khách.
`emergencyContactPhone`	`string`Có thể trống	Số điện thoại người liên hệ. Chỉ có khi xem một khách.
`note`	`string`Có 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`	`string`Có 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`	`string`Có thể trống	Số hộ chiếu. Chỉ có khi xem một khách và token mang phạm vi `customers:identity`.
`guardianNationalId`	`string`Có 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`	`string`Có thể trống	Số thẻ BHYT. Chỉ có khi xem một khách và token mang phạm vi `customers:identity`.
`bhytRegFacilityCode`	`string`Có 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`	`string`Có 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`	`string`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`externalId`	Đường dẫn	`string`	Bắt buộc	Mã khách phía phần mềm của bạn.

curl -X GET 'https://app.avenix.vn/v1/open/customers/by-external-id/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H "Authorization: Bearer $TOKEN"

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ường	Kiểu	Mô tả
`id`	`uuid`	Mã khách hàng.
`code`	`string`	Mã ngắn hiện trong phần mềm.
`fullName`	`string`	Họ tên.
`dateOfBirth`	`date`Có thể trống	Ngày sinh, dạng YYYY-MM-DD.
`gender`	`enum`Có thể trống	Giới tính. Giá trị:`malefemaleother`
`phone`	`string`Có thể trống	Số điện thoại chính theo chuẩn E.164, ví dụ +84901234567.
`email`	`string`Có thể trống	Email. Chỉ có khi xem một khách.
`province`	`string`Có thể trống	Tỉnh, thành phố.
`ward`	`string`Có thể trống	Phường, xã.
`streetAddress`	`string`Có 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-time`Có thể trống	Thời điểm sửa gần nhất. Chỉ có khi xem một khách.
`externalId`	`string`Có thể trống	Mã khách phía phần mềm của bạn.
`country`	`string`Có thể trống	Mã quốc gia ISO của địa chỉ, trống là Việt Nam.
`city`	`string`Có thể trống	Thành phố, khi khách ở nước ngoài.
`region`	`string`Có thể trống	Bang hoặc vùng, khi khách ở nước ngoài.
`isVip`	`boolean`	Khách VIP.
`referralSourceId`	`string`Có 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-time`Có 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`	`string`Có thể trống	Dân tộc. Chỉ có khi xem một khách.
`occupation`	`string`Có thể trống	Nghề nghiệp. Chỉ có khi xem một khách.
`occupationCode`	`string`Có thể trống	Mã nghề theo danh mục khám sức khoẻ. Chỉ có khi xem một khách.
`workplace`	`string`Có thể trống	Nơi làm việc. Chỉ có khi xem một khách.
`bloodGroup`	`string`Có thể trống	Nhóm máu. Chỉ có khi xem một khách.
`rhFactor`	`string`Có thể trống	Yếu tố Rh. Chỉ có khi xem một khách.
`patientType`	`string`Có thể trống	Hình thức khám. Chỉ có khi xem một khách.
`healthCheckSubject`	`string`Có 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`	`string`Có thể trống	Người liên hệ khẩn cấp. Chỉ có khi xem một khách.
`emergencyContactRelation`	`string`Có thể trống	Quan hệ với khách. Chỉ có khi xem một khách.
`emergencyContactPhone`	`string`Có thể trống	Số điện thoại người liên hệ. Chỉ có khi xem một khách.
`note`	`string`Có 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`	`string`Có 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`	`string`Có thể trống	Số hộ chiếu. Chỉ có khi xem một khách và token mang phạm vi `customers:identity`.
`guardianNationalId`	`string`Có 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`	`string`Có thể trống	Số thẻ BHYT. Chỉ có khi xem một khách và token mang phạm vi `customers:identity`.
`bhytRegFacilityCode`	`string`Có 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`	`string`Có 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`	`string`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`id`	Đường dẫn	`uuid`	Bắt buộc	Mã bản ghi.

curl -X GET 'https://app.avenix.vn/v1/open/customers/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H "Authorization: Bearer $TOKEN"

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ường	Kiểu	Mô tả
`id`	`uuid`	Mã khách hàng.
`code`	`string`	Mã ngắn hiện trong phần mềm.
`fullName`	`string`	Họ tên.
`dateOfBirth`	`date`Có thể trống	Ngày sinh, dạng YYYY-MM-DD.
`gender`	`enum`Có thể trống	Giới tính. Giá trị:`malefemaleother`
`phone`	`string`Có thể trống	Số điện thoại chính theo chuẩn E.164, ví dụ +84901234567.
`email`	`string`Có thể trống	Email. Chỉ có khi xem một khách.
`province`	`string`Có thể trống	Tỉnh, thành phố.
`ward`	`string`Có thể trống	Phường, xã.
`streetAddress`	`string`Có 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-time`Có thể trống	Thời điểm sửa gần nhất. Chỉ có khi xem một khách.
`externalId`	`string`Có thể trống	Mã khách phía phần mềm của bạn.
`country`	`string`Có thể trống	Mã quốc gia ISO của địa chỉ, trống là Việt Nam.
`city`	`string`Có thể trống	Thành phố, khi khách ở nước ngoài.
`region`	`string`Có thể trống	Bang hoặc vùng, khi khách ở nước ngoài.
`isVip`	`boolean`	Khách VIP.
`referralSourceId`	`string`Có 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-time`Có 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`	`string`Có thể trống	Dân tộc. Chỉ có khi xem một khách.
`occupation`	`string`Có thể trống	Nghề nghiệp. Chỉ có khi xem một khách.
`occupationCode`	`string`Có thể trống	Mã nghề theo danh mục khám sức khoẻ. Chỉ có khi xem một khách.
`workplace`	`string`Có thể trống	Nơi làm việc. Chỉ có khi xem một khách.
`bloodGroup`	`string`Có thể trống	Nhóm máu. Chỉ có khi xem một khách.
`rhFactor`	`string`Có thể trống	Yếu tố Rh. Chỉ có khi xem một khách.
`patientType`	`string`Có thể trống	Hình thức khám. Chỉ có khi xem một khách.
`healthCheckSubject`	`string`Có 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`	`string`Có thể trống	Người liên hệ khẩn cấp. Chỉ có khi xem một khách.
`emergencyContactRelation`	`string`Có thể trống	Quan hệ với khách. Chỉ có khi xem một khách.
`emergencyContactPhone`	`string`Có thể trống	Số điện thoại người liên hệ. Chỉ có khi xem một khách.
`note`	`string`Có 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`	`string`Có 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`	`string`Có thể trống	Số hộ chiếu. Chỉ có khi xem một khách và token mang phạm vi `customers:identity`.
`guardianNationalId`	`string`Có 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`	`string`Có thể trống	Số thẻ BHYT. Chỉ có khi xem một khách và token mang phạm vi `customers:identity`.
`bhytRegFacilityCode`	`string`Có 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`	`string`Có 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`	`string`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`id`	Đường dẫn	`uuid`	Bắt buộc	Mã bản ghi.

Nội dung gửi

Tên trường	Kiểu	Mô tả
`fullName`	`string`	Họ tên.
`phone`	`string`	Số điện thoại. Nhận 0901234567 hoặc +84901234567, trả về dạng E.164.
`dateOfBirth`	`date`	Ngày sinh, dạng YYYY-MM-DD.
`gender`	`enum`	Giới tính. Giá trị:`malefemaleother`
`email`	`email`	Email.
`province`	`string`	Tỉnh, thành phố.
`ward`	`string`	Phường, xã.
`streetAddress`	`string`	Số nhà, tên đường.
`country`	`string`Có thể trống	Mã quốc gia ISO, ví dụ `sg`. Bỏ trống là Việt Nam.
`city`	`string`Có thể trống	Thành phố, bắt buộc khi ở nước ngoài.
`region`	`string`Có thể trống	Bang hoặc vùng ở nước ngoài.
`extraPhones`	`array`Có thể trống	Các số điện thoại thêm. Gửi cả bộ.
`note`	`string`Có thể trống	Ghi chú cho phòng khám.
`referralSourceId`	`string`Có thể trống	Nguồn khách theo danh mục của phòng khám.
`isVip`	`boolean`Có thể trống	Khách VIP.
`ethnicity`	`string`Có thể trống	Dân tộc.
`occupation`	`string`Có thể trống	Nghề nghiệp.
`occupationCode`	`string`Có thể trống	Mã nghề theo danh mục khám sức khoẻ.
`workplace`	`string`Có thể trống	Nơi làm việc.
`bloodGroup`	`enum`Có thể trống	Nhóm máu. Giá trị:`ABABO`
`rhFactor`	`enum`Có thể trống	Yếu tố Rh. Giá trị:`+-`
`patientType`	`enum`Có thể trống	Hình thức khám. Giá trị:`servicebhythealth_checkfree`
`healthCheckSubject`	`string`Có thể trống	Đối tượng khám sức khoẻ theo danh mục Sở Y tế.
`emergencyContactName`	`string`Có thể trống	Người liên hệ khẩn cấp.
`emergencyContactRelation`	`string`Có thể trống	Quan hệ với khách.
`emergencyContactPhone`	`string`Có thể trống	Số điện thoại người liên hệ.
`externalId`	`string`Có 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`	`string`Có 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`	`string`Có thể trống	Số hộ chiếu. Cần phạm vi `customers:identity`.
`guardianNationalId`	`string`Có thể trống	CCCD người giám hộ. Cần phạm vi `customers:identity`.
`bhytCode`	`string`Có thể trống	Số thẻ BHYT. Cần phạm vi `customers:identity`.
`bhytRegFacilityCode`	`string`Có thể trống	Nơi đăng ký khám chữa bệnh ban đầu. Cần phạm vi `customers:identity`.
`bhytValidFrom`	`date`Có thể trống	Thẻ BHYT có hiệu lực từ. Cần phạm vi `customers:identity`.
`bhytValidTo`	`date`Có 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ường	Kiểu	Mô tả
`id`	`uuid`	Mã khách hàng.
`code`	`string`	Mã ngắn hiện trong phần mềm.
`fullName`	`string`	Họ tên.
`dateOfBirth`	`date`Có thể trống	Ngày sinh, dạng YYYY-MM-DD.
`gender`	`enum`Có thể trống	Giới tính. Giá trị:`malefemaleother`
`phone`	`string`Có thể trống	Số điện thoại chính theo chuẩn E.164, ví dụ +84901234567.
`email`	`string`Có thể trống	Email. Chỉ có khi xem một khách.
`province`	`string`Có thể trống	Tỉnh, thành phố.
`ward`	`string`Có thể trống	Phường, xã.
`streetAddress`	`string`Có 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-time`Có thể trống	Thời điểm sửa gần nhất. Chỉ có khi xem một khách.
`externalId`	`string`Có thể trống	Mã khách phía phần mềm của bạn.
`country`	`string`Có thể trống	Mã quốc gia ISO của địa chỉ, trống là Việt Nam.
`city`	`string`Có thể trống	Thành phố, khi khách ở nước ngoài.
`region`	`string`Có thể trống	Bang hoặc vùng, khi khách ở nước ngoài.
`isVip`	`boolean`	Khách VIP.
`referralSourceId`	`string`Có 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-time`Có 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`	`string`Có thể trống	Dân tộc. Chỉ có khi xem một khách.
`occupation`	`string`Có thể trống	Nghề nghiệp. Chỉ có khi xem một khách.
`occupationCode`	`string`Có thể trống	Mã nghề theo danh mục khám sức khoẻ. Chỉ có khi xem một khách.
`workplace`	`string`Có thể trống	Nơi làm việc. Chỉ có khi xem một khách.
`bloodGroup`	`string`Có thể trống	Nhóm máu. Chỉ có khi xem một khách.
`rhFactor`	`string`Có thể trống	Yếu tố Rh. Chỉ có khi xem một khách.
`patientType`	`string`Có thể trống	Hình thức khám. Chỉ có khi xem một khách.
`healthCheckSubject`	`string`Có 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`	`string`Có thể trống	Người liên hệ khẩn cấp. Chỉ có khi xem một khách.
`emergencyContactRelation`	`string`Có thể trống	Quan hệ với khách. Chỉ có khi xem một khách.
`emergencyContactPhone`	`string`Có thể trống	Số điện thoại người liên hệ. Chỉ có khi xem một khách.
`note`	`string`Có 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`	`string`Có 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`	`string`Có thể trống	Số hộ chiếu. Chỉ có khi xem một khách và token mang phạm vi `customers:identity`.
`guardianNationalId`	`string`Có 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`	`string`Có thể trống	Số thẻ BHYT. Chỉ có khi xem một khách và token mang phạm vi `customers:identity`.
`bhytRegFacilityCode`	`string`Có 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`	`string`Có 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`	`string`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`branchId`	Truy vấn	`uuid`	Bắt buộc	Chi nhánh.
`doctorId`	Truy vấn	`uuid`		Bác sĩ. Bỏ trống để xem theo giờ mở cửa.
`date`	Truy vấn	`date`	Bắt buộc	Ngày cần xem, dạng YYYY-MM-DD.

curl -X GET 'https://app.avenix.vn/v1/open/appointments/availability' \
  -H "Authorization: Bearer $TOKEN"

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ường	Kiểu	Mô tả
`date`	`date`	Ngày đang xem.
`slotMinutes`	`integer`	Độ dài mỗi ô, tính bằng phút.
`closedReason`	`string`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`from`	Truy vấn	`date-time`	Bắt buộc	Từ thời điểm.
`to`	Truy vấn	`date-time`	Bắt buộc	Đến thời điểm, cách `from` tối đa 31 ngày.
`branchId`	Truy vấn	`uuid`		Chỉ lấy một chi nhánh.
`customerId`	Truy vấn	`uuid`		Chỉ lấy một khách.

curl -X GET 'https://app.avenix.vn/v1/open/appointments' \
  -H "Authorization: Bearer $TOKEN"

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ường	Kiểu	Mô tả
`data`	`array`	Các dòng của trang này.
`data[].id`	`uuid`	Mã lịch hẹn.
`data[].code`	`string`Có 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`	`uuid`Có 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`	`uuid`Có thể trống	Ghế hoặc phòng đã giữ.
`data[].assistantId`	`uuid`Có thể trống	Phụ tá.
`data[].salesStaffId`	`uuid`Có thể trống	Nhân viên kinh doanh.
`data[].plannedServiceIds`	`array`	Các dịch vụ dự kiến làm.
`data[].doctorName`	`string`Có thể trống	Tên bác sĩ. Chỉ có khi xem một lịch.
`data[].branchName`	`string`Có thể trống	Tên chi nhánh. Chỉ có khi xem một lịch.
`data[].chairName`	`string`Có thể trống	Tên ghế hoặc phòng. Chỉ có khi xem một lịch.
`data[].assistantName`	`string`Có thể trống	Tên phụ tá. Chỉ có khi xem một lịch.
`data[].salesStaffName`	`string`Có thể trống	Tên nhân viên kinh doanh. Chỉ có khi xem một lịch.
`data[].note`	`string`Có thể trống	Ghi chú. Chỉ có khi xem một lịch.
`data[].cancelReason`	`string`Có thể trống	Lý do huỷ. Chỉ có khi xem một lịch.
`data[].checkedInAt`	`date-time`Có thể trống	Lúc khách đến. Chỉ có khi xem một lịch.
`data[].completedAt`	`date-time`Có thể trống	Lúc hoàn tất. Chỉ có khi xem một lịch.
`data[].updatedAt`	`date-time`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`Idempotency-Key`	Header	`string`	Bắt buộc	Chuỗi ngẫu nhiên cho mỗi việc. Gửi lại cùng khoá trong 24 giờ thì không tạo trùng.

Nội dung gửi

Tên trường	Kiểu	Bắt buộc	Mô tả
`branchId`	`uuid`	Bắt buộc	Chi nhánh, phải thuộc các chi nhánh kết nối được cấp.
`customerId`	`uuid`	Bắt buộc	Khách hàng.
`doctorId`	`uuid`		Bác sĩ.
`startsAt`	`date-time`	Bắt buộc	Giờ bắt đầu.
`endsAt`	`date-time`	Bắt buộc	Giờ kết thúc.
`note`	`string`		Ghi chú cho phòng khám.
`chairId`	`uuid`		Ghế hoặc phòng giữ cho ca.
`assistantId`	`uuid`		Phụ tá.
`salesStaffId`	`uuid`		Nhân viên kinh doanh.
`plannedServiceIds`	`array`		Các dịch vụ dự kiến làm, mã `id` ở danh sách dịch vụ.

curl -X POST 'https://app.avenix.vn/v1/open/appointments' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"branchId":"3f2b8c1e-7a4d-4c9b-8e21-5d6f7a8b9c01","customerId":"8a1c2d3e-4f5a-4b6c-9d7e-0f1a2b3c4d5e","startsAt":"2026-12-01T09:00:00+07:00","endsAt":"2026-12-01T09:30:00+07:00"}'

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ường	Kiểu	Mô tả
`id`	`uuid`	Mã lịch hẹn.
`code`	`string`Có 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`	`uuid`Có 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`	`uuid`Có thể trống	Ghế hoặc phòng đã giữ.
`assistantId`	`uuid`Có thể trống	Phụ tá.
`salesStaffId`	`uuid`Có thể trống	Nhân viên kinh doanh.
`plannedServiceIds`	`array`	Các dịch vụ dự kiến làm.
`doctorName`	`string`Có thể trống	Tên bác sĩ. Chỉ có khi xem một lịch.
`branchName`	`string`Có thể trống	Tên chi nhánh. Chỉ có khi xem một lịch.
`chairName`	`string`Có thể trống	Tên ghế hoặc phòng. Chỉ có khi xem một lịch.
`assistantName`	`string`Có thể trống	Tên phụ tá. Chỉ có khi xem một lịch.
`salesStaffName`	`string`Có thể trống	Tên nhân viên kinh doanh. Chỉ có khi xem một lịch.
`note`	`string`Có thể trống	Ghi chú. Chỉ có khi xem một lịch.
`cancelReason`	`string`Có thể trống	Lý do huỷ. Chỉ có khi xem một lịch.
`checkedInAt`	`date-time`Có thể trống	Lúc khách đến. Chỉ có khi xem một lịch.
`completedAt`	`date-time`Có thể trống	Lúc hoàn tất. Chỉ có khi xem một lịch.
`updatedAt`	`date-time`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`id`	Đường dẫn	`uuid`	Bắt buộc	Mã bản ghi.

curl -X GET 'https://app.avenix.vn/v1/open/appointments/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H "Authorization: Bearer $TOKEN"

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ường	Kiểu	Mô tả
`id`	`uuid`	Mã lịch hẹn.
`code`	`string`Có 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`	`uuid`Có 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`	`uuid`Có thể trống	Ghế hoặc phòng đã giữ.
`assistantId`	`uuid`Có thể trống	Phụ tá.
`salesStaffId`	`uuid`Có thể trống	Nhân viên kinh doanh.
`plannedServiceIds`	`array`	Các dịch vụ dự kiến làm.
`doctorName`	`string`Có thể trống	Tên bác sĩ. Chỉ có khi xem một lịch.
`branchName`	`string`Có thể trống	Tên chi nhánh. Chỉ có khi xem một lịch.
`chairName`	`string`Có thể trống	Tên ghế hoặc phòng. Chỉ có khi xem một lịch.
`assistantName`	`string`Có thể trống	Tên phụ tá. Chỉ có khi xem một lịch.
`salesStaffName`	`string`Có thể trống	Tên nhân viên kinh doanh. Chỉ có khi xem một lịch.
`note`	`string`Có thể trống	Ghi chú. Chỉ có khi xem một lịch.
`cancelReason`	`string`Có thể trống	Lý do huỷ. Chỉ có khi xem một lịch.
`checkedInAt`	`date-time`Có thể trống	Lúc khách đến. Chỉ có khi xem một lịch.
`completedAt`	`date-time`Có thể trống	Lúc hoàn tất. Chỉ có khi xem một lịch.
`updatedAt`	`date-time`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`id`	Đường dẫn	`uuid`	Bắt buộc	Mã bản ghi.

Nội dung gửi

Tên trường	Kiểu	Bắt buộc	Mô tả
`startsAt`	`date-time`	Bắt buộc	Giờ bắt đầu mới.
`endsAt`	`date-time`	Bắt buộc	Giờ kết thúc mới.
`doctorId`	`uuid`		Bác sĩ mới.
`chairId`	`uuid`Có thể trống		Ghế hoặc phòng, trống là bỏ.
`note`	`string`Có thể trống		Ghi chú, trống là xoá.
`assistantId`	`uuid`Có thể trống		Phụ tá, trống là bỏ.
`salesStaffId`	`uuid`Có 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ường	Kiểu	Mô tả
`id`	`uuid`	Mã lịch hẹn.
`code`	`string`Có 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`	`uuid`Có 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`	`uuid`Có thể trống	Ghế hoặc phòng đã giữ.
`assistantId`	`uuid`Có thể trống	Phụ tá.
`salesStaffId`	`uuid`Có thể trống	Nhân viên kinh doanh.
`plannedServiceIds`	`array`	Các dịch vụ dự kiến làm.
`doctorName`	`string`Có thể trống	Tên bác sĩ. Chỉ có khi xem một lịch.
`branchName`	`string`Có thể trống	Tên chi nhánh. Chỉ có khi xem một lịch.
`chairName`	`string`Có thể trống	Tên ghế hoặc phòng. Chỉ có khi xem một lịch.
`assistantName`	`string`Có thể trống	Tên phụ tá. Chỉ có khi xem một lịch.
`salesStaffName`	`string`Có thể trống	Tên nhân viên kinh doanh. Chỉ có khi xem một lịch.
`note`	`string`Có thể trống	Ghi chú. Chỉ có khi xem một lịch.
`cancelReason`	`string`Có thể trống	Lý do huỷ. Chỉ có khi xem một lịch.
`checkedInAt`	`date-time`Có thể trống	Lúc khách đến. Chỉ có khi xem một lịch.
`completedAt`	`date-time`Có thể trống	Lúc hoàn tất. Chỉ có khi xem một lịch.
`updatedAt`	`date-time`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`id`	Đường dẫn	`uuid`	Bắt buộc	Mã bản ghi.

Nội dung gửi

Tên trường	Kiểu	Bắt buộc	Mô tả
`reason`	`string`		Lý do huỷ, tối thiểu 10 ký tự.

curl -X POST 'https://app.avenix.vn/v1/open/appointments/3fa85f64-5717-4562-b3fc-2c963f66afa6/cancel' \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"reason":"Khách báo đổi kế hoạch"}'

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ường	Kiểu	Mô tả
`id`	`uuid`	Mã lịch hẹn.
`code`	`string`Có 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`	`uuid`Có 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`	`uuid`Có thể trống	Ghế hoặc phòng đã giữ.
`assistantId`	`uuid`Có thể trống	Phụ tá.
`salesStaffId`	`uuid`Có thể trống	Nhân viên kinh doanh.
`plannedServiceIds`	`array`	Các dịch vụ dự kiến làm.
`doctorName`	`string`Có thể trống	Tên bác sĩ. Chỉ có khi xem một lịch.
`branchName`	`string`Có thể trống	Tên chi nhánh. Chỉ có khi xem một lịch.
`chairName`	`string`Có thể trống	Tên ghế hoặc phòng. Chỉ có khi xem một lịch.
`assistantName`	`string`Có thể trống	Tên phụ tá. Chỉ có khi xem một lịch.
`salesStaffName`	`string`Có thể trống	Tên nhân viên kinh doanh. Chỉ có khi xem một lịch.
`note`	`string`Có thể trống	Ghi chú. Chỉ có khi xem một lịch.
`cancelReason`	`string`Có thể trống	Lý do huỷ. Chỉ có khi xem một lịch.
`checkedInAt`	`date-time`Có thể trống	Lúc khách đến. Chỉ có khi xem một lịch.
`completedAt`	`date-time`Có thể trống	Lúc hoàn tất. Chỉ có khi xem một lịch.
`updatedAt`	`date-time`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`Idempotency-Key`	Header	`string`	Bắt buộc	Chuỗi ngẫu nhiên cho mỗi việc. Gửi lại cùng khoá trong 24 giờ thì không tạo trùng.

Nội dung gửi

Tên trường	Kiểu	Bắt buộc	Mô tả
`fullName`	`string`	Bắt buộc	Họ tên khách.
`phone`	`string`	Bắt buộc	Số điện thoại khách.
`note`	`string`		Nội dung khách để lại.
`source`	`string`		Nguồn khách, ví dụ tên landing page.
`expectedRevenue`	`integer`		Doanh thu dự kiến, tính bằng đồng.
`expectedClosingDate`	`date`		Ngày dự kiến chốt, dạng YYYY-MM-DD.
`customerId`	`uuid`		Gắn cơ hội với hồ sơ khách đã có.

curl -X POST 'https://app.avenix.vn/v1/open/leads' \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"fullName":"Trần Văn Bình","phone":"0912345678","source":"Landing tẩy trắng"}'

Kết quả 201

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "code": "KH-00012"
}

Các trường trả về2

Tên trường	Kiểu	Mô tả
`id`	`uuid`	Mã cơ hội.
`code`	`string`Có 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ường	Vị trí	Kiểu	Mô tả
`q`	Truy vấn	`string`	Tìm theo tên hoặc mã.
`limit`	Truy vấn	`integer`	Số dòng mỗi trang, từ 1 đến 100.
`cursor`	Truy vấn	`string`	Giá trị `nextCursor` của trang trước. Bỏ trống để lấy trang đầu.
`category`	Truy vấn	`string`	Chỉ lấy một nhóm, mã `key` ở danh sách nhóm dịch vụ.

curl -X GET 'https://app.avenix.vn/v1/open/services' \
  -H "Authorization: Bearer $TOKEN"

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ường	Kiểu	Mô tả
`data`	`array`	Các dòng của trang này.
`data[].code`	`string`	Mã dịch vụ.
`data[].name`	`string`	Tên dịch vụ.
`data[].category`	`string`	Nhóm dịch vụ.
`data[].unit`	`string`	Đơn vị tính.
`data[].price`	`integer`	Giá bán, tính bằng đồng.
`data[].durationMinutes`	`integer`	Thời lượng dự kiến, tính bằng phút.
`data[].vatRate`	`integer`	Thuế suất VAT, tính bằng phần trăm.
`data[].priceIncludesVat`	`boolean`	Giá bán đã gồm VAT hay chưa.
`data[].id`	`uuid`	Mã bản ghi, dùng cho `plannedServiceIds` của lịch hẹn.
`data[].barcode`	`string`Có thể trống	Mã vạch.
`data[].imageUrl`	`string`Có thể trống	Đường dẫn ảnh.
`data[].technicalCodes`	`array`	Các mã dịch vụ kỹ thuật.
`data[].eInvoiceName`	`string`Có thể trống	Tên in trên hoá đơn điện tử, trống là theo tên dịch vụ.
`data[].sessionCount`	`integer`Có thể trống	Số bước tiến trình.
`data[].sessionIntervalDays`	`integer`Có thể trống	Số ngày giữa hai bước.
`data[].sessionNames`	`array`Có thể trống	Tên từng bước.
`data[].isWarrantable`	`boolean`	Có bảo hành.
`data[].warrantyMonths`	`integer`Có thể trống	Số tháng bảo hành.
`data[].warrantyPolicy`	`string`Có 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`	`integer`Có thể trống	Giá labo. Cần phạm vi `catalog:cost`.
`nextCursor`	`string`Có 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ường	Vị trí	Kiểu	Mô tả
`q`	Truy vấn	`string`	Tìm theo tên hoặc mã.
`limit`	Truy vấn	`integer`	Số dòng mỗi trang, từ 1 đến 100.
`cursor`	Truy vấn	`string`	Giá trị `nextCursor` của trang trước. Bỏ trống để lấy trang đầu.
`category`	Truy vấn	`enum`	Chỉ lấy một loại hàng. Giá trị:`productconsumablevaccinemedication`
`groupId`	Truy vấn	`uuid`	Chỉ lấy một nhóm hàng.
`manufacturerId`	Truy vấn	`uuid`	Chỉ lấy một hãng.

curl -X GET 'https://app.avenix.vn/v1/open/products' \
  -H "Authorization: Bearer $TOKEN"

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,
      "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ề41

Tên trường	Kiểu	Mô tả
`data`	`array`	Các dòng của trang này.
`data[].code`	`string`	Mã hàng hoá.
`data[].name`	`string`	Tên hàng hoá.
`data[].category`	`string`	Loại hàng.
`data[].groupName`	`string`Có thể trống	Nhóm hàng.
`data[].manufacturerName`	`string`Có 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`	`string`Có thể trống	Đơn vị thứ hai, ví dụ Hộp.
`data[].secondaryPrice`	`integer`Có thể trống	Giá bán theo đơn vị thứ hai.
`data[].barcode`	`string`Có 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`	`uuid`Có thể trống	Nhóm hàng.
`data[].manufacturerId`	`uuid`Có thể trống	Hãng sản xuất.
`data[].parentId`	`uuid`Có thể trống	Hàng gốc, khi dòng này là biến thể.
`data[].variantAttribute1`	`string`Có thể trống	Tên thuộc tính thứ nhất của biến thể, ví dụ Màu.
`data[].variantAttribute2`	`string`Có thể trống	Tên thuộc tính thứ hai của biến thể, ví dụ Size.
`data[].lastSupplierId`	`uuid`Có 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`	`string`Có 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`	`string`Có 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`	`string`Có thể trống	Mô tả.
`data[].dosage`	`string`Có thể trống	Hàm lượng.
`data[].usageInstructions`	`string`Có thể trống	Hướng dẫn sử dụng.
`data[].activeIngredient`	`string`Có thể trống	Hoạt chất.
`data[].route`	`string`Có thể trống	Đường dùng.
`data[].nationalDrugCode`	`string`Có thể trống	Mã thuốc quốc gia.
`data[].registrationNumber`	`string`Có thể trống	Số đăng ký.
`data[].parentCode`	`string`Có thể trống	Mã hàng gốc, khi dòng này là biến thể.
`data[].parentName`	`string`Có thể trống	Tên hàng gốc.
`data[].variantOption1`	`string`Có thể trống	Giá trị thuộc tính thứ nhất của biến thể.
`data[].variantOption2`	`string`Có 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`	`integer`Có thể trống	Số tháng bảo hành.
`data[].warrantyPolicy`	`string`Có 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`	`string`Có 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ường	Kiểu	Mô tả
`data`	`array`	Các dòng của trang này.
`data[].key`	`string`	Mã nhóm, trùng trường `category` của dịch vụ.
`data[].name`	`string`	Tên nhóm do phòng khám đặt.

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ường	Kiểu	Mô tả
`data`	`array`	Các dòng của trang này.
`data[].id`	`uuid`	Mã nhóm hàng, trùng trường `groupId` của hàng hoá.
`data[].code`	`string`	Mã ngắn của nhóm.
`data[].name`	`string`	Tên nhóm.
`data[].category`	`string`	Loại hàng của nhóm.
`data[].description`	`string`Có 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ường	Kiểu	Mô tả
`data`	`array`	Các dòng của trang này.
`data[].id`	`uuid`	Mã hãng, trùng trường `manufacturerId` của hàng hoá.
`data[].name`	`string`	Tên hãng.
`data[].country`	`string`Có thể trống	Quốc gia.
`data[].logoUrl`	`string`Có 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ường	Vị trí	Kiểu	Mô tả
`q`	Truy vấn	`string`	Tìm theo tên, mã số thuế hoặc mã.
`limit`	Truy vấn	`integer`	Số dòng mỗi trang, từ 1 đến 100.
`cursor`	Truy vấn	`string`	Giá trị `nextCursor` của trang trước. Bỏ trống để lấy trang đầu.

curl -X GET 'https://app.avenix.vn/v1/open/suppliers' \
  -H "Authorization: Bearer $TOKEN"

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ường	Kiểu	Mô tả
`data`	`array`	Các dòng của trang này.
`data[].id`	`uuid`	Mã nhà cung cấp.
`data[].code`	`string`	Mã ngắn hiện trong phần mềm.
`data[].name`	`string`	Tên nhà cung cấp.
`data[].taxCode`	`string`Có thể trống	Mã số thuế.
`data[].phone`	`string`Có thể trống	Số điện thoại.
`data[].email`	`string`Có thể trống	Email.
`data[].province`	`string`Có thể trống	Tỉnh, thành phố.
`data[].ward`	`string`Có thể trống	Phường, xã.
`data[].streetAddress`	`string`Có thể trống	Số nhà, tên đường.
`data[].contactPerson`	`string`Có thể trống	Người liên hệ.
`data[].note`	`string`Có thể trống	Ghi chú.
`nextCursor`	`string`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`from`	Truy vấn	`date-time`	Bắt buộc	Lập từ thời điểm.
`to`	Truy vấn	`date-time`	Bắt buộc	Lập đến thời điểm, cách `from` tối đa 366 ngày.
`branchId`	Truy vấn	`uuid`		Chỉ lấy một chi nhánh.
`customerId`	Truy vấn	`uuid`		Chỉ lấy một khách.
`status`	Truy vấn	`enum`		Chỉ lấy một trạng thái. Giá trị:`draftissuedpartially_paidpaidvoidedrefunded`
`limit`	Truy vấn	`integer`		Số dòng mỗi trang, từ 1 đến 100.
`cursor`	Truy vấn	`string`		Giá trị `nextCursor` của trang trước. Bỏ trống để lấy trang đầu.

curl -X GET 'https://app.avenix.vn/v1/open/invoices' \
  -H "Authorization: Bearer $TOKEN"

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ường	Kiểu	Mô tả
`data`	`array`	Các dòng của trang này.
`data[].id`	`uuid`	Mã hoá đơn.
`data[].code`	`string`	Mã ngắn hiện trong phần mềm.
`data[].branchId`	`uuid`	Chi nhánh.
`data[].customerId`	`uuid`Có 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-time`Có 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`	`string`Có thể trống	Mã ngắn của khách.
`data[].customerName`	`string`Có thể trống	Họ tên khách.
`data[].note`	`string`Có thể trống	Ghi chú của đơn.
`data[].voidReason`	`string`Có thể trống	Lý do huỷ.
`data[].encounterId`	`uuid`Có thể trống	Phiếu khám của hoá đơn, trống khi bán lẻ.
`nextCursor`	`string`Có 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ường	Vị trí	Kiểu	Bắt buộc	Mô tả
`id`	Đường dẫn	`uuid`	Bắt buộc	Mã bản ghi.

curl -X GET 'https://app.avenix.vn/v1/open/invoices/3fa85f64-5717-4562-b3fc-2c963f66afa6' \
  -H "Authorization: Bearer $TOKEN"

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ường	Kiểu	Mô tả
`id`	`uuid`	Mã hoá đơn.
`code`	`string`	Mã ngắn hiện trong phần mềm.
`branchId`	`uuid`	Chi nhánh.
`customerId`	`uuid`Có 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-time`Có 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`	`string`Có thể trống	Mã ngắn của khách.
`customerName`	`string`Có thể trống	Họ tên khách.
`note`	`string`Có thể trống	Ghi chú của đơn.
`voidReason`	`string`Có thể trống	Lý do huỷ.
`encounterId`	`uuid`Có 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`	`string`Có thể trống	Lý do giảm giá cả đơn.
`encounterCode`	`string`Có thể trống	Mã phiếu khám.
`doctorId`	`uuid`Có thể trống	Bác sĩ phụ trách.
`doctorName`	`string`Có thể trống	Tên bác sĩ phụ trách.
`createdByName`	`string`Có thể trống	Người lập hoá đơn.
`updatedAt`	`date-time`Có 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`	`string`Có thể trống	Ghi chú của dòng.
`lines[].plannedDate`	`string`Có thể trống	Mốc thời gian đã chốt của dòng.
`lines[].promotionName`	`string`Có 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ị:`cashtransfervietqrbalancedepositpoints`
`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-time`Có thể trống	Thời điểm thu.
`payments[].accountName`	`string`Có thể trống	Tài khoản nhận tiền.
`payments[].reference`	`string`Có thể trống	Mã tham chiếu giao dịch.
`payments[].createdAt`	`date-time`	Thời điểm ghi phiếu.
`payments[].refundedAt`	`date-time`Có thể trống	Thời điểm hoàn gần nhất.
`payments[].refundReason`	`string`Có thể trống	Lý do hoàn.

Mã lỗi có thể gặp:401403404429