Hoa don

Tao va quan ly hoa don voi xu ly thanh toan tich hop.

Invoice Flow

Tham chieu nhanh

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

Cac endpoint API

Tao hoa don

Tao hoa don moi voi san pham, khach hang va phuong thuc thanh toan.

POST /api/v1/invoices

cURL
Go

curl -X POST 'https://api.finan.one/open/api/v1/invoices' \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -H 'x-timestamp: 1699999999' \
  -d '{
    "invoice_code": "INV12345",
    "transaction_date": "2024-11-22T10:00:00Z",
    "due_date": "2024-11-29T10:00:00Z",
    "items": [
      {
        "code": "PRD0001",
        "tax_code": "TAX_CODE_10",
        "unit_price": 100000,
        "quantity": 2,
        "note": "note for product"
      }
    ],
    "tax_type": "price_excluding_tax",
    "discount": {
      "is_percentage": false,
      "value": 10000
    },
    "customer": {
      "code": "CUST123",
      "email": "[email protected]"
    },
    "note": "This is a note for the invoice",
    "payment_methods": ["bank_transfer", "card", "ewallet_momo"],
    "account_id": "54957437-0cb5-4992-ad0e-76d26ba4ddc3"
  }'

package main

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

type InvoiceItem struct {
    Code      string `json:"code"`
    TaxCode   string `json:"tax_code"`
    UnitPrice int64  `json:"unit_price,omitempty"`
    Quantity  int    `json:"quantity"`
    Note      string `json:"note,omitempty"`
}

type Discount struct {
    IsPercentage bool    `json:"is_percentage"`
    Value        float64 `json:"value"`
}

type InvoiceCustomer struct {
    Code  string `json:"code"`
    Email string `json:"email,omitempty"`
}

