Skip to main content

Đặc tả API

Quy định chung​

  • Các API được cung cấp sẽ sử dụng phương thức chung là REST API với kiểu dữ liệu mặc định là json. Ngoài ra nếu đối tác muốn sử dụng kiểu dữ liệu khác thì có thẻ sử Header khác.
    • Ví dụ: Content-Type: application/xml
Thông tin

Các đặc tả được viết sẽ sử dụng json

  • Các API sẽ có các thông số như sau: Endpoint, Header, Dữ liệu truyền lên, Dữ liệu trả về.

Mã HTTP (HTTP Status)​

  • Đối với các yêu cầu thành công sẽ trả về HTTP_Status là 2XX với chi tiết bảng mã sau đây:

    HTTP StatusTênMô tả
    200OKYêu cầu được thực hiện thành công. Dữ liệu trả về trong RespondBody
    201CREATEDYêu cầu tạo tài nguyên thành công. Thông tin được trả về trong RespondBody
    202ACCEPTEDYêu cầu được chấp thuận, tuy nhiên server chưa thực thi xong, dữ liệu về kết quả yêu cầu sẽ được trả về dưới dạng callback hoặc bằng một API khác

  • Đối với các yêu cầu bị lỗi từ phía bên gọi (client) thì sẽ trả về HTTP_Status là 4XX

    HTTP StatusTênMô tả
    400Bad RequestLỗi dữ liệu truyền lên không đúng định dạng trong đặc tả hoặc bị trùng lặp, xem errorCode hoặc errorMessage để thông tin thêm
    401UnauthorizedKhông xác định được người dùng/client. Nguyên nhân do thiếu Token hoặc token hết hạn. Hoặc MERCHANT_CODE và MERCHANT_SECRET không khớp
    403ForbiddenNgười dùng/client không có quyền truy cập tài nguyên này. Hoặc Merchant bị ban do gọi sai xác thực quá nhiều lần.
    404Not FoundTài nguyên/endpoint này không tồn tại.
    413Entity Too LargeDữ liệu truyền lên quá lớn.
    415Unsupported Media TypeKhông hỗ trợ kiểu định đạng dữ liệu này.

  • Đối với các lỗi từ phía server, HTTP Status là 5XX . Đối với các lỗi này, yêu cầu đối tác liên hệ lại với support kỹ thuật để khắc phục

Dữ liệu trả về​

  • Thông thường với mã lỗi thành công 2XX dữ liệu sẽ được trả về theo đúng định dạng trong từ đặc tả của API. VD:
        {
            "bearerToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.u9aiDQrGQ12HQZFb-oOyP5dbSmfnMC9bsPnU7GywhaQ",
            "expire": 1634281710
        }

  • Đối với yêu cầu lỗi, dữ liệu trả về sẽ có định dạng:

    Tên trườngMô tảKiểu dữ liệu
    errorCodeMã code với những yêu cầu mà client không thể kiểm tra trước khi gửi yêu cầu được. VD: trùng số CMT, email....Number
    errorMessageThông tin diễn giải mã lỗi, thường dành cho dev để kiểm chứng trước khi gửi yêu cầuText