Tham chiếu: Khách hàng

Khách hàng, địa chỉ và ghi chú. Mọi đường dẫn dưới https://danix.vn/api/open/v1. Đặc tả máy đọc: openapi.json.

Liệt kê khách hàng

GET /customers

Phân trang theo con trỏ. Lọc theo số điện thoại bằng phone.

Quyền cần có: khoá có quyền pos.customers.read.

Tham số query

Ví dụ yêu cầu

curl -X GET "https://danix.vn/api/open/v1/customers" \
  -H "Authorization: Bearer dnx_live_…"

Phản hồi mẫu (200)

{
  "data": [
    {
      "id": "018f3b8e-1c2d-7a4b-9c3d-000000000201",
      "name": "Nguyễn Văn An",
      "gender": "male",
      "dateOfBirth": null,
      "source": "order",
      "isBlocked": false,
      "primaryPhone": "0901234567",
      "primaryEmail": null,
      "createdAt": "2026-10-02T03:15:00.000Z",
      "updatedAt": "2026-10-02T03:15:00.000Z",
      "deletedAt": null
    }
  ],
  "nextCursor": null
}

Trường của phản hồi

Lỗi

Định dạng lỗi và bảng mọi mã code: Lỗi.

Tạo khách hàng

POST /customers

Tạo hồ sơ khách. Gửi Idempotency-Key để thử lại an toàn.

Quyền cần có: khoá có quyền pos.customers.create.

Header

Thân yêu cầu (JSON)

Ví dụ yêu cầu

curl -X POST "https://danix.vn/api/open/v1/customers" \
  -H "Authorization: Bearer dnx_live_…" \
  -H "Idempotency-Key: 865d6735-58e7-488f-9ba7-be2de4de5651" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Nguyễn Văn An",
  "contacts": [
    {
      "kind": "phone",
      "value": "0901234567",
      "isPrimary": true
    }
  ]
}'

Phản hồi mẫu (201)

{
  "id": "018f3b8e-1c2d-7a4b-9c3d-000000000201",
  "name": "Nguyễn Văn An",
  "gender": "male",
  "dateOfBirth": null,
  "source": "order",
  "isBlocked": false,
  "primaryPhone": "0901234567",
  "primaryEmail": null,
  "createdAt": "2026-10-02T03:15:00.000Z",
  "updatedAt": "2026-10-02T03:15:00.000Z",
  "deletedAt": null,
  "contacts": [
    {
      "id": "018f3b8e-1c2d-7a4b-9c3d-000000000901",
      "kind": "phone",
      "value": "0901234567",
      "isPrimary": true
    }
  ],
  "addresses": []
}

Trường của phản hồi

Lỗi

Định dạng lỗi và bảng mọi mã code: Lỗi.

Chi tiết một khách hàng

GET /customers/{id}

Trả khách kèm số điện thoại, email và địa chỉ giao hàng.

Quyền cần có: khoá có quyền pos.customers.read.

Tham số đường dẫn

Ví dụ yêu cầu

curl -X GET "https://danix.vn/api/open/v1/customers/{id}" \
  -H "Authorization: Bearer dnx_live_…"

Thay {id} trong địa chỉ bằng mã thật của bản ghi, và dnx_live_… bằng khoá của bạn.

Phản hồi mẫu (200)

{
  "id": "018f3b8e-1c2d-7a4b-9c3d-000000000201",
  "name": "Nguyễn Văn An",
  "gender": "male",
  "dateOfBirth": null,
  "source": "order",
  "isBlocked": false,
  "primaryPhone": "0901234567",
  "primaryEmail": null,
  "createdAt": "2026-10-02T03:15:00.000Z",
  "updatedAt": "2026-10-02T03:15:00.000Z",
  "deletedAt": null,
  "contacts": [
    {
      "id": "018f3b8e-1c2d-7a4b-9c3d-000000000901",
      "kind": "phone",
      "value": "0901234567",
      "isPrimary": true
    }
  ],
  "addresses": []
}

Trường của phản hồi

Lỗi

Định dạng lỗi và bảng mọi mã code: Lỗi.

Sửa khách hàng

PATCH /customers/{id}

Chỉ gửi trường cần đổi. Số điện thoại và email không sửa được qua đường này.

Quyền cần có: khoá có quyền pos.customers.update.

Tham số đường dẫn

Thân yêu cầu (JSON)

Ví dụ yêu cầu

curl -X PATCH "https://danix.vn/api/open/v1/customers/{id}" \
  -H "Authorization: Bearer dnx_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Nguyễn Văn An (VIP)"
}'

Thay {id} trong địa chỉ bằng mã thật của bản ghi, và dnx_live_… bằng khoá của bạn.

Phản hồi mẫu (200)

{
  "id": "018f3b8e-1c2d-7a4b-9c3d-000000000201",
  "name": "Nguyễn Văn An",
  "gender": "male",
  "dateOfBirth": null,
  "source": "order",
  "isBlocked": false,
  "primaryPhone": "0901234567",
  "primaryEmail": null,
  "createdAt": "2026-10-02T03:15:00.000Z",
  "updatedAt": "2026-10-02T03:15:00.000Z",
  "deletedAt": null,
  "contacts": [
    {
      "id": "018f3b8e-1c2d-7a4b-9c3d-000000000901",
      "kind": "phone",
      "value": "0901234567",
      "isPrimary": true
    }
  ],
  "addresses": []
}

Trường của phản hồi

Lỗi

Định dạng lỗi và bảng mọi mã code: Lỗi.

Thêm địa chỉ cho khách

POST /customers/{id}/addresses

Thêm một địa chỉ giao hàng vào hồ sơ khách. Khách đã có một địa chỉ đúng như vậy thì trả conflict. Gửi mã đơn vị hành chính (tra bằng GET /geo/units) để đơn dùng địa chỉ này đẩy được sang hãng vận chuyển.

Quyền cần có: khoá có quyền pos.customers.update.

Tham số đường dẫn

Thân yêu cầu (JSON)

Ví dụ yêu cầu

curl -X POST "https://danix.vn/api/open/v1/customers/{id}/addresses" \
  -H "Authorization: Bearer dnx_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "addressLine": "12 Lê Lợi",
  "provinceName": "Đà Nẵng"
}'

Thay {id} trong địa chỉ bằng mã thật của bản ghi, và dnx_live_… bằng khoá của bạn.

Phản hồi mẫu (201)

{
  "id": "018f3b8e-1c2d-7a4b-9c3d-000000000999",
  "recipientName": null,
  "recipientPhone": null,
  "addressLine": "12 Lê Lợi, Đà Nẵng",
  "geoSystem": null,
  "provinceUnitId": null,
  "districtUnitId": null,
  "wardUnitId": null,
  "provinceName": null,
  "districtName": null,
  "wardName": null
}

Trường của phản hồi

Lỗi

Định dạng lỗi và bảng mọi mã code: Lỗi.

Sửa địa chỉ của khách

PATCH /customers/{id}/addresses/{addressId}

Thay nội dung một địa chỉ giao hàng; trùng đúng một địa chỉ khác của khách thì trả conflict. Gửi tên địa danh (tỉnh, huyện, xã) mà không gửi mã thì mã đơn vị cũ bị XOÁ — địa chỉ không còn đẩy hãng được tới khi gửi lại mã; không gửi trường địa danh nào thì giữ nguyên.

Quyền cần có: khoá có quyền pos.customers.update.

Tham số đường dẫn

Thân yêu cầu (JSON)

Ví dụ yêu cầu

curl -X PATCH "https://danix.vn/api/open/v1/customers/{id}/addresses/{addressId}" \
  -H "Authorization: Bearer dnx_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "addressLine": "34 Trần Phú"
}'

Thay {id}, {addressId} trong địa chỉ bằng mã thật của bản ghi, và dnx_live_… bằng khoá của bạn.

Phản hồi mẫu (200)

{
  "id": "018f3b8e-1c2d-7a4b-9c3d-000000000999",
  "recipientName": null,
  "recipientPhone": null,
  "addressLine": "34 Trần Phú",
  "geoSystem": "old",
  "provinceUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001501",
  "districtUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001502",
  "wardUnitId": "018f3b8e-1c2d-7a4b-9c3d-000000001503",
  "provinceName": "Đà Nẵng",
  "districtName": "Hải Châu",
  "wardName": "Thạch Thang"
}

Trường của phản hồi

Lỗi

Định dạng lỗi và bảng mọi mã code: Lỗi.

Xoá địa chỉ của khách

DELETE /customers/{id}/addresses/{addressId}

Xoá một địa chỉ giao hàng khỏi hồ sơ khách. Đơn cũ vẫn giữ địa chỉ đã ghi.

Quyền cần có: khoá có quyền pos.customers.delete.

Tham số đường dẫn

Ví dụ yêu cầu

curl -X DELETE "https://danix.vn/api/open/v1/customers/{id}/addresses/{addressId}" \
  -H "Authorization: Bearer dnx_live_…"

Thay {id}, {addressId} trong địa chỉ bằng mã thật của bản ghi, và dnx_live_… bằng khoá của bạn.

Phản hồi mẫu (200)

{
  "ok": true
}

Trường của phản hồi

Lỗi

Định dạng lỗi và bảng mọi mã code: Lỗi.

Ghi chú của khách

GET /customers/{id}/notes

Danh sách ghi chú, mới nhất trước.

Quyền cần có: khoá có quyền pos.customers.read.

Tham số đường dẫn

Ví dụ yêu cầu

curl -X GET "https://danix.vn/api/open/v1/customers/{id}/notes" \
  -H "Authorization: Bearer dnx_live_…"

Thay {id} trong địa chỉ bằng mã thật của bản ghi, và dnx_live_… bằng khoá của bạn.

Phản hồi mẫu (200)

{
  "data": []
}

Trường của phản hồi

Lỗi

Định dạng lỗi và bảng mọi mã code: Lỗi.

Thêm ghi chú vào khách

POST /customers/{id}/notes

Ghi chú đứng tên ứng dụng kết nối.

Quyền cần có: khoá có quyền pos.customers.update.

Tham số đường dẫn

Thân yêu cầu (JSON)

Ví dụ yêu cầu

curl -X POST "https://danix.vn/api/open/v1/customers/{id}/notes" \
  -H "Authorization: Bearer dnx_live_…" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "Khách thích giao buổi tối"
}'

Thay {id} trong địa chỉ bằng mã thật của bản ghi, và dnx_live_… bằng khoá của bạn.

Phản hồi mẫu (201)

{
  "id": "018f3b8e-1c2d-7a4b-9c3d-000000000778",
  "message": "Khách thích giao buổi tối",
  "createdByName": "Đồng bộ kế toán",
  "createdByIsIntegration": true,
  "createdAt": "2026-10-02T03:15:00.000Z",
  "updatedAt": "2026-10-02T03:15:00.000Z"
}

Trường của phản hồi

Lỗi

Định dạng lỗi và bảng mọi mã code: Lỗi.