Khach hang

Quan ly ho so khach hang bao gom thong tin lien he, dia chi va tai khoan ngan hang.

Tham chieu nhanh

Endpoint	Method	Mo ta
`/api/v1/customers`	POST	Tao khach hang moi
`/api/v1/customers`	GET	Lay danh sach tat ca khach hang
`/api/v1/customers/:id`	GET	Lay thong tin khach hang cu the
`/api/v1/customers/:id`	PUT	Cap nhat khach hang
`/api/v1/customers/:id`	DELETE	Xoa khach hang

Cac endpoint API

Tao khach hang

Tao ban ghi khach hang moi.

POST /api/v1/customers

cURL
Go

curl -X POST 'https://api.finan.one/open/api/v1/customers' \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -H 'x-timestamp: 1699999999' \
  -d '{
    "general_info": {
      "name": "Nguyen Van B",
      "customer_code": "CUST20231122",
      "phone": "0933456789",
      "phone_code": "+84",
      "email": "[email protected]",
      "type": "personal",
      "tax_id": "123456789",
      "contact_persons": [
        {
          "name": "Jane Smith",
          "phone_number": "987654321",
          "email": "[email protected]"
        }
      ],
      "custom_tag": "VIP"
    },
    "address": {
      "country": "Vietnam",
      "province": "Ho Chi Minh",
      "district": "District 1",
      "ward": "Ben Thanh Ward",
      "address": "123 Le Loi Street",
      "zip_code": "100000"
    },
    "bank_accounts": [
      {
        "bank_code": "201",
        "bank_name": "Vietcombank",
        "account_holder_name": "Nguyen Van B",
        "account_number": "123456789012"
      }
    ]
  }'

package main

import (
    "bytes"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "strconv"
    "time"
)

type ContactPerson struct {
    Name        string `json:"name"`
    PhoneNumber string `json:"phone_number"`
    Email       string `json:"email"`
}

type GeneralInfo struct {
    Name           string          `json:"name"`
    CustomerCode   string          `json:"customer_code"`
    Phone          string          `json:"phone"`
    PhoneCode      string          `json:"phone_code"`
    Email          string          `json:"email,omitempty"`
    Type           string          `json:"type"`
    TaxID          string          `json:"tax_id,omitempty"`
    ContactPersons []ContactPerson `json:"contact_persons,omitempty"`
    CustomTag      string          `json:"custom_tag,omitempty"`
}

type Address struct {
    Country  string `json:"country,omitempty"`
    Province string `json:"province,omitempty"`
    District string `json:"district,omitempty"`
    Ward     string `json:"ward,omitempty"`
    Address  string `json:"address,omitempty"`
    ZipCode  string `json:"zip_code,omitempty"`
}

type BankAccount struct {
    BankCode          string `json:"bank_code"`
    BankName          string `json:"bank_name"`
    AccountHolderName string `json:"account_holder_name"`
    AccountNumber     string `json:"account_number"`
}

type CreateCustomerRequest struct {
    GeneralInfo  GeneralInfo   `json:"general_info"`
    Address      *Address      `json:"address,omitempty"`
    BankAccounts []BankAccount `json:"bank_accounts,omitempty"`
}

func generateSignature(secretKey, method, path, payload, timestamp string) string {
    message := secretKey + "_" + method + "_" + path + "_" + payload + "_" + timestamp
    hash := sha256.Sum256([]byte(message))
    return hex.EncodeToString(hash[:])
}

func main() {
    clientID := "YOUR_CLIENT_ID"
    secretKey := "YOUR_SECRET_KEY"
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)

    reqBody := CreateCustomerRequest{
        GeneralInfo: GeneralInfo{
            Name:         "Nguyen Van B",
            CustomerCode: "CUST20231122",
            Phone:        "0933456789",
            PhoneCode:    "+84",
            Email:        "[email protected]",
            Type:         "personal",
            TaxID:        "123456789",
            CustomTag:    "VIP",
        },
        Address: &Address{
            Country:  "Vietnam",
            Province: "Ho Chi Minh",
            District: "District 1",
            Ward:     "Ben Thanh Ward",
            Address:  "123 Le Loi Street",
            ZipCode:  "100000",
        },
        BankAccounts: []BankAccount{
            {
                BankCode:          "201",
                BankName:          "Vietcombank",
                AccountHolderName: "Nguyen Van B",
                AccountNumber:     "123456789012",
            },
        },
    }

    jsonBody, _ := json.Marshal(reqBody)
    signature := generateSignature(secretKey, "POST", "/api/v1/customers", string(jsonBody), timestamp)

    req, _ := http.NewRequest("POST", "https://api.finan.one/open/api/v1/customers", bytes.NewBuffer(jsonBody))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-client-id", clientID)
    req.Header.Set("x-signature", signature)
    req.Header.Set("x-timestamp", timestamp)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Noi dung request

general_info (bat buoc)