type CreateInvoiceRequest struct {
    InvoiceCode     string          `json:"invoice_code"`
    TransactionDate string          `json:"transaction_date"`
    DueDate         string          `json:"due_date"`
    Items           []InvoiceItem   `json:"items"`
    TaxType         string          `json:"tax_type"`
    Discount        *Discount       `json:"discount,omitempty"`
    Customer        InvoiceCustomer `json:"customer"`
    Note            string          `json:"note,omitempty"`
    PaymentMethods  []string        `json:"payment_methods"`
    AccountID       string          `json:"account_id,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 := CreateInvoiceRequest{
        InvoiceCode:     "INV12345",
        TransactionDate: "2024-11-22T10:00:00Z",
        DueDate:         "2024-11-29T10:00:00Z",
        Items: []InvoiceItem{
            {
                Code:      "PRD0001",
                TaxCode:   "TAX_CODE_10",
                UnitPrice: 100000,
                Quantity:  2,
                Note:      "note for product",
            },
        },
        TaxType: "price_excluding_tax",
        Discount: &Discount{
            Type:  "amount",
            Value: 10000,
        },
        Customer: InvoiceCustomer{
            Code:  "CUST123",
            Email: "[email protected]",
        },
        Note:           "This is a note for the invoice",
        PaymentMethods: []string{"bank_transfer", "card", "ewallet_momo"},
        AccountID:      "54957437-0cb5-4992-ad0e-76d26ba4ddc3",
    }

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

    req, _ := http.NewRequest("POST", "https://api.finan.one/open/api/v1/invoices", 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

Truong	Kieu	Bat buoc	Mo ta
`invoice_code`	string	✅	Ma hoa don duy nhat
`transaction_date`	datetime	✅	Ngay giao dich (ISO 8601)
`due_date`	datetime	✅	Ngay den han thanh toan (ISO 8601)
`tax_type`	string	✅	`price_excluding_tax`, `price_including_tax`, hoac `tax_not_applicable`
`items`	array	✅	Danh sach san pham/dich vu
`customer`	object	✅	Thong tin khach hang
`discount`	object		Cau hinh giam gia
`note`	string		Ghi chu hoa don
`payment_methods`	array	✅	Phuong thuc thanh toan chap nhan: `bank_transfer`, `card`, `ewallet_momo`
`account_id`	uuid		Bat buoc cho `bank_transfer` toi Shinhan. Lay tu API Tai khoan

items[]

Truong	Kieu	Bat buoc	Mo ta
`code`	string	✅	Ma SKU san pham
`tax_code`	string	✅	Ma thue. Xem Tai lieu tham chieu ma
`unit_price`	integer		Gia moi don vi (su dung gia san pham neu de trong)
`quantity`	integer	✅	So luong
`note`	string		Ghi chu muc

discount

Truong	Kieu	Mo ta
`is_percentage`	boolean	`false` cho so tien co dinh, `true` cho phan tram
`value`	float	Gia tri giam gia (toi da 2 chu so thap phan)

customer

Truong	Kieu	Bat buoc	Mo ta
`code`	string	✅	Ma khach hang (phai ton tai trong he thong)
`email`	string		Ghi de email chi cho hoa don nay

Phan hoi

✅ Success (200)
❌ Error

{
  "message": { "content": "Thực thi API thành công" },
  "code": 102001,
  "request_id": "abc123...",
  "data": {
    "invoice_id": "INV-550e8400-e29b-41d4-a716-446655440000",
    "invoice_code": "INV12345",
    "transaction_date": "2024-11-22T10:00:00Z",
    "due_date": "2024-11-29T10:00:00Z",
    "tax_type": "price_excluding_tax",
    "total_amount": 220000,
    "total_tax_amount": 20000,
    "total_discount_amount": 10000,
    "paid_amount": 0,
    "unpaid_amount": 220000,
    "items": [
      {
        "code": "PRD0001",
        "name": "Product Name",
        "quantity": 2,
        "unit_price": 100000,
        "amount": 200000
      }
    ],
    "customer": {
      "code": "CUST123",
      "name": "Customer Name",
      "email": "[email protected]"
    },
    "payment_link": "https://book.finan.one/pay/520/invoice/INV12345",
    "created_at": "2024-11-22T12:00:00Z"
  }
}

Code	Message	Mo ta
400	`Bad Request`	Noi dung request khong hop le
401	`Unauthorized`	Xac thuc khong hop le
404	`Not Found`	Khong tim thay khach hang hoac san pham
409	`Conflict`	Ma hoa don 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 with code CUST123 not found"
  },
  "code": 104000,
  "request_id": "abc123..."
}

Lien ket thanh toan

Chia se payment_link voi khach hang cua ban de thanh toan de dang. Ho tro tat ca cac phuong thuc thanh toan da cau hinh.

Lay danh sach hoa don

Truy xuat tat ca hoa don.

GET /api/v1/invoices

cURL
Go

curl -X GET 'https://api.finan.one/open/api/v1/invoices' \
  -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/invoices", "", timestamp)

    req, _ := http.NewRequest("GET", "https://api.finan.one/open/api/v1/invoices", 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": [
    {
      "invoice_id": "INV-550e8400-e29b-41d4-a716-446655440000",
      "invoice_code": "INV12345",
      "transaction_date": "2024-11-22T10:00:00Z",
      "due_date": "2024-11-29T10:00:00Z",
      "total_amount": 220000,
      "paid_amount": 220000,
      "unpaid_amount": 0,
      "payment_link": "https://book.finan.one/pay/520/invoice/INV12345",
      "created_at": "2024-11-22T12:00:00Z"
    }
  ]
}

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

Lay mot hoa don

GET /api/v1/invoices/:invoice_id

Lay yeu cau thanh toan cho hoa don

De truy xuat cac yeu cau thanh toan cho hoa don, su dung API Thanh toan voi bo loc:

curl -X GET 'https://api.finan.one/open/api/v1/payments?reference_type=invoice&reference_id=INV-550e8400' \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -H 'x-timestamp: 1699999999'

Cap nhat hoa don

Cap nhat hoa don hien tai voi cac muc moi, giam gia, ngay den han hoac email khach hang.

PUT /api/v1/invoices/:invoice_id

cURL
Go

curl -X PUT 'https://api.finan.one/open/api/v1/invoices/INVOICE_ID' \
  -H 'Content-Type: application/json' \
  -H 'x-client-id: YOUR_CLIENT_ID' \
  -H 'x-signature: YOUR_SIGNATURE' \
  -H 'x-timestamp: 1699999999' \
  -d '{
    "due_date": "2024-11-29T10:00:00Z",
    "items": [
      {
        "code": "PRD0001",
        "tax_code": "TAX_CODE_10",
        "unit_price": 100000,
        "quantity": 2,
        "note": "note for product"
      }
    ],
    "discount": {
      "is_percentage": false,
      "value": 120000
    },
    "customer": {
      "email": "[email protected]"
    },
    "note": "This is note of invoice"
  }'

package main

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

type UpdateInvoiceItem struct {
    Code      string `json:"code"`
    TaxCode   string `json:"tax_code"`
    UnitPrice int64  `json:"unit_price,omitempty"`
    Quantity  int    `json:"quantity"`
}

type Discount struct {
    IsPercentage bool    `json:"is_percentage"`
    Value        float64 `json:"value"`
}

type UpdateCustomer struct {
    Email string `json:"email,omitempty"`
}

type UpdateInvoiceRequest struct {
    DueDate  string              `json:"due_date,omitempty"`
    Items    []UpdateInvoiceItem `json:"items,omitempty"`
    Discount *Discount           `json:"discount,omitempty"`
    Customer *UpdateCustomer     `json:"customer,omitempty"`
    Note     string              `json:"note,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)
    invoiceID := "INV-550e8400-e29b-41d4-a716-446655440000"

    reqBody := UpdateInvoiceRequest{
        DueDate: "2024-12-05T10:00:00Z",
        Items: []UpdateInvoiceItem{
            {
                Code:      "PRD0001",
                TaxCode:   "TAX_CODE_10",
                UnitPrice: 100000,
                Quantity:  3,
            },
        },
        Note: "Updated invoice note",
    }

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

    url := "https://api.finan.one/open/api/v1/invoices/" + invoiceID
    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))
}

