API địa điểm kinh doanh người bán

Quản lý danh mục địa điểm kinh doanh người bán (mã số, tên, địa chỉ) qua SePay eInvoice API. Tạo, sửa, xóa địa điểm và lấy ID để truyền mã số và tên địa điểm lên hóa đơn điện tử.

||
Luồng sử dụng
  1. Gọi API tạo địa điểm để thêm địa điểm, nhận xid.
  2. Truyền xid đó vào trường seller_store_xid khi Xuất hóa đơn điện tử.
  3. Có thể lọc hóa đơn theo địa điểm và xem địa điểm trong chi tiết hóa đơn.

API danh sách địa điểm

Lấy danh sách địa điểm kinh doanh của công ty.

GET
https://einvoice-api.sepay.vn/v1/business-locations
Response thành công (200)
{
  "success": true,
  "data": [
    {
      "xid": "8f14e45f-ceea-4b6d-9c1a-2b3c4d5e6f70",
      "code": "CN01",
      "name": "Chi nhánh 1",
      "address": "12 Đường Ánh Sao, Quận 9, TP.HCM",
      "is_used": true,
      "is_active": true
    },
    {
      "xid": "3c59dc04-8e88-4506-b12a-9f3d1e7c5a21",
      "code": "HQ",
      "name": "Trụ sở chính",
      "address": "1 Đường Ban Mai, Quận 9, TP.HCM",
      "is_used": false,
      "is_active": true
    }
  ]
}
successboolean
dataarray<object>
>
>
>
curl --request GET \
  --url https://einvoice-api.sepay.vn/v1/business-locations \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

API tạo địa điểm

Thêm một địa điểm mới vào danh mục. Địa điểm mới ở trạng thái đang bật (is_active=true).

POST
https://einvoice-api.sepay.vn/v1/business-locations/create
codestringrequired

Mã số địa điểm kinh doanh, tối đa 50 ký tự. Là định danh cố định - đặt khi tạo và không sửa được. Duy nhất trong công ty, trùng trả lỗi SELLER_STORE_DUPLICATE_CODE.

namestringrequired

Tên địa điểm kinh doanh theo giấy chứng nhận đăng ký kinh doanh, tối đa 400 ký tự. Duy nhất trong công ty, trùng trả lỗi SELLER_STORE_DUPLICATE_NAME.

addressstringrequired

Địa chỉ địa điểm kinh doanh, tối đa 255 ký tự. Duy nhất trong công ty, trùng trả lỗi SELLER_STORE_DUPLICATE_ADDRESS.

Response thành công (201)
{
  "success": true,
  "data": {
    "xid": "b6d767d2-f8ed-4c1b-9a2e-7f5c3d1a8b40",
    "code": "CN02",
    "name": "Chi nhánh 2",
    "address": "34 Đường Hoa Nắng, Quận 7, TP.HCM",
    "is_used": false,
    "is_active": true
  }
}
successboolean
dataobject
>
>
>
>
>
curl --request POST \
  --url https://einvoice-api.sepay.vn/v1/business-locations/create \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"code":"CN02","name":"Chi nhánh 2","address":"34 Đường Hoa Nắng, Quận 7, TP.HCM"}'

API cập nhật địa điểm

Sửa tên, địa chỉ hoặc kích hoạt/hủy kích hoạt một địa điểm. Địa điểm đã dùng để xuất hóa đơn vẫn sửa được bình thường, hóa đơn đã xuất không bị ảnh hưởng.

POST
https://einvoice-api.sepay.vn/v1/business-locations/update
xidstringrequired

Mã định danh (xid, dạng UUID) của địa điểm cần cập nhật, lấy từ API danh sách địa điểm.

namestring

Tên mới, tối đa 400 ký tự, duy nhất trong công ty. Không bắt buộc - chỉ gửi khi muốn đổi tên, không gửi giữ nguyên tên cũ. Gửi nhưng để rỗng sẽ bị từ chối.

addressstring

Địa chỉ mới, tối đa 255 ký tự, duy nhất trong công ty. Không bắt buộc - chỉ gửi khi muốn đổi địa chỉ, không gửi giữ nguyên địa chỉ cũ. Gửi nhưng để rỗng sẽ bị từ chối.