Truong	Kieu	Bat buoc	Mo ta
`name`	string	✅	Ho ten khach hang
`customer_code`	string	✅	Ma dinh danh khach hang duy nhat
`phone`	string	✅	So dien thoai
`phone_code`	string	✅	Ma quoc gia (vi du: `+84`)
`email`	string		Dia chi email
`type`	string	✅	`personal` hoac `company`
`tax_id`	string		Ma so thue
`contact_persons`	array		Nguoi lien he (bat buoc cho loai `company`)
`custom_tag`	string		Nhan tuy chinh (vi du: `VIP`)

contact_persons (bat buoc cho loai company)

Truong	Kieu	Bat buoc	Mo ta
`name`	string	✅	Ten nguoi lien he
`phone_number`	string	✅	So dien thoai lien he
`email`	string	✅	Email lien he

address (tuy chon)

Truong	Kieu	Mo ta
`country`	string	Quoc gia
`province`	string	Tinh/Thanh pho
`district`	string	Quan/Huyen
`ward`	string	Phuong/Xa
`address`	string	Dia chi duong
`zip_code`	string	Ma buu chinh

bank_accounts (tuy chon)

Truong	Kieu	Mo ta
`bank_code`	string	Ma ngan hang. Xem Tai lieu tham chieu ma
`bank_name`	string	Ten ngan hang
`account_holder_name`	string	Ten chu tai khoan
`account_number`	string	So tai khoan

Phan hoi

✅ Success (200)
❌ Error

{
  "message": { "content": "Thực thi API thành công" },
  "code": 102001,
  "request_id": "abc123...",
  "data": {
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "general_info": {
      "name": "Nguyen Van B",
      "customer_code": "CUST20231122",
      "phone": "0933456789",
      "email": "[email protected]",
      "type": "personal"
    },
    "address": {
      "country": "Vietnam",
      "province": "Ho Chi Minh",
      "district": "District 1"
    },
    "bank_accounts": [
      {
        "bank_code": "201",
        "bank_name": "Vietcombank",
        "account_number": "123456789012"
      }
    ],
    "created_at": "2024-01-20T14:00:00Z"
  }
}

Code	Message	Mo ta
400	`Bad Request`	Noi dung request khong hop le
401	`Unauthorized`	Xac thuc khong hop le
409	`Conflict`	Ma khach hang da ton tai
422	`Unprocessable Entity`	Xac thuc du lieu that bai

{
  "message": {
    "content": "Yêu cầu không hợp lệ",
    "error": "Customer code already exists"
  },
  "code": 104000,
  "request_id": "abc123..."
}

mẹo

Dam bao customer_code la duy nhat trong he thong cua ban de tranh cac ban ghi trung lap.

Lay danh sach khach hang

Truy xuat tat ca khach hang.

GET /api/v1/customers

cURL
Go

curl -X GET 'https://api.finan.one/open/api/v1/customers' \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -H 'x-timestamp: 1699999999'

package main

import (
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "io"
    "net/http"
    "strconv"
    "time"
)

func generateSignature(secretKey, method, path, payload, timestamp string) string {
    message := secretKey + "_" + method + "_" + path + "_" + payload + "_" + timestamp
    hash := sha256.Sum256([]byte(message))
    return hex.EncodeToString(hash[:])
}

func main() {
    clientID := "YOUR_CLIENT_ID"
    secretKey := "YOUR_SECRET_KEY"
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)

    signature := generateSignature(secretKey, "GET", "/api/v1/customers", "", timestamp)

    req, _ := http.NewRequest("GET", "https://api.finan.one/open/api/v1/customers", nil)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-client-id", clientID)
    req.Header.Set("x-signature", signature)
    req.Header.Set("x-timestamp", timestamp)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Phan hoi

✅ Success (200)
❌ Error

{
  "message": { "content": "Thực thi API thành công" },
  "code": 102000,
  "request_id": "abc123...",
  "data": [
    {
      "customer_id": "550e8400-e29b-41d4-a716-446655440000",
      "general_info": {
        "name": "Nguyen Van B",
        "customer_code": "CUST20231122",
        "type": "personal"
      },
      "created_at": "2024-01-20T14:00:00Z"
    }
  ]
}

Code	Message	Mo ta
401	`Unauthorized`	Xac thuc khong hop le

Lay mot khach hang

GET /api/v1/customers/:customer_id

Cap nhat khach hang

Thay the du lieu cua khach hang hien tai. Day la thao tac thay the toan bo -- tat ca cac truong bat buoc phai duoc bao gom, va cac truong tuy chon bi bo qua se bi xoa.

PUT /api/v1/customers/:customer_id

Thay the toan bo, khong phai cap nhat mot phan

Ban phai bao gom general_info.type va tat ca cac truong ban muon giu lai. Cac truong khong duoc bao gom (vi du: address, bank_accounts) se bi dat lai thanh trong.

cURL
Go