Cac truong co the cap nhat

Truong	Kieu	Mo ta
`due_date`	datetime	Ngay den han da cap nhat
`items`	array	Danh sach muc da cap nhat
`discount`	object	Giam gia da cap nhat
`customer.email`	string	Ghi de email khach hang
`note`	string	Ghi chu hoa don

Phan hoi

✅ Success (200)
❌ Error

{
  "message": { "content": "Thực thi API thành công" },
  "code": 102000,
  "request_id": "abc123...",
  "data": {
    "invoice_id": "INV-550e8400-e29b-41d4-a716-446655440000",
    "invoice_code": "INV12345",
    "due_date": "2024-12-05T10:00:00Z",
    "total_amount": 330000,
    "updated_at": "2024-11-23T10:00:00Z"
  }
}

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

Xoa hoa don

Xoa mot hoa don.

DELETE /api/v1/invoices/:invoice_id

cURL
Go

curl -X DELETE 'https://api.finan.one/open/api/v1/invoices/INV-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)
    invoiceID := "INV-550e8400-e29b-41d4-a716-446655440000"

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

    url := "https://api.finan.one/open/api/v1/invoices/" + invoiceID
    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 hoa don

Yeu cau thanh toan

Neu hoa don co cac yeu cau thanh toan, chung van hoat dong sau khi xoa. Ban van co the truy van thanh toan bang reference_type=invoice va reference_id.

Buoc tiep theo

Thanh toan - Tao yeu cau thanh toan cho hoa don
Khach hang - Quan ly ho so khach hang
San pham - Quan ly danh muc san pham

Tham chieu nhanh​

Cac endpoint API​

Tao hoa don​

Noi dung request​

Phan hoi​

Lay danh sach hoa don​

Phan hoi​

Lay yeu cau thanh toan cho hoa don​

Cap nhat hoa don​

Cac truong co the cap nhat​

Phan hoi​

Xoa hoa don​

Phan hoi​

Buoc tiep theo​

Tham chieu nhanh

Cac endpoint API

Tao hoa don

Noi dung request

Phan hoi

Lay danh sach hoa don

Phan hoi

Lay yeu cau thanh toan cho hoa don

Cap nhat hoa don

Cac truong co the cap nhat

Phan hoi

Xoa hoa don

Phan hoi

Buoc tiep theo