is_activeboolean

Kích hoạt (true) hoặc hủy kích hoạt (false) địa điểm. Địa điểm bị hủy kích hoạt không dùng để xuất hóa đơn mới nhưng hóa đơn cũ đã gắn vẫn tra cứu được.

Response thành công (200)
{
  "success": true,
  "data": {
    "xid": "b6d767d2-f8ed-4c1b-9a2e-7f5c3d1a8b40",
    "code": "CN02",
    "name": "Chi nhánh 2 - Quận 3",
    "address": "58 Đường Trăng Thanh, Quận 3, TP.HCM",
    "is_used": false,
    "is_active": true
  }
}
>
>
>
>
>
curl --request POST \
  --url https://einvoice-api.sepay.vn/v1/business-locations/update \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"xid":"b6d767d2-f8ed-4c1b-9a2e-7f5c3d1a8b40","name":"Chi nhánh 2 - Quận 3","address":"58 Đường Trăng Thanh, Quận 3, TP.HCM","is_active":false}'

API xóa địa điểm

Xóa một địa điểm khỏi danh mục. Chỉ xóa được địa điểm chưa từng dùng để xuất hóa đơn.

POST
https://einvoice-api.sepay.vn/v1/business-locations/delete
xidstringrequired

Mã định danh (xid, dạng UUID) của địa điểm cần xóa, lấy từ API danh sách địa điểm. Chỉ xóa được địa điểm chưa dùng để xuất hóa đơn - địa điểm đã dùng hãy hủy kích hoạt (is_active=false) thay vì xóa.

Response thành công (200)
{
  "success": true,
  "message": "Đã xóa địa điểm kinh doanh người bán"
}
>
>
>
>
>
curl --request POST \
  --url https://einvoice-api.sepay.vn/v1/business-locations/delete \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"xid":"b6d767d2-f8ed-4c1b-9a2e-7f5c3d1a8b40"}'

Xử lý lỗi

Các endpoint địa điểm trả lỗi theo cấu trúc { "success": false, "error": { "code": "...", "message": "..." } }.

401UNAUTHORIZED

Thiếu hoặc sai Bearer token.

422VALIDATION_ERROR

Thiếu trường bắt buộc, vượt quá độ dài, hoặc không có thông tin nào để cập nhật.

422SELLER_STORE_DUPLICATE_CODE

Mã số địa điểm đã tồn tại trong công ty (chỉ khi tạo).

422SELLER_STORE_DUPLICATE_NAME

Tên địa điểm đã tồn tại trong công ty.

422SELLER_STORE_DUPLICATE_ADDRESS

Địa chỉ đã tồn tại trong danh mục công ty.

404SELLER_STORE_NOT_FOUND

Địa điểm không tồn tại hoặc không thuộc tài khoản của bạn (khi cập nhật/xóa).

409SELLER_STORE_IN_USE

Địa điểm đã được dùng để xuất hóa đơn nên không thể xóa - hãy hủy kích hoạt (is_active=false) thay vì xóa.

405METHOD_NOT_ALLOWED

Gọi sai HTTP method của endpoint.

500INTERNAL_ERROR

Đã có lỗi xảy ra, vui lòng liên hệ SePay để được hỗ trợ.

Về is_used và is_active
  • is_used=true: địa điểm đã được dùng để xuất ít nhất một hóa đơn. Địa điểm này không xóa được nhưng vẫn sửa tên, địa chỉ và kích hoạt/hủy kích hoạt (is_active) bình thường.
  • is_active=false: địa điểm đã bị hủy kích hoạt, không chọn được khi xuất hóa đơn mới (API xuất hóa đơn trả 400 SELLER_STORE_INACTIVE), nhưng các hóa đơn đã gắn trước đó vẫn lọc và tra cứu được.

Bước tiếp theo

Sau khi có xid của địa điểm, bạn có thể:

  1. Xuất hóa đơn điện tử - Gắn seller_store_xid để truyền mã số và tên địa điểm lên hóa đơn.
  2. Danh sách hóa đơn - Lọc hóa đơn theo seller_store_xid.
Trước
—
Tiếp theo
—