curl -X PUT 'https://api.finan.one/open/api/v1/customers/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -H 'x-timestamp: 1699999999' \
  -d '{
    "general_info": {
      "name": "Updated Customer Name",
      "customer_code": "CUST20231122",
      "phone": "0933456789",
      "phone_code": "+84",
      "email": "[email protected]",
      "type": "personal",
      "custom_tag": "Priority Customer"
    },
    "address": {
      "country": "Vietnam",
      "province": "Ho Chi Minh"
    }
  }'

package main

import (
    "bytes"
    "crypto/sha256"
    "encoding/hex"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "strconv"
    "time"
)

type UpdateCustomerRequest struct {
    GeneralInfo map[string]interface{} `json:"general_info,omitempty"`
    Address     map[string]interface{} `json:"address,omitempty"`
}

func generateSignature(secretKey, method, path, payload, timestamp string) string {
    message := secretKey + "_" + method + "_" + path + "_" + payload + "_" + timestamp
    hash := sha256.Sum256([]byte(message))
    return hex.EncodeToString(hash[:])
}

func main() {
    clientID := "YOUR_CLIENT_ID"
    secretKey := "YOUR_SECRET_KEY"
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)
    customerID := "550e8400-e29b-41d4-a716-446655440000"

    reqBody := UpdateCustomerRequest{
        GeneralInfo: map[string]interface{}{
            "name":       "Updated Customer Name",
            "email":      "[email protected]",
            "custom_tag": "Priority Customer",
        },
    }

    jsonBody, _ := json.Marshal(reqBody)
    path := "/api/v1/customers/" + customerID
    signature := generateSignature(secretKey, "PUT", path, string(jsonBody), timestamp)

    url := "https://api.finan.one/open/api/v1/customers/" + customerID
    req, _ := http.NewRequest("PUT", url, bytes.NewBuffer(jsonBody))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-client-id", clientID)
    req.Header.Set("x-signature", signature)
    req.Header.Set("x-timestamp", timestamp)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Phan hoi

✅ Success (200)
❌ Error

{
  "message": { "content": "Thực thi API thành công" },
  "code": 102000,
  "request_id": "abc123...",
  "data": {
    "customer_id": "550e8400-e29b-41d4-a716-446655440000",
    "general_info": {
      "name": "Updated Customer Name",
      "email": "[email protected]"
    },
    "updated_at": "2024-01-21T10:00:00Z"
  }
}

Code	Message	Mo ta
401	`Unauthorized`	Xac thuc khong hop le
404	`Not Found`	Khong tim thay khach hang
422	`Unprocessable Entity`	Xac thuc du lieu that bai

Xoa khach hang

Xoa ban ghi khach hang.

DELETE /api/v1/customers/:customer_id

cURL
Go

curl -X DELETE 'https://api.finan.one/open/api/v1/customers/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -H 'x-timestamp: 1699999999'

package main

import (
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "io"
    "net/http"
    "strconv"
    "time"
)

func generateSignature(secretKey, method, path, payload, timestamp string) string {
    message := secretKey + "_" + method + "_" + path + "_" + payload + "_" + timestamp
    hash := sha256.Sum256([]byte(message))
    return hex.EncodeToString(hash[:])
}

func main() {
    clientID := "YOUR_CLIENT_ID"
    secretKey := "YOUR_SECRET_KEY"
    timestamp := strconv.FormatInt(time.Now().Unix(), 10)
    customerID := "550e8400-e29b-41d4-a716-446655440000"

    path := "/api/v1/customers/" + customerID
    signature := generateSignature(secretKey, "DELETE", path, "", timestamp)

    url := "https://api.finan.one/open/api/v1/customers/" + customerID
    req, _ := http.NewRequest("DELETE", url, nil)
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("x-client-id", clientID)
    req.Header.Set("x-signature", signature)
    req.Header.Set("x-timestamp", timestamp)

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Phan hoi

✅ Success (200)
❌ Error

{
  "message": { "content": "Thực thi API thành công" },
  "code": 102001,
  "request_id": "abc123...",
  "data": "success"
}

Code	Message	Mo ta
401	`Unauthorized`	Xac thuc khong hop le
404	`Not Found`	Khong tim thay khach hang
409	`Conflict`	Khach hang con hoa don dang hoat dong

Phu thuoc

Viec xoa co the that bai neu khach hang con hoa don chua thanh toan hoac hop dong dang hoat dong. Hay giai quyet cac phu thuoc truoc.

Buoc tiep theo

San pham - Quan ly danh muc san pham
Hoa don - Tao hoa don cho khach hang
Tai lieu tham chieu ma - Ma ngan hang

Tham chieu nhanh​

Cac endpoint API​

Tao khach hang​

Noi dung request​

Phan hoi​

Lay danh sach khach hang​

Phan hoi​

Cap nhat khach hang​

Phan hoi​

Xoa khach hang​

Phan hoi​

Buoc tiep theo​

Tham chieu nhanh

Cac endpoint API

Tao khach hang

Noi dung request

Phan hoi

Lay danh sach khach hang

Phan hoi

Cap nhat khach hang

Phan hoi

Xoa khach hang

Phan hoi

Buoc tiep